115 lines
6.9 KiB
Markdown
115 lines
6.9 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common.DAS.Concepts/DAS/Channel/LevelTriggerTypes.cs
|
||
- Common/DTS.Common.DAS.Concepts/DAS/Channel/Channel.cs
|
||
- Common/DTS.Common.DAS.Concepts/DAS/Channel/TimestampPartTypes.cs
|
||
- Common/DTS.Common.DAS.Concepts/DAS/Channel/Data.cs
|
||
generated_at: "2026-04-16T02:05:03.519331+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "0f3b00d01b342d9f"
|
||
---
|
||
|
||
# Channel
|
||
|
||
## Documentation: DAS Channel Concepts Module
|
||
|
||
---
|
||
|
||
### 1. Purpose
|
||
This module defines core conceptual types used to represent data acquisition system (DAS) channel behavior and data structures within the DTS Common library. It provides foundational enums (`LevelTriggerTypes`, `TimestampPartTypes`) for configuring trigger conditions and interpreting timestamp components, and abstract base classes (`Channel<TDataType>`, `Data<TDatumType>`) that serve as the basis for concrete channel and data implementations in the DAS subsystem. The module exists to standardize how channel-level logic (e.g., threshold triggers) and data containers are modeled internally, decoupling high-level application logic (e.g., slice control app) from hardware-specific implementations.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### Enums
|
||
- **`LevelTriggerTypes`** (`[Flags]` enum)
|
||
Represents configurable trigger conditions for a channel. Values are bit flags:
|
||
- `NONE = 0x00`: No trigger condition.
|
||
- `OutsideWindow = 0x01`: Trigger when value is outside a specified window.
|
||
- `InsideWindow = 0x02`: Trigger when value is inside a specified window.
|
||
- `LessThan = 0x04`: Trigger when value is less than a threshold.
|
||
- `GreaterThan = 0x08`: Trigger when value is greater than a threshold.
|
||
*Note:* Combinations (e.g., `LessThan | GreaterThan`) are valid per `[Flags]` semantics, though semantic validity (e.g., `OutsideWindow` + `InsideWindow`) is not enforced here.
|
||
|
||
- **`TimestampPartTypes`** (`[Flags]` enum with `[Description]` attributes)
|
||
Represents components of a timestamp, typically used for parsing or reconstructing high-precision timestamps. Values are bit flags:
|
||
- `Marker = 1 << 0` (value `1`): A marker bit (description: `"Marker"`).
|
||
- `Seconds_High = 1 << 1` (value `2`): High-order bits of seconds (description: `"Seconds"`).
|
||
- `Seconds_Low = 1 << 2` (value `4`): Low-order bits of seconds (description: `"Seconds"`).
|
||
- `Nanoseconds_High = 1 << 3` (value `8`): High-order bits of nanoseconds (description: `"Nanoseconds"`).
|
||
- `Nanoseconds_Low = 1 << 4` (value `16`): Low-order bits of nanoseconds (description: `"Nanoseconds"`).
|
||
- `Reserved = 1 << 5` (value `32`): Reserved bit (description: `"Reserved"`).
|
||
*Note:* `Seconds_High` and `Seconds_Low` share the same description `"Seconds"`; similarly for nanosecond components.
|
||
|
||
#### Abstract Classes
|
||
- **`Channel<TDataType>`**
|
||
Abstract base class representing a DAS channel in the slice control app. Inherits from `Exceptional` (from `DTS.Common.Utilities`).
|
||
- *Generic parameter:* `TDataType` specifies the type of data the channel carries (e.g., `double`, `int`, custom struct).
|
||
- *Behavior:* No public methods or properties defined in this source; intended as a base for concrete channel implementations (e.g., `AnalogChannel`, `DigitalChannel`).
|
||
|
||
- **`Data<TDatumType>`**
|
||
Abstract base class representing a list of channel data samples. Inherits from `ExceptionalList<TDatumType>` (from `DTS.Common.Utilities`).
|
||
- *Generic parameter:* `TDatumType` specifies the type of individual data samples (e.g., `double`, `SampleRecord`).
|
||
- *Constructors:*
|
||
- `protected Data()`: Default constructor.
|
||
- `protected Data(int capacity)`: Constructor with initial list capacity.
|
||
- `protected Data(IEnumerable<TDatumType> collection)`: Constructor that copies elements from a collection.
|
||
- *Behavior:* Provides no additional functionality beyond its base list class; intended as a base for concrete data container implementations (e.g., `SampleData`, `EventList`).
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- **`LevelTriggerTypes`**:
|
||
- Values are strictly bit flags (`0x00`, `0x01`, `0x02`, `0x04`, `0x08`).
|
||
- Valid combinations must be powers-of-two or bitwise ORs thereof.
|
||
- No validation is performed on combinations (e.g., `OutsideWindow | InsideWindow` is syntactically valid but semantically ambiguous).
|
||
|
||
- **`TimestampPartTypes`**:
|
||
- Values are strictly bit flags with explicit bit positions (bits 0–5).
|
||
- `Seconds_High` and `Seconds_Low` are distinct flags despite sharing a description; similarly for `Nanoseconds_High`/`Low`.
|
||
- The `Reserved` flag is defined but its usage is unspecified.
|
||
|
||
- **`Channel<TDataType>` and `Data<TDatumType>`**:
|
||
- Both are abstract; direct instantiation is impossible.
|
||
- No invariants are enforced in the provided source (e.g., no validation of `TDatumType` constraints).
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
|
||
#### This module depends on:
|
||
- `DTS.Common.Utilities`:
|
||
- Provides `Exceptional` (base class for `Channel<TDataType>`).
|
||
- Provides `ExceptionalList<T>` (base class for `Data<TDatumType>`).
|
||
- `System`:
|
||
- Core types (`System.FlagsAttribute`, `System.ComponentModel.DescriptionAttribute`, `System.ComponentModel.TypeConverterAttribute`).
|
||
- `DTS.Common.Converters`:
|
||
- Provides `EnumDescriptionTypeConverter` for `TimestampPartTypes`.
|
||
|
||
#### This module is depended on by:
|
||
- **Inferred consumers**:
|
||
- Any code referencing `DTS.Common.DAS.Concepts.DAS.Channel` namespace (e.g., concrete channel implementations, trigger logic, timestamp parsers).
|
||
- The `slice control app` (explicitly mentioned in `Channel<TDataType>` summary) is a direct consumer.
|
||
- Serialization/deserialization logic likely uses `TimestampPartTypes` (given `TypeConverter` attribute).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **`LevelTriggerTypes` combinations**:
|
||
- `OutsideWindow` and `InsideWindow` are mutually exclusive in practice but not enforced. Combining them (`OutsideWindow | InsideWindow = 0x03`) may lead to undefined behavior in downstream logic.
|
||
- `LessThan` and `GreaterThan` can be combined (e.g., for hysteresis), but this is not documented.
|
||
|
||
- **`TimestampPartTypes` descriptions**:
|
||
- `Seconds_High` and `Seconds_Low` share the same `[Description("Seconds")]`; UI/tooling relying solely on `DescriptionAttribute` may not distinguish them.
|
||
- `Reserved` flag is defined but its purpose is unspecified—avoid using it unless documented elsewhere.
|
||
|
||
- **Abstract base classes**:
|
||
- `Channel<TDataType>` and `Data<TDatumType>` provide no implementation details beyond inheritance. Behavior (e.g., thread safety, sample ordering) must be inferred from concrete subclasses.
|
||
- `Data<TDatumType>` inherits from `ExceptionalList<T>`, but no information about `ExceptionalList<T>`’s behavior (e.g., exception handling semantics) is provided here.
|
||
|
||
- **No versioning or deprecation markers**:
|
||
- No attributes (e.g., `[Obsolete]`) or version comments indicate deprecated/legacy usage patterns.
|
||
|
||
*None identified from source alone.* |