12.5.3 Command List States |
A command list progresses through a series of states from the moment it is sent to the card until its commands have finished executing. Understanding these states is important for correctly interpreting the value returned by GetListStatus and for knowing when to use it in combination with WaitForListDone or RegisterListDoneCallback.
List StatesA command list can be in one of four states at any given time, represented by the ListStatus enumerable:
State | Meaning |
|---|---|
NotExisting | The card has no record of a list with this ID. |
Idle | The card holds a list with this ID, but the list is not currently queued or being prepared for execution. See The Two Meanings of Idle below. |
InExecutionQueue | Execution of the list has been requested and the list is waiting in the execution queue. |
Processing | The card is preparing the list for execution — translating it into an internal format the execution engine can use. Command execution may begin before translation is complete. See What Processing Means below. |
Lifecycle of a Command ListThe following table shows how a list moves through its states from submission to completed execution.
Stage | List state |
|---|---|
List not yet sent to card | NotExisting |
List received and stored by card | Idle — the list exists but execution has not been requested. |
Execution of the list requested | InExecutionQueue — the list is waiting in line to be processed. |
Card begins preparing the list | Processing — the list is being translated; Command execution may begin before translation is complete. |
Card finishes preparing the list | Idle — translation is complete; the execution engine has been running commands since the first packages became available. |
Commands are being executed (e.g., I/O writes) | Idle — this stage is not reflected in the list state; see below. |
All commands executed; WaitForListDone returns | Idle — completion is signalled separately, not through the list state. |
The Two Meanings of IdleThe Idle state occurs at two distinct points in a list's lifecycle:
Before execution is requested — the list has been received by the card but no execution has been requested yet.
After preparation is complete — the card has finished translating the list while the execution engine has been consuming it concurrently. The list's commands may or may not have finished at this point.
The Idle state indicates that the list is not currently being processed by the card and is available to be modified or queued for execution again. This makes it possible to repeatedly request execution of the same list, or to update the list and re-queue it in quick succession. However, Idle says nothing about the state of the execution engine — it does not indicate whether the list's commands have finished executing. To be notified when all commands in a list have been executed, either call WaitForListDone or register a callback via RegisterListDoneCallback.
What Processing MeansThe Processing state indicates that the card is preparing the list for execution — translating it into an internal format that the execution engine can use. Translation and execution run in parallel: the execution engine begins consuming translated packages as soon as they become available, while translation of the remainder of the list is still ongoing. The card gets a brief head start on translation before execution begins, but in general both processes overlap.
In practice, translation tends to complete well before all commands have been executed, so the list will typically transition back to Idle while I/O output is still in progress. This transition does not indicate that commands have finished executing.
Tracking Execution CompletionBecause the list state does not track what happens after preparation, a different mechanism is needed to detect when a list's commands have finished executing. The recommended approach is:
Send the command list to the card and verify the list is received by checking that its state is Idle.
Request execution and verify the list enters the queue by checking that its state is InExecutionQueue.
Observe the list transition through Processing and back to Idle as the card prepares it.
To be notified when all commands in a list have been executed, either call WaitForListDone or register a callback via RegisterListDoneCallback.
The list state is useful for monitoring the translation pipeline. It is WaitForListDone or RegisterListDoneCallback that closes the loop on end-to-end execution.
See Also