noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
365ebdecbd94c65939f38bd270147e5dc6af3a75
DP44/enriched-qwen3-coder-next/DataPRO/SLICECommands.md

305 lines
16 KiB
Markdown
Raw Normal View History

init
2026-04-17 14:55:32 -04:00
---
source_files:
- DataPRO/SLICECommands/StackSetupCommands.cs
- DataPRO/SLICECommands/CommandBase.cs
- DataPRO/SLICECommands/CommandPacket.cs
- DataPRO/SLICECommands/StackUtilityCommands.cs
- DataPRO/SLICECommands/FirmwareUpdateCommands.cs
- DataPRO/SLICECommands/Ptp1588Commands.cs
generated_at: "2026-04-16T03:46:47.989856+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "fe72794d5a98f1f5"
---
# SLICE Command Module Documentation
## 1. Purpose
This module implements the command-layer abstraction for the SLICE protocol, providing strongly-typed command classes for interacting with SLICE hardware devices. It defines a hierarchy of command classes grouped by functional domain—stack setup, stack utility, firmware update, and PTP 1588 time synchronization—each inheriting from `CommandBase`. Commands are serialized into `CommandPacket` instances, which handle protocol-level details such as sequence numbering, type identification, and parameter encoding. The module serves as the primary interface between application logic and the underlying communication layer (`ICommunication`), enabling structured, type-safe command execution and response parsing.
## 2. Public Interface
### Core Base Classes
- **`Commands_Stack_Setup`** *(abstract class)*
Base class for stack setup commands. Sets `command.Type = CommandPacket.CommandType.StackSetup`.
Constructors:
- `Commands_Stack_Setup(ICommunication sock)`
- `Commands_Stack_Setup(ICommunication sock, int TimeoutMillisec)`
- **`Commands_Stack_Utility`** *(abstract class)*
Base class for stack utility commands (e.g., flash operations, power control). Sets `command.Type = CommandPacket.CommandType.StackUtility`.
Defines internal `Commands` enum with values like `BusPowerControl`, `ForceEnumeration`, etc.
Constructors:
- `Commands_Stack_Utility(ICommunication sock)`
- `Commands_Stack_Utility(ICommunication sock, int TimeoutMillisec)`
- **`FirmwareUpdateCommands`** *(abstract class)*
Base class for firmware update commands. Sets `command.Type = CommandPacket.CommandType.FirmwareUpdate`.
Defines internal `Commands` enum with values like `QueryFirmwareUpdateBlockSize`, `ProgramFirmwareUpdateBlock`, `Load_SliceProStackFirmwareImage`, etc.
Defines `FirmwareMode` enum (`FW`, `BL`, `BLL`).
Constants: `MAX_FILE_ID = 30`, `MAX_FILE_LENGTH = 400`.
Abstract property `_Command` must be implemented by derived classes.
Constructors:
- `FirmwareUpdateCommands(ICommunication sock)`
- `FirmwareUpdateCommands(ICommunication sock, int TimeoutMillisec)`
- **`Ptp1588Commands`** *(abstract class)*
Base class for PTP 1588 time synchronization commands. Sets `command.Type = CommandPacket.CommandType.Ptp1588`.
Defines enums: `PtpClockType`, `PtpMode`, `PtpDelayMechanism`, `PtpSyncStatus`, `PtpTimestampUnits`.
Defines internal `Commands` enum (e.g., `SetMode`, `GetTime`, `SetAutoTriggerTime`).
Static helper: `ToTimestampString(uint s, uint ns)` → formats as `"s.fffffffff"`.
Abstract property `_Command` must be implemented.
Constructors:
- `Ptp1588Commands(ICommunication sock)`
- `Ptp1588Commands(ICommunication sock, int TimeoutMillisec)`
### Concrete Command Classes
#### Stack Utility Commands
- **`BusPowerControl`**
Controls bus power on/off.
Properties:
- `PowerOn: bool` — sets parameter[0] to `1` (on) or `0` (off).
Constructors:
- `BusPowerControl(ICommunication sock)`
- `BusPowerControl(ICommunication sock, int TimeoutMillisec)`
Overrides: `CommandToString()`, `ResponseToString()`.
- **`ForceEnumeration`**
Triggers enumeration of connected SLICE modules.
Properties:
- `SLICECount: int` — populated from response parameter[0] on success.
Constructors:
- `ForceEnumeration(ICommunication sock)`
- `ForceEnumeration(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()` (parses response), `CommandToString()`, `ResponseToString()`.
#### Firmware Update Commands
- **`QueryFirmwareUpdateBlockSize`**
Queries maximum firmware block size.
Properties:
- `BlockSize: ushort` — populated from response parameter[0] on success.
Constructors:
- `QueryFirmwareUpdateBlockSize(ICommunication sock)`
- `QueryFirmwareUpdateBlockSize(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()`, `ResponseToString(ref List<List<string>> lines)`.
- **`QueryBootloaderVersion`**
Queries bootloader version string.
Properties:
- `Version: string` — populated from response parameter[0] on success.
Constructors:
- `QueryBootloaderVersion(ICommunication sock)`
- `QueryBootloaderVersion(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()`, `ResponseToString(ref List<List<string>> lines)`.
- **`ProgramFirmwareUpdateBlock`**
Programs a firmware block.
Properties:
- `BlockBaseAddress: uint` — sets parameter[0–3].
- `BlockSize: ushort` — set internally from `Data` length; sets parameter[4–5].
- `BlockCRC16: ushort` — sets parameter[6–7].
- `Upper: bool` — sets parameter[8] to `1` if true.
- `Data: byte[]` — sets parameter[10..] (requires `command.Parameter` expansion).
Constructors:
- `ProgramFirmwareUpdateBlock(ICommunication sock)`
- `ProgramFirmwareUpdateBlock(ICommunication sock, int TimeoutMillisec)`
Overrides: `CommandToString(ref List<List<string>> lines)`.
- **`FinishFirmwareUpdate`**
Finalizes firmware update with image CRC.
Properties:
- `ImageCRC16: ushort` — sets parameter[0–1].
Constructors:
- `FinishFirmwareUpdate(ICommunication sock)`
- `FinishFirmwareUpdate(ICommunication sock, int TimeoutMillisec)`
Overrides: `CommandToString(ref List<List<string>> lines)`, `ResponseToString(ref List<List<string>> lines)`.
- **`QueryInFirmwareUpdateMode`**
Queries current firmware update mode.
Properties:
- `InUpdateMode: bool` — `true` if not in `FW` mode.
- `IsFwMode`, `IsBlMode`, `IsBllMode: bool` — mode flags.
- `Mode: FirmwareMode` — actual mode enum.
Constructors:
- `QueryInFirmwareUpdateMode(ICommunication sock)`
- `QueryInFirmwareUpdateMode(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()`.
- **`Load_SliceProStackFirmwareImage`**
Loads a 400-byte firmware block to base NAND (requires protocol ≥137).
Properties:
- `StartByteCount: uint` — sets parameter[2–5].
- `Data: byte[]` — sets parameter[6..]; throws `NotImplementedException` if length > `MAX_FILE_LENGTH` (400).
- `Size: int` — length of `Data`.
- `MaximumFileStreamBytes: int` → `400`.
- `_fileID = 20` (hardcoded for firmware).
- `MinimumProtocolVersion` set via `sock.GetMinProto(ProtocolLimitedCommands.StackFirmwareUpdate)`.
- `command.ShouldLog = false`.
Constructors:
- `Load_SliceProStackFirmwareImage(ICommunication sock)`
- `Load_SliceProStackFirmwareImage(ICommunication sock, int TimeoutMillisec)`
Overrides: `CommandToString(ref List<List<string>> lines)`.
- **`Start_SliceProStackFirmwareUpdate`**, **`Set_SliceProStackFirmwareUpdateMode`**, **`Get_SliceProStackFirmwareUpdateMode`**
Support Slice Pro stack firmware updates (protocol ≥137).
- `Set_SliceProStackFirmwareUpdateMode`:
- `SliceModuleCount: int` — sets `_sliceProUpdateMode` array size.
- `SliceModuledateMode: byte[]` — sets `command.Parameter`.
- `Get_SliceProStackFirmwareUpdateMode`:
- `SliceModuleCount: int` — populated from `response.Parameter.Length`.
- `SliceModuledateMode: byte[]` — populated from response parameters.
Overrides `WholePackage()`.
#### PTP 1588 Commands
- **`Ptp1588SetMode`**
Sets PTP mode.
Methods:
- `SetClockType(PtpClockType)` — sets parameter[0–1].
- `SetDelayMechanism(PtpDelayMechanism)` — sets parameter[2–3].
Constructors:
- `Ptp1588SetMode(ICommunication sock)`
- `Ptp1588SetMode(ICommunication sock, int TimeoutMillisec)`
Overrides: `CommandToString(ref List<List<string>> lines)`.
- **`Ptp1588GetMode`**
Gets PTP mode.
Properties:
- `ClockType: PtpClockType`
- `DelayMechanism: PtpDelayMechanism`
Constructors:
- `Ptp1588GetMode(ICommunication sock)`
- `Ptp1588GetMode(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()`.
- **`Ptp1588GetSyncStatus`**
Gets PTP sync status.
Properties:
- `SyncStatus: PtpSyncStatus`
- `OFM: int` — offset from master (ns).
- `FreqAdj: int` — frequency adjustment.
Constructors:
- `Ptp1588GetSyncStatus(ICommunication sock)`
- `Ptp1588GetSyncStatus(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()` (requires `response.ParameterLength > 6` for full data).
- **`Ptp1588SetTime`**, **`Ptp1588GetTime`**, **`Ptp1588SetAutoTriggerTime`**, **`Ptp1588GetAutoTriggerTime`**
Time setting/getting commands.
- `SetTime`/`SetAutoTriggerTime`: `SetSeconds(uint)`, `SetNanoseconds(uint)`.
- `GetTime`/`GetAutoTriggerTime`:
- `Seconds: uint`, `Nanoseconds: uint`, `Timestamp: string` (via `ToTimestampString`).
Constructors and overrides similar to above.
- **`Ptp1588GetTimestamp`**
Gets timestamp for a specified trigger source.
Properties:
- `TimestampUnit: PtpTimestampUnits` (set via property).
- `Seconds`, `Nanoseconds`, `Timestamp`, `IsValid: bool`.
Constructors:
- `Ptp1588GetTimestamp(ICommunication sock)`
- `Ptp1588GetTimestamp(ICommunication sock, int TimeoutMillisec)`
Overrides: `CommandToString(ref List<List<string>> lines)`, `ResponseToString(ref List<List<string>> lines)`.
- **`Ptp1588SetEnableTimestamping`**
Enables/disables trigger timestamping.
Methods:
- `SetEnable(bool)` — sets parameter[0] to `1` or `0`.
Constructors:
- `Ptp1588SetEnableTimestamping(ICommunication sock)`
- `Ptp1588SetEnableTimestamping(ICommunication sock, int TimeoutMillisec)`.
- **`Ptp1588SetAdcClockFrequency`**
Requests ADC clock frequency.
Properties:
- `RequestedFrequency: uint` (set via property).
- `ActualFrequency: uint` — populated from response parameter[0] on success.
Constructors:
- `Ptp1588SetAdcClockFrequency(ICommunication sock)`
- `Ptp1588SetAdcClockFrequency(ICommunication sock, int TimeoutMillisec)`
Overrides: `WholePackage()`, `CommandToString(ref List<List<string>> lines)`, `ResponseToString(ref List<List<string>> lines)`.
- **`Ptp1588RunClockAdjustmentCalibration`**
Runs clock calibration.
Methods:
- `SetDuration(ushort)` — sets parameter[0–1].
- `SetSaveAttribute(bool)` — sets parameter[2].
Constructors:
- `Ptp1588RunClockAdjustmentCalibration(ICommunication sock)`
- `Ptp1588RunClockAdjustmentCalibration(ICommunication sock, int TimeoutMillisec)`.
- **`QueryClockSyncStatus`**
Queries clock sync configuration (requires protocol ≥ version from `ProtocolLimitedCommands.QueryClockSyncStatus`).
Properties:
- `InputState`, `OutputState`, `SyncStatus: byte`.
- `ClockSyncProfile: ClockSyncProfile` (enum from `DTS.Common.Enums`).
- `InputSources`, `OutputSources: List<T>` (populated from `Enum.GetValues`).
- `InputSyncStatus: IDictionary<InputClockSource, bool>` — built by masking `SyncStatus` with each source enum value.
Overrides: `WholePackage()`.
- **`SetClockSyncConfig`**
Sets clock sync configuration (requires protocol ≥ version from `ProtocolLimitedCommands.SetClockSyncConfig`).
Overrides: `ResponseToString(ref List<List<string>> lines)` (reports success/failure).
## 3. Invariants
- **Command Type Consistency**:
Each command class sets `command.Type` to a specific `CommandPacket.CommandType` value in its constructor (e.g., `StackSetup`, `StackUtility`, `FirmwareUpdate`, `Ptp1588`). Derived classes must not override this.
- **Sequence Number Uniqueness**:
`CommandPacket.GetNextSequenceNumber()` uses a static `GlobalSequenceNumber` incremented under lock (`GlobalSequenceNumberLock`). Sequence numbers are monotonically increasing and unique per process.
- **Parameter Initialization**:
Commands initialize `command.Parameter` to a fixed-size `byte[]` in constructors. Dynamic expansion occurs only in `ProgramFirmwareUpdateBlock.Data` and `Load_SliceProStackFirmwareImage.Data` when data exceeds initial capacity.
- **Protocol Version Enforcement**:
Commands requiring specific protocol versions (e.g., `Load_SliceProStackFirmwareImage`, `SetClockSyncConfig`) set `MinimumProtocolVersion` via `sock.GetMinProto(...)`.
- **Response Parsing Guard**:
`WholePackage()` overrides check `response.Status == CommandStatus.StatusNoError` before parsing parameters.
- **Command Parameter Layout**:
Parameter offsets are fixed and documented by command (e.g., `ProgramFirmwareUpdateBlock.BlockBaseAddress` → parameter[0–3], `BlockSize` → parameter[4–5]). Offsets are not inferred dynamically.
## 4. Dependencies
### Dependencies *on* this module:
- **`DTS.DASLib.Command.SLICE.CommandBase`** → Base for all command classes.
- **`DTS.DASLib.Command.SLICE.CommandPacket`** → Packet structure and sequence numbering.
- **`DTS.Common.Interface.DASFactory.ICommunication`** → Communication channel abstraction (passed to constructors).
- **`DTS.Common.Enums.DASFactory.DFConstantsAndEnums`** → `CommandStatus`, `ProtocolLimitedCommands`, `InputClockSource`, `OutputClockSource`, `ClockSyncProfile`.
- **`DTS.Common.ICommunication`** → Used in `ICommunication` interface (likely aliased or re-exported).
### Dependencies *of* this module:
- **`DTS.DASLib.Communication`** (namespace) — referenced in `StackUtilityCommands.cs` but not used (likely legacy).
- **`DTS.DASLib.Utility`** — referenced but unused in `StackUtilityCommands.cs`.
- **`DTS.Common`** — for enums, logging, utilities.
- **`System`**, **`System.Collections.Generic`**, **`System.Text`**, **`System.Threading`**, **`System.Reflection`**, **`System.IO`**, **`System.Diagnostics`** — standard libraries.
## 5. Gotchas
- **`Load_SliceProStackFirmwareImage.Data` throws `NotImplementedException`** if input data length exceeds `MAX_FILE_LENGTH` (400 bytes). This is a hard limit; no fallback or chunking is provided.
- **`Ptp1588GetSyncStatus` silently degrades**: If `response.ParameterLength ≤ 6`, `SyncStatus` defaults to `NotSynced` without error logging.
- **`Set_SliceProStackFirmwareUpdateMode.SliceModuledateMode` setter copies values but does not validate array length against `SliceModuleCount`** — mismatched lengths may cause silent truncation or `IndexOutOfRangeException`.
- **`QueryClockSyncStatus.InputSyncStatus` is populated only for `InputClockSource` enum values *except the first* (`sources[0]`)** due to `for (int i = 1; i < sources.Count; i++)`. The first source is skipped.
- **`ProgramFirmwareUpdateBlock.Data` setter expands `command.Parameter` only if current length is insufficient**, but does not shrink it. Repeated use may retain unused bytes.
- **`FirmwareUpdateCommands` and `Ptp1588Commands` use `command.SetCommand((byte)_Command, _Command.ToString())`**, but `_Command.ToString()` is not used elsewhere in the codebase — likely for debugging only.
- **`BusPowerControl.PowerOn` setter always writes to parameter[0]**, regardless of prior state — no idempotency or validation.
- **`QueryInFirmwareUpdateMode.InUpdateMode` logic is inverted**: `InUpdateMode = (Mode != FirmwareMode.FW)`, but `IsFwMode = (Mode == FirmwareMode.FW)`. This may cause confusion.
- **`Ptp1588SetAdcClockFrequency` uses typo in command name**: `Commands.SetAdcClockFrquency` (missing 'e' in "Frequency").
- **`Load_SliceProStackFirmwareImage._fileID` is hardcoded to `20`** (firmware ID), but `MAX_FILE_ID = 30` suggests user IDs (1–10) are possible — no public API to change `_fileID`.
- **No validation of `command.Parameter` bounds** in setters like `ProgramFirmware
Reference in New Issue Copy Permalink