Clarify invocation of seqCmdStatus port in CmdDispatcher (#3557)

Co-authored-by: Thomas Boyer-Chammard <49786685+thomas-bc@users.noreply.github.com>

Author: AlesKus

Svc/CmdDispatcher/CommandDispatcherImpl.cpp

@@ -81,6 +81,9 @@ namespace Svc {
         if (portToCall != -1) {
             // call port to report status
             if (this->isConnected_seqCmdStatus_OutputPort(portToCall)) {
+                // NOTE: seqCmdStatus port forwards three arguments: (opCode, cmdSeq, response).
+                //       However, the cmdSeq value has no meaning for the calling sequencer.
+                //       Instead, the context value is forwarded to allow the caller to utilize it if needed.
                 this->seqCmdStatus_out(portToCall,opCode,context,response);
             }
         }

Svc/CmdDispatcher/docs/sdd.md

@@ -13,7 +13,7 @@ Requirement | Description | Verification Method
 CD-001 | The `Svc::CmdDispatcher` component shall accept command buffers and decode them into commands | Inspection, Unit Test
 CD-002 | The `Svc::CmdDispatcher` component shall dispatch commands to components | Unit Test
 CD-003 | The `Svc::CmdDispatcher` component shall provide an interface to register commands | Inspection
-CD-004 | The `Svc::CmdDispatcher` component shall process command status from components and report the results to the command buffer sender. | Unit Test 
+CD-004 | The `Svc::CmdDispatcher` component shall process command status from components and report the results to the command buffer sender. | Unit Test
 
 ## 3. Design
 
@@ -32,10 +32,10 @@ The `Svc::CmdDispatcher` component uses the following port types:
 Port Data Type | Name | Direction | Kind | Usage
 -------------- | ---- | --------- | ---- | -----
 [`Fw::Cmd`](../../../Fw/Cmd/docs/sdd.md) | cmdSend | Output | n/a | Send commands to components
-[`Fw::CmdResponse`](../../../Fw/Cmd/docs/sdd.md) | compStat | Input | Asynchronous | Port for components to report command status
-[`Fw::CmdResponse`](../../../Fw/Cmd/docs/sdd.md) | seqStatus | Output | n/a | Send command status to command buffer source
-[`Fw::Com`](../../../Fw/Com/docs/sdd.md) | cmdBuff | Input | Asynchronous | Receive command buffer
-[`Fw::CmdReg`](../../../Fw/Cmd/docs/sdd.md) | cmdReg | Input | Synchronous | Command Registration 
+[`Fw::CmdResponse`](../../../Fw/Cmd/docs/sdd.md) | compCmdStat | Input | Asynchronous | Port for components to report command status
+[`Fw::CmdResponse`](../../../Fw/Cmd/docs/sdd.md) | seqCmdStatus | Output | n/a | Send command status to command buffer source
+[`Fw::Com`](../../../Fw/Com/docs/sdd.md) | seqCmdBuff | Input | Asynchronous | Receive command buffer
+[`Fw::CmdReg`](../../../Fw/Cmd/docs/sdd.md) | cmdReg | Input | Synchronous | Command Registration
 
 ### 3.2 Functional Description
 
@@ -47,7 +47,9 @@ An autogenerated function on components create a public function `regCommands` t
 
 #### 3.2.2 Command Dispatch
 
-When the command dispatcher receives a command buffer, it decodes the opcode. It searches the dispatch table for the opcode, then assigns a sequence number to the command and stores the opcode, sequence number, context value and source port in a pending command table. The command is then dispatched to the component that implements the command. When the component completes execution of the command, it reports the status back via the `compStat` port. The sequence number is matched to the entry in the pending command table, and the `seqStatus` output port corresponding to the source port is called (if it is connected) with the status and the context value. Note that this requires that the component sending the command buffer have connections to the same `cmdBuff` and `seqStatus` port numbers.
+When the command dispatcher receives a command buffer, it decodes the opcode. It searches the dispatch table for the opcode, then assigns a sequence number to the command and stores the opcode, sequence number, context value and source port in a pending command table. The command is then dispatched to the component that implements the command. When the component completes execution of the command, it reports the status back via the `compCmdStat` port. The sequence number is matched to the entry in the pending command table, and the `seqCmdStatus` output port corresponding to the source port is called (if it is connected) with the status and the context value.
+Note #1: this requires that the component sending the command buffer have connections to the same `seqCmdBuff` and `seqCmdStatus` port numbers.
+Note #2: the `seqCmdStatus` port utilize the same type as the `compCmdStat`, the `Fw::CmdResponse`. This has been done to avoid creation of similar types for status ports. However, the `Fw::CmdResponse::cmdSeq` argument of the `seqCmdStatus` doesn't have any meaning for the calling sequencer. Therefore, as it has been mentioned before, instead of forwarding a command sequence number, the context value is transferred.
 
 ### 3.3 Scenarios
 
@@ -78,14 +80,14 @@ The `Svc::CmdDispatcher` component dispatches commands to other components:
 
 ```mermaid
 sequenceDiagram
-    Command Buffer Source->>CommandDispatcher: cmdBuff()
+    Command Buffer Source->>CommandDispatcher: seqCmdBuff()
     activate Command Buffer Source
     activate CommandDispatcher
-    CommandDispatcher->>Component: cmdBuff()
+    CommandDispatcher->>Component: seqCmdBuff()
     activate Component
-    Component->>CommandDispatcher: comStat()
+    Component->>CommandDispatcher: compCmdStat()
     deactivate Component
-    CommandDispatcher->>Command Buffer Source: seqStatus()
+    CommandDispatcher->>Command Buffer Source: seqCmdStatus()
     deactivate CommandDispatcher
     deactivate Command Buffer Source
 ```
@@ -115,10 +117,11 @@ To see unit test coverage run `fprime-util check --coverage`
 Date | Description
 ---- | -----------
 6/25/2015 | Design review edits
-7/22/2015 | Design review actions 
+7/22/2015 | Design review actions
 9/16/2015 | Unit Test additions
 1/28/2016 | Added context value discussion
 5/17/2021 | Added CMD Reregistration option
+5/05/2025 | Added a note about Fw::CmdResponse::cmdSeq usage in seqCmdStatus