Tighten com protocol sdds (#5017)

* Tighten ComQueue protocol definition across com-stack SDDs

Clarify that Fw::Success::SUCCESS is valid in exactly three contexts:
1. At start-up to initiate data flow
2. In response to a successfully transmitted message
3. After a previous Fw::Success::FAILURE to indicate recovery

Updated SDDs and docs for:
- Communication Adapter Interface (core protocol reference)
- ComQueue
- ComAggregator
- ComStub
- FprimeFramer
- TmFramer
- AosFramer
- ComRetry
- Svc Interfaces
- How-to guides (radio manager, custom framing)

Closes #5005

Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>

* Remove incorrect data.

* Add 'interoperate' to spell-check expect list

Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>

* Fix relative link depth for CCSDS framer docs (4 levels, not 3)

Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: LeStarch

.github/actions/spelling/expect.txt

@@ -352,6 +352,7 @@ initstate
 inkscape
 inorder
 installable
+interoperate
 intlimits
 inttypes
 INVALIDBUFFER

Svc/Ccsds/AosFramer/docs/sdd.md

@@ -34,5 +34,5 @@ The `Svc::Ccsds::AosFramer` uses an internal (member) buffer to hold the fixed s
 | output | dataOut | Svc.ComDataWithContext | Outputs framed data with optional context |
 | output | dataReturnOut | Svc.ComDataWithContext | Returns ownership of the incoming Fw::Buffer to its sender once framing is handled |
 | sync input | dataReturnIn | Svc.ComDataWithContext | Receives buffer from a deallocate call in a ComDriver component |
-| sync input | comStatusIn | Fw.SuccessCondition | Receives general status from downstream component indicating readiness for more input |
-| output | comStatusOut | Fw.SuccessCondition | Indicates the status of framer for receiving more data |
+| sync input | comStatusIn | Fw.SuccessCondition | Receives status from downstream communication adapter per the [Communication Adapter Protocol](../../../../docs/reference/communication-adapter-interface.md#communication-adapter-protocol) |
+| output | comStatusOut | Fw.SuccessCondition | Passes status through to upstream `Svc::ComQueue` per the [Framer Status Protocol](../../../../docs/reference/communication-adapter-interface.md#framer-status-protocol) |

Svc/Ccsds/TmFramer/docs/sdd.md

@@ -42,8 +42,8 @@ For each frame generated, the `Svc::Ccsds::TmFramer` will populate the CCSDS TM
 | output | dataOut | Svc.ComDataWithContext | Outputs framed data with optional context |
 | output | dataReturnOut | Svc.ComDataWithContext | Returns ownership of the incoming Fw::Buffer to its sender once framing is handled |
 | sync input | dataReturnIn | Svc.ComDataWithContext | Receives buffer from a deallocate call in a ComDriver component |
-| sync input | comStatusIn | Fw.SuccessCondition | Receives general status from downstream component indicating readiness for more input |
-| output | comStatusOut | Fw.SuccessCondition | Indicates the status of framer for receiving more data |
+| sync input | comStatusIn | Fw.SuccessCondition | Receives status from downstream communication adapter per the [Communication Adapter Protocol](../../../../docs/reference/communication-adapter-interface.md#communication-adapter-protocol) |
+| output | comStatusOut | Fw.SuccessCondition | Passes status through to upstream `Svc::ComQueue` per the [Framer Status Protocol](../../../../docs/reference/communication-adapter-interface.md#framer-status-protocol) |
 
 ## Requirements
 
@@ -56,7 +56,7 @@ For each frame generated, the `Svc::Ccsds::TmFramer` will populate the CCSDS TM
 | SVC-Ccsds-TM-FRAMER-004 | The TmFramer shall output the constructed TM Transfer Frame via its `dataOut` port. | Unit Test |
 | SVC-Ccsds-TM-FRAMER-005 | The TmFramer shall return ownership of the input buffer via the `dataReturnOut` port after the framing process is complete. | Unit Test |
 | SVC-Ccsds-TM-FRAMER-006 | The TmFramer shall accept returned buffers (previously sent via `dataOut`) through the `dataReturnIn` port for deallocation or reuse. | Unit Test |
-| SVC-Ccsds-TM-FRAMER-007 | The TmFramer shall receive communication status from downstream components via the `comStatusIn` port, and pass it through to `comStatusOut` | Unit Test, Integration Test |
+| SVC-Ccsds-TM-FRAMER-007 | The TmFramer shall receive communication status from downstream components via the `comStatusIn` port and pass it through to `comStatusOut`, including the initial start-up `Fw::Success::SUCCESS`, per-message statuses, and any recovery `Fw::Success::SUCCESS` after a `Fw::Success::FAILURE`, per the [Framer Status Protocol](../../../../docs/reference/communication-adapter-interface.md#framer-status-protocol) | Unit Test, Integration Test |
 | SVC-Ccsds-TM-FRAMER-008 | The TmFramer shall use exactly one Virtual Channel. | Unit Test, Integration Test |
 | SVC-Ccsds-TM-FRAMER-009 | The TmFramer shall correctly populate all mandatory fields of the TM Transfer Frame Primary Header, including Transfer Frame Version Number, Spacecraft Identifier, Virtual Channel Identifier, Operational Control Field Flag, Master Channel Frame Count, Virtual Channel Frame Count, Transfer Frame Secondary Header Flag, Synchronization Flag, Packet Order Flag, Segment Length Identifier, and First Header Pointer. | Unit Test, Inspection |
 | SVC-Ccsds-TM-FRAMER-010 | The TmFramer shall be configurable with a Spacecraft Identifier. | Inspection, Unit Test |

Svc/ComAggregator/docs/sdd.md

@@ -13,9 +13,9 @@ Aggregates buffers in the downlink chain. This is for use with systems that have
 | Svc-ComAggregator-002 | ComAggregator shall hold the incoming buffer when there is insufficient space in the aggregate buffer.                                                        | Unit-Test    |
 | Svc-ComAggregator-003 | ComAggregator shall send the current aggregate buffer when the incoming buffer is held due to overflow.                                                       | Unit-Test    |
 | Svc-ComAggregator-004 | ComAggregator shall send the current aggregate buffer when it receives a timeout trigger if and only if the aggregate is non-empty.                           | Unit-Test    |
-| Svc-ComAggregator-005 | ComAggregator shall clear aggregation state when a SUCCESS communication status is received back.                                                             | Unit-Test    |
+| Svc-ComAggregator-005 | ComAggregator shall clear aggregation state when a `Fw::Success::SUCCESS` communication status is received back.                                                             | Unit-Test    |
 | Svc-ComAggregator-006 | ComAggregator shall preserve the order of received buffers when forming each aggregate and across aggregate sends.                                            | Unit-Test    |
-| Svc-ComAggregator-007 | ComAggregator shall inter operate with the [Communication Adapter Interface comStatus protocol](../../../docs/reference/communication-adapter-interface.md)   | Unit-Test    |
+| Svc-ComAggregator-007 | ComAggregator shall interoperate with the [Communication Adapter Interface protocol](../../../docs/reference/communication-adapter-interface.md). Specifically, it shall pass through `Fw::Success::SUCCESS` and `Fw::Success::FAILURE` statuses per the [Framer Status Protocol](../../../docs/reference/communication-adapter-interface.md#framer-status-protocol), including the initial start-up SUCCESS and any recovery SUCCESS following a FAILURE.   | Unit-Test    |
 
 
 ## Design

Svc/ComQueue/docs/sdd.md

@@ -2,7 +2,7 @@
 
 ## 1. Introduction
 
-`Svc::ComQueue` is an  F´ active component that functions as a priority queue of buffer types. Messages are dequeued and forwarded in order of priority when a `Fw::Success::SUCCESS` signal is received. Receiving a `Fw::Success::FAILURE` results in the queues being paused until a following `Fw::Success::SUCCESS` is received.
+`Svc::ComQueue` is an  F´ active component that functions as a priority queue of buffer types. Messages are dequeued and forwarded in order of priority when a `Fw::Success::SUCCESS` signal is received on the `comStatusIn` port. `Fw::Success::SUCCESS` is accepted in three contexts: (1) at start-up to initiate data flow, (2) in response to a previously sent message, and (3) after a previous `Fw::Success::FAILURE` to indicate recovery. Receiving a `Fw::Success::FAILURE` results in the queues being paused until a subsequent `Fw::Success::SUCCESS` is received.
 
 `Svc::ComQueue` is configured with a queue depth and queue priority for each incoming `Fw::Com` and `Fw::Buffer` port by passing in a configuration table at initialization. 
 Queued messages from the highest priority source port are serviced first and a round-robin algorithm is used to balance between ports of shared priority.
@@ -12,10 +12,11 @@ Queued messages from the highest priority source port are serviced first and a r
 ## 2. Assumptions
 
 1. Incoming buffers to a given port are in priority order
-2. Data is considered to be successfully sent when a `Fw::Success::SUCCESS` signal was received
-3. The com adapter is responsible for any retransmission of failed data
+2. Data is considered to be successfully sent when a `Fw::Success::SUCCESS` signal is received in response to that data
+3. The communication adapter is responsible for any retransmission of failed data and for emitting a recovery `Fw::Success::SUCCESS` after a failure
 4. The system includes downstream components implementing the
  [communications adapter](../../../docs/reference/communication-adapter-interface.md)
+5. An initial `Fw::Success::SUCCESS` will be received on `comStatusIn` to initiate data flow (typically at start-up or driver connection)
 
 
 ## 3. Requirements
@@ -24,10 +25,10 @@ Queued messages from the highest priority source port are serviced first and a r
 | Requirement      | Description                                                                                                                             | Rationale                                                               | Verification Method |
 |------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|---------------------|
 | SVC-COMQUEUE-001 | `Svc::ComQueue` shall queue `Fw::Buffer` and `Fw::ComBuffer` received on incoming ports.                                                | The purpose of the queue is to store messages.                          | Unit Test           |
-| SVC-COMQUEUE-002 | `Svc::ComQueue` shall output exactly one `Fw::Buffer` (wrapping the queued data units) on a received `Fw::Success::SUCCESS` signal.           | `Svc::ComQueue` obeys the communication adapter interface protocol.     | Unit Test     |
-| SVC-COMQUEUE-003 | `Svc::ComQueue` shall pause sending on the  `Fw::Success::FAILURE` and restart on the next `Fw::Success::SUCCESS` signal.               | `Svc::ComQueue` should not sent to a failing communication adapter.     | Unit Test           |
+| SVC-COMQUEUE-002 | `Svc::ComQueue` shall output exactly one `Fw::Buffer` (wrapping the queued data units) on a received `Fw::Success::SUCCESS` signal. `Fw::Success::SUCCESS` is valid at start-up (to initiate flow), in response to a sent message, or after a previous `Fw::Success::FAILURE` (to indicate recovery).           | `Svc::ComQueue` obeys the [communication adapter interface protocol](../../../docs/reference/communication-adapter-interface.md#communication-queue-protocol).     | Unit Test     |
+| SVC-COMQUEUE-003 | `Svc::ComQueue` shall pause sending on `Fw::Success::FAILURE` and resume on the next `Fw::Success::SUCCESS` signal.               | `Svc::ComQueue` should not send to a failing communication adapter.     | Unit Test           |
 | SVC-COMQUEUE-004 | `Svc::ComQueue` shall have a configurable number of `Fw::Com` and `Fw::Buffer` input ports.                                             | `Svc::ComQueue` should be adaptable for a number of projects.           | Inspection          |
-| SVC-COMQUEUE-005 | `Svc::ComQueue` shall select and send the next priority `Fw::Buffer` and `Fw::ComBuffer` message in response to `Fw::Success::SUCCESS`. | `Svc::ComQueue` obeys the communication adapter interface protocol.     | Unit test           |
+| SVC-COMQUEUE-005 | `Svc::ComQueue` shall select and send the next priority `Fw::Buffer` and `Fw::ComBuffer` message in response to `Fw::Success::SUCCESS`. | `Svc::ComQueue` obeys the [communication adapter interface protocol](../../../docs/reference/communication-adapter-interface.md#communication-queue-protocol).     | Unit test           |
 | SVC-COMQUEUE-006 | `Svc::ComQueue` shall periodically telemeter the number of queued messages per-port in response to a `run` port invocation.             | `Svc::ComQueue` should provide useful telemetry.                        | Unit Test           | 
 | SVC-COMQUEUE-007 | `Svc::ComQueue` shall emit a queue overflow event for a given port when the configured depth is exceeded. Messages shall be discarded.  | `Svc::ComQueue` needs to indicate off-nominal events.                   | Unit Test           | 
 | SVC-COMQUEUE-008 | `Svc::ComQueue` shall implement a round robin approach to balance between ports of the same priority.                                   | Allows projects to balance between a set of queues of similar priority. | Unit Test           |
@@ -78,6 +79,8 @@ buffer is received. `FAILURE` statuses keep the `Svc::ComQueue` in `WAITING` sta
 either send a buffer and transition to `WAITING` or will have no buffers to send and will transition into `READY` state.
 Buffers are queued when in `WAITING` state.
 
+`Fw::Success::SUCCESS` triggers a transition from `WAITING` to either `WAITING` (if a buffer was sent) or `READY` (if no buffers are queued). This SUCCESS is valid in three contexts per the [Communication Queue Protocol](../../../docs/reference/communication-adapter-interface.md#communication-queue-protocol): at start-up, in response to a sent message, or after a previous FAILURE indicating recovery.
+
 ![`Svc::ComQueue` Functional State Machine](./img/state-machine.png)
 
 ### 4.3 Model Configuration

Svc/ComRetry/docs/sdd.md

@@ -2,7 +2,7 @@
 
 ## 1. Introduction
 
-The `Svc::ComRetry` component forwards messages from upstream to downstream components, resending messages on failure. Any topology requiring retry capabilities must place this component in the pipeline before a `ComStub` or `Radio` component. This component expects a `ComStatus` response. It acts as a pass-through component in case of a successful delivery, i.e. when it receives `Fw::Success::SUCCESS`. On receiving `Fw::Success::FAILURE`, it resends the message until it exceeds the maximum number of retries.
+The `Svc::ComRetry` component forwards messages from upstream to downstream components, resending messages on failure. Any topology requiring retry capabilities must place this component in the pipeline before a `ComStub` or `Radio` component. This component expects a `ComStatus` response per the [Communication Adapter Protocol](../../../docs/reference/communication-adapter-interface.md#communication-adapter-protocol). It acts as a pass-through component in case of a successful delivery, i.e. when it receives `Fw::Success::SUCCESS`. On receiving `Fw::Success::FAILURE`, it resends the message until it exceeds the maximum number of retries. After all retries are exhausted, it emits `Fw::Success::FAILURE` upstream, and the downstream communication adapter is responsible for eventually emitting a recovery `Fw::Success::SUCCESS` to resume data flow.
 
 `Svc::ComRetry` can be used alongside the other F´ communication components (`Svc::Framer`, `Svc::Deframer`, `Svc::ComQueue`).
 
@@ -14,7 +14,7 @@ The `Svc::ComRetry` component forwards messages from upstream to downstream comp
 | SVC-COMRETRY-002 | `Svc::ComRetry` shall store `Fw::Buffer` and its context on receiving buffer ownership through `dataReturnIn` | Store the buffer in case a retry is required  | Unit test           |
 | SVC-COMRETRY-003 | `Svc::ComRetry` shall pause delivery on receiving `Fw::Success::FAILURE` | `Svc::ComRetry` should not send to a failing communication adapter.  | Unit test           |
 | SVC-COMRETRY-004 | `Svc::ComRetry` shall resend `Fw::Buffer` on receiving `Fw::Success::SUCCESS` after prior failure if retries are available | Retry delivery of buffer  | Unit test           |
-| SVC-COMRETRY-005 | `Svc::ComRetry` shall simply pass the status upstream when the buffer is not initialized  | No buffer has been passed down the stack to `Svc::ComRetry` yet  | Unit test           |
+| SVC-COMRETRY-005 | `Svc::ComRetry` shall pass through the initial start-up `Fw::Success::SUCCESS` and any non-data statuses upstream when no buffer is pending  | The initial SUCCESS must reach `Svc::ComQueue` to initiate data flow per the [Communication Queue Protocol](../../../docs/reference/communication-adapter-interface.md#communication-queue-protocol)  | Unit test           |
 | SVC-COMRETRY-006 | The maximum number of retries shall be configurable | The number of retries should be adaptable for projects  | Inspection           |
 | SVC-COMRETRY-007 | `Svc::ComRetry` shall return buffer ownership to the upstream component on receiving `Fw::Success::SUCCESS` or after all retry attempts fail | Memory management       | Unit Test           |
 | SVC-COMRETRY-008 | `Svc::ComRetry` shall send `ComStatus` upstream on successful delivery or after all retry attempts fail                             | Status of message delivery must be passed up the stack      | Unit Test           |