Skip to content

Commit 20a7cf3

Browse files
LeStarchthomas-bc
LeStarch
authored and
thomas-bc
committed
Create SDD for CdhCore subtopology (nasa#4121)
* Create SDD for CdhCore subtopology Added a comprehensive Software Design Document (SDD) for the CdhCore subtopology, detailing requirements, design, usage, configuration, and traceability. * sp * Update SDD with review feedback Added section for rate-group connection points and updated instance requirements.
1 parent bb28fd1 commit 20a7cf3

File tree

1 file changed

+166
-0
lines changed
  • Svc/Subtopologies/CdhCore/docs

1 file changed

+166
-0
lines changed

‎Svc/Subtopologies/CdhCore/docs/sdd.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# CdhCore Subtopology — Software Design Document (SDD)
2+
3+
The **CdhCore subtopology** provides a reusable bundle of the core flight-software services that nearly every F´ deployment requires. It collects standard components for **command dispatching**, **event handling**, **health monitoring**, **version/configuration reporting**, **logging**, and **assert/fatal adaptation** into a single subtopology that can be instantiated in a larger system topology. By doing so, it reduces boilerplate wiring and ensures consistent configuration of these essential services. The subtopology also defines **configurable instances** for telemetry sending and fatal-event handling, allowing integration engineers to connect these core services to project-specific implementations while reusing the common backbone of CDH (Command and Data Handling) functions.
4+
5+
## 1. Requirements
6+
7+
| ID | Description | Validation |
8+
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
9+
| SVC-CDHCORE-001 | The subtopology shall provide **command dispatching functionality** to route incoming commands to components. | Inspection |
10+
| SVC-CDHCORE-002 | The subtopology shall provide **event management functionality** to collect events. | Inspection |
11+
| SVC-CDHCORE-003 | The subtopology shall provide **health monitoring functionality** including for active components. | Inspection |
12+
| SVC-CDHCORE-004 | The subtopology shall provide **version and configuration reporting functionality** at system startup. | Inspection |
13+
| SVC-CDHCORE-005 | The subtopology shall provide **text logging functionality** for console logged event messages. | Inspection |
14+
| SVC-CDHCORE-006 | The subtopology shall provide **assert to fatal handling functionality** to convert `FW_ASSERT`s into `FATAL` events. | Inspection |
15+
| SVC-CDHCORE-007 | The subtopology shall provide **fatal-event routing functionality** to forward fatal announcements to a configurable handler. | Inspection |
16+
| SVC-CDHCORE-008 | The subtopology shall provide **telemetry sending functionality** through a configurable telemetry interface. | Inspection |
17+
| SVC-CDHCORE-009 | The subtopology shall support **configurable instance properties** for IDs, queue sizes, stack sizes, and priorities. | Inspection |
18+
| SVC-CDHCORE-010 | The subtopology shall expose rate-group connection points for any rate-drive components it contains. | Inspection |
19+
20+
## 2. Design & Core Functions
21+
22+
### 2.1 Instance Summary
23+
24+
| Instance name | Type (Svc) | Kind | Purpose (core function) | Handles |
25+
| -------------- | -------------------- | ------- | -------------------------------------------------------------------------------------- |------------------------|
26+
| `cmdDisp` | `CommandDispatcher` | Active | Receives uplinked/issued commands and dispatches them. | command connections |
27+
| `events` | `EventManager` | Active | Aggregates and distributes events; `FatalAnnounce` is wired to `fatalHandler`. | event connections |
28+
| `$health` | `Health` | Queued | Performs health pings; configured with ping table. | health connections |
29+
| `version` | `Version` | Passive | Provides version reporting; configured for startup reporting. | |
30+
| `textLogger` | `PassiveTextLogger` | Passive | Text event logging sink. | text event connections |
31+
| `fatalAdapter` | `AssertFatalAdapter` | Passive | Adapts framework `FW_ASSERT`s into `FATAL`s behavior. | |
32+
| `tlmSend` | *(configurable)* | — | Telemetry send instance provided via configuration. | telemetry connections |
33+
| `fatalHandler` | *(configurable)* | — | Fatal handler instance provided via configuration. | |
34+
35+
### 2.2 Configuration Hooks inside the Subtopology
36+
37+
* **Health**: Configures `$health` with a ping table (`ConfigObjects.CdhCore_health::pingEntries`).
38+
* **Version**: Calls `version.config(true)` so version/config reporting is enabled at startup.
39+
40+
### 2.3 Internal Wiring
41+
42+
* **Fault protection path**: `events.FatalAnnounce -> fatalHandler.FatalReceive` is wired.
43+
44+
All other services are registered in the calling topology.
45+
46+
### 2.4 Required Inputs for Operation
47+
48+
The `CdhCore` subtopology is not a stand-alone application. It requires specific connections from the including deployment topology to operate correctly:
49+
50+
* **Rate Groups**
51+
52+
* The active components instances (`$health` and possibly `tlmSend` depending on configuration) require scheduling via rate group ports.
53+
* The including topology must connect them to rate group driver outputs or equivalent schedulers.
54+
55+
* **Configurable Instances**
56+
57+
* `tlmSend`: A project-specific telemetry sender instance that handles downlinking channelized telemetry.
58+
* `fatalHandler`: A project-specific handler that processes fatal events (for example, shutting down the system or resetting hardware).
59+
60+
Without these inputs, the subtopology cannot schedule, report, or properly propagate telemetry and fatal events.
61+
62+
### 2.5 Limitations
63+
64+
The `CdhCore` subtopology is focused on core CDH services and does **not** include the following functions:
65+
66+
* **Uplink handling** (command reception from ground)
67+
* **Downlink handling** (telemetry transport to ground)
68+
* **Framing or deframing** of communications data (e.g., CCSDS, F´ framing)
69+
* **File management services** (uplink, downlink, or storage)
70+
71+
These capabilities must be provided by other subtopologies or components (e.g., `ComCcsds`, `FramingFprime`, file services) and wired alongside `CdhCore` in the deployment topology.
72+
73+
## 3. Usage
74+
75+
The **CdhCore subtopology** is included in a deployment to provide core CDH services—command dispatching, event handling, health monitoring, version/configuration reporting, logging, and fatal handling—through clearly defined **connection specifiers**. These specifiers expose the necessary ports so the deployment topology can attach external infrastructure such as radios or storage. In practice, `CdhCore` is typically wired into a **communication or framing stack** (e.g., `ComCcsds`, `ComFprime`, `FramingFprime`, or `FramingCcsds`) to complete the end-to-end command and telemetry paths.
76+
77+
### 3.1 Example Usage
78+
79+
Example of integrating `CdhCore` in a deployment topology:
80+
81+
```fpp
82+
topology Flight {
83+
import CdhCore.Subtopology
84+
import ComCcsds.Subtopology # Used as an example communication subtopology
85+
86+
# Use CdhCore handler components
87+
command connections instance CdhCore.cmdDisp
88+
event connections instance CdhCore.events
89+
telemetry connections instance CdhCore.tlmSend
90+
text event connections instance CdhCore.textLogger
91+
health connections instance CdhCore.$health
92+
93+
connections RateGroups {
94+
# Connect rate groups to active components inside CdhCore
95+
rg.RateGroupMemberOut[0] -> CdhCore.tlmSend.Run
96+
rg.RateGroupMemberOut[1] -> CdhCore.$health.Run
97+
}
98+
99+
connections ComCcsds_CdhCore{
100+
# events and telemetry to comQueue
101+
CdhCore.events.PktSend -> ComCcsds.comQueue.comPacketQueueIn[ComCcsds.Ports_ComPacketQueue.EVENTS]
102+
CdhCore.tlmSend.PktSend -> ComCcsds.comQueue.comPacketQueueIn[ComCcsds.Ports_ComPacketQueue.TELEMETRY]
103+
104+
# Router <-> CmdDispatcher
105+
ComCcsds.fprimeRouter.commandOut -> CdhCore.cmdDisp.seqCmdBuff
106+
CdhCore.cmdDisp.seqCmdStatus -> ComCcsds.fprimeRouter.cmdResponseIn
107+
cmdSeq.comCmdOut -> CdhCore.cmdDisp.seqCmdBuff
108+
CdhCore.cmdDisp.seqCmdStatus -> cmdSeq.cmdResponseIn
109+
}
110+
}
111+
```
112+
113+
> [!TIP]
114+
> `ComCcsds` was used in the example wiring, but may be replace by another subtopology meeting the same function.
115+
116+
### 3.2 Integration Notes
117+
118+
* The **rate group driver** is project-specific. You may use a single driver with multiple cycle outputs (as above), or separate drivers for each component depending on timing needs.
119+
* The **ping table** used by the health component must be configured to include the active components you want monitored in your system.
120+
* The **fatal handler** should implement logic appropriate for your platform (e.g., log to NVM, trigger a reset).
121+
* The **telemetry sender** should be wired to your communication link, downlink storage, or other system-level data channel.
122+
123+
## 4. Configuration
124+
125+
> This section summarizes the **knobs defined in the CdhCore configuration module**.
126+
127+
### 4.1 Where it lives
128+
129+
* Module: `Svc/Subtopologies/CdhCore/CdhCoreConfig/`
130+
* Files (focus of this section):
131+
132+
1. `CdhCoreConfig.fpp` — component properties
133+
2. `CdhCoreFatalHandlerConfig.fpp` — fatal-event handling instance
134+
3. `CdhCoreTlmConfig.fpp` — telemetry instance
135+
136+
### 4.2 Component properties (`CdhCoreConfig.fpp`)
137+
138+
* **Base ID** — base id for the subtopology, component will be offset from this.
139+
* **Queue sizes** — component queue depths (for active and queued components).
140+
* **Stack sizes** — task stack allocation (for active).
141+
* **Priorities** — RTOS scheduling priority (for active).
142+
143+
> These govern footprint and responsiveness of: command dispatching, event management, health monitoring, text logging, version reporting, and assert→fatal adaptation. Override to meet platform timing and memory constraints.
144+
145+
### 4.3 Fatal-event handling (`CdhCoreFatalHandlerConfig.fpp`)
146+
147+
Defines a component instance called `fatalHandler` to handle `FATAL` events produced by the `eventManager`.
148+
149+
### 4.4 Telemetry path (`CdhCoreTlmConfig.fpp`)
150+
151+
Defines a component instance called `tlmSend` to handle telemetry.
152+
153+
## 5. Traceability Matrix
154+
155+
| Requirement ID | Satisfied by |
156+
| --------------- | ------------------------------------------------------------------ |
157+
| SVC-CDHCORE-001 | `cmdDisp` — `Svc.CommandDispatcher` |
158+
| SVC-CDHCORE-002 | `events` — `Svc.EventManager` |
159+
| SVC-CDHCORE-003 | `$health` — `Svc.Health` |
160+
| SVC-CDHCORE-004 | `version` — `Svc.Version` |
161+
| SVC-CDHCORE-005 | `textLogger` — `Svc.PassiveTextLogger` |
162+
| SVC-CDHCORE-006 | `fatalAdapter` — `Svc.AssertFatalAdapter` |
163+
| SVC-CDHCORE-007 | `fatalHandler` — configurable instance |
164+
| SVC-CDHCORE-008 | `tlmSend` — configurable instance |
165+
| SVC-CDHCORE-009 | `CdhCoreConfig` / `CdhCoreFatalHandlerConfig` / `CdhCoreTlmConfig` |
166+
| SVC-CDHCORE-010 | $health.Run |

0 commit comments

Comments
 (0)