Add system-functional docs for Fw, Os, Svc, Drv, Subtopologies, and generation skill#86
Conversation
Original prompt from michael.d.starch
|
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
| - [F Prime BufferRepeater SDD](https://github.com/nasa/fprime/blob/devel/Svc/BufferRepeater/docs/sdd.md) | ||
| - [F Prime BufferLogger SDD](https://github.com/nasa/fprime/blob/devel/Svc/BufferLogger/docs/sdd.md) | ||
| - [F Prime StaticMemory SDD](https://github.com/nasa/fprime/blob/devel/Svc/StaticMemory/docs/sdd.md) | ||
| - [Fw::Buffer SDD](https://github.com/nasa/fprime/blob/devel/Fw/Buffer/docs/sdd.md) |
There was a problem hiding this comment.
This should be first in the list as Fw::Buffer is used for all subsystems
| ### Buffer Allocation | ||
|
|
||
| Two buffer allocation strategies are available: | ||
|
|
There was a problem hiding this comment.
Buffer manager is an implementation of a buffer pool
|
|
||
| - **Buffer Manager** — Allocates buffers from a pool of dynamically managed memory. The pool is configured at setup time with bin sizes and counts, allowing efficient allocation of buffers at various sizes without per-allocation heap calls. The allocator tracks outstanding buffers and detects leaks. | ||
|
|
||
| - **Static Memory** — Allocates buffers from statically defined memory regions. This is a drop-in replacement for the Buffer Manager that avoids dynamic memory complexity entirely. Each output port corresponds to a fixed-size memory region. This is appropriate when buffer sizes and usage patterns are fully known at design time. |
There was a problem hiding this comment.
Useful for supporting components needing buffer management when only one outstanding allocation is needed at a time
| In both cases, components request buffers via the Fw::BufferGet port and return them via the Fw::BufferSend port. | ||
|
|
||
| ### Buffer Accumulation | ||
|
|
There was a problem hiding this comment.
Also useful to pause buffer processing during critical events
|
|
||
| ### APID Management | ||
|
|
||
| The APID Manager tracks per-APID sequence counts for both outgoing and incoming Space Packets. It provides incrementing sequence counts to the Space Packet Framer for each APID and validates received sequence counts in the Space Packet Deframer to detect packet loss. |
There was a problem hiding this comment.
Add a note on how apids are defined. Check me on this….but currently apids are assigned to the fprime data descriptor type
There was a problem hiding this comment.
Users wanting different management can replace this component
|
|
||
| 1. The Communication Queue sends data to the Space Packet Framer, which constructs CCSDS Space Packets with proper APIDs and sequence counts. | ||
| 2. The TM Framer wraps each Space Packet into a CCSDS TM Transfer Frame for transmission over the space link. | ||
|
|
|
|
||
| 1. The Frame Accumulator collects bytes and assembles complete frames. The TC Deframer extracts Space Packets from TC Transfer Frames. | ||
| 2. The Space Packet Deframer validates the Space Packets and extracts the payload, which is then routed by the F Prime Router to its destination (command dispatcher, file uplink, etc.). | ||
|
|
| - A packet identifier | ||
| - A send level that determines when the packet is active | ||
|
|
||
| The table is provided to the component at initialization via the `setPacketList()` method. |
There was a problem hiding this comment.
Users specify this table through FPP modeling in the topology where this component is used.
| ### Telemetry Limits | ||
|
|
||
| As with channel-based telemetry, channels can have limit ranges defined in the dictionary. Limit checking is performed by the ground system. | ||
|
|
There was a problem hiding this comment.
We should describe the MIN, MAX options as well.
|
|
||
| ### Cycle Source | ||
|
|
||
| The Linux Timer provides a periodic tick source on Linux systems. It generates cycle port calls at a configured rate, driving the rate group scheduling chain. On other platforms, the cycle source may be provided by a hardware timer driver or other platform-specific component. |
There was a problem hiding this comment.
Link to the rate group document here. It drives the RGs. Also have that doc link back here.
…ng them - Add .agents/skills/write-system-functional-doc/SKILL.md: reusable Devin skill for analyzing F Prime components and writing system-functional documents - Add docs/reference/system-functional/command-dispatch.md: high-level functional description of command dispatching (registration, routing, status tracking, queue overflow protection, off-nominal behavior) - Update docs/reference/system-functional/index.md to include new document Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
The skill now handles three input types: - Single component path (e.g. Svc/CmdDispatcher) - Subtopology path (e.g. Svc/Subtopologies/CdhCore) - Multiple component paths for informal subsystems (e.g. RateGroupDriver + ActiveRateGroup) Adds guidance for: - Identifying the scope of a capability across components - Tracing data/control flow between collaborating components - Writing about the functional capability (not individual components) - Handling subtopology-specific details (configurability, external interfaces) - Organizing by functional aspect rather than by component Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
…nd-dispatch doc These SDDs are for the sequencing capability, not command dispatch. Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
New documents: - framework.md: Core types, ports, components, serialization, commands, events, telemetry, parameters, time, buffers, data products - osal.md: OS abstraction layer (tasks, files, mutexes, queues, system resources) - rate-group-scheduling.md: Cycle source, RateGroupDriver, ActiveRateGroup, PassiveRateGroup, ActivePhaser - telemetry.md: TlmChan and TlmPacketizer - event-management.md: EventManager, text logging, fatal handling - health-monitoring.md: Health, Ping, WatchDog - file-management.md: FileManager, FileDownlink, FileUplink, FileDispatcher, FileWorker - communication.md: ComQueue, FprimeFramer/Deframer/Router, FrameAccumulator, ComStub, ComSplitter, ComAggregator, ComLogger, ComRetry, GenericHub - ccsds-protocol.md: SpacePacketFramer/Deframer, ApidManager, TmFramer, TcDeframer, AosFramer - data-products.md: DpManager, DpWriter, DpCatalog - buffer-management.md: BufferManager, BufferAccumulator, BufferRepeater, BufferLogger, StaticMemory - parameters.md: PrmDb - time-services.md: ChronoTime, OsTime, PosixTime, LinuxTimer - system-services.md: SystemResources, Version, AssertFatalAdapter, FatalHandler, PolyDb - hardware-drivers.md: ByteStreamDriverModel, TCP/UDP/IP, UART, GPIO, I2C, SPI - subtopology-cdh-core.md: CdhCore subtopology - subtopology-com-fprime.md: ComFprime subtopology - subtopology-com-ccsds.md: ComCcsds subtopology - subtopology-com-logger-tee.md: ComLoggerTee subtopology - subtopology-data-products.md: DataProducts subtopology - subtopology-file-handling.md: FileHandling subtopology Updated index.md with organized sections (Core, Capabilities, Subtopologies). Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
Separate documents for the two telemetry approaches: - telemetry-chan.md: Channel-based storage (TlmChan) - telemetry-packetizer.md: Packetized storage (TlmPacketizer) Index offers both choices on one line. Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
- buffer-management: Move Fw::Buffer ref first, fix BufferManager desc (pool not leak detection), fix StaticMemory desc (one outstanding alloc), add pause note - ccsds-protocol: Add APID assignment note, custom ApidManager replaceable, no multi-VCID, fix seq count behavior, add Unsupported Features section - command-dispatch: Add duplicate opcode assertion behavior, queue priority note - event-management: FATAL triggers fatal handler, ACTIVITY_LO for background, component-level throttling with count/time modes - framework: Add cross-links to all corresponding system-functional docs - health-monitoring: Fix to warning-then-fatal (two thresholds) - communication: Remove Hub section, add CCSDS cross-reference, add topology diagram - hardware-drivers: Note Linux drivers in core, other packages for other OS/HW - rate-group-scheduling: Fix ISR claim, add ActivePhaser variant, overruns=slips, link to time-services - subtopology-com-ccsds: Note custom radio for external variant, add topology/downlink/uplink diagrams - subtopology-com-fprime: Add topology diagram - telemetry-packetizer: Fix packet table definition (FPP modeling), add Rate Logic section with SILENCED/EVERY_MAX/ON_CHANGE_MIN/ON_CHANGE_MIN_OR_EVERY_MAX - time-services: Add cross-link to rate group scheduling Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
968a88a to
351ee7d
Compare
Coverage report — base
|
| Module | Line | Function | Branch |
|---|---|---|---|
CFDP/Checksum |
71.15 | 57.14 | 53.85 |
Drv/AsyncByteStreamBufferAdapter |
100.00 | 100.00 | 100.00 |
Drv/ByteStreamBufferAdapter |
100.00 | 100.00 | 100.00 |
Drv/Ip |
44.32 | 57.38 | 25.36 |
Drv/TcpClient |
75.00 | 100.00 | 47.37 |
Drv/TcpServer |
84.72 | 100.00 | 60.00 |
Drv/Udp |
68.09 | 90.91 | 42.86 |
Fw/Buffer |
81.25 | 89.47 | 58.62 |
Fw/DataStructures |
98.30 | 96.76 | 83.03 |
Fw/Dp |
94.83 | 96.67 | 95.95 |
Fw/FilePacket |
75.24 | 89.06 | 54.30 |
Fw/Log |
75.71 | 84.21 | 60.71 |
Fw/Logger |
100.00 | 100.00 | 100.00 |
Fw/SerializableFile |
90.00 | 100.00 | 79.41 |
Fw/Time |
88.62 | 85.48 | 86.84 |
Fw/Tlm |
53.76 | 60.00 | 37.50 |
Fw/Types |
53.84 | 56.01 | 34.32 |
Os |
18.05 | 19.48 | 14.52 |
Os/Generic |
89.10 | 96.30 | 67.18 |
Os/Generic/Types |
92.45 | 91.67 | 82.14 |
Os/Posix |
62.00 | 84.21 | 43.87 |
Svc/ActiveRateGroup |
100.00 | 100.00 | 92.31 |
Svc/ActiveTextLogger |
79.05 | 90.00 | 71.23 |
Svc/AssertFatalAdapter |
94.74 | 100.00 | 86.67 |
Svc/BufferAccumulator |
88.00 | 94.12 | 74.49 |
Svc/BufferLogger |
92.62 | 86.96 | 80.46 |
Svc/BufferManager |
99.05 | 100.00 | 83.64 |
Svc/BufferRepeater |
91.67 | 100.00 | 75.00 |
Svc/ChronoTime |
100.00 | 100.00 | 100.00 |
Svc/CmdDispatcher |
96.97 | 91.67 | 91.75 |
Svc/CmdSequencer |
93.89 | 97.12 | 84.63 |
Svc/CmdSplitter |
100.00 | 100.00 | 100.00 |
Svc/ComLogger |
97.37 | 91.67 | 83.91 |
Svc/ComSplitter |
100.00 | 100.00 | 100.00 |
Svc/ComStub |
98.51 | 100.00 | 85.19 |
Svc/DpCatalog |
78.00 | 100.00 | 66.27 |
Svc/DpManager |
97.44 | 100.00 | 100.00 |
Svc/DpWriter |
97.58 | 90.00 | 97.22 |
Svc/FileDownlink |
84.15 | 90.91 | 71.90 |
Svc/FileManager |
88.41 | 93.33 | 82.44 |
Svc/FileUplink |
92.35 | 96.55 | 80.95 |
Svc/FileWorker |
90.29 | 100.00 | 84.87 |
Svc/FprimeDeframer |
100.00 | 100.00 | 97.92 |
Svc/FprimeFramer |
100.00 | 100.00 | 95.45 |
Svc/FprimeRouter |
88.89 | 100.00 | 78.26 |
Svc/FpySequencer |
86.76 | 99.04 | 76.89 |
Svc/GenericHub |
100.00 | 100.00 | 85.64 |
Svc/Health |
100.00 | 100.00 | 88.66 |
Svc/LinuxTimer |
97.06 | 100.00 | 82.35 |
Svc/OsTime |
70.00 | 83.33 | 60.98 |
Svc/PassiveRateGroup |
100.00 | 100.00 | 89.47 |
Svc/PolyDb |
100.00 | 100.00 | 53.57 |
Svc/PosixTime |
100.00 | 100.00 | 75.00 |
Svc/PrmDb |
92.75 | 89.47 | 88.24 |
Svc/RateGroupDriver |
100.00 | 100.00 | 68.75 |
Svc/SeqDispatcher |
73.08 | 80.00 | 71.05 |
Svc/StaticMemory |
100.00 | 100.00 | 100.00 |
Svc/SystemResources |
98.63 | 100.00 | 76.19 |
Svc/TlmChan |
77.59 | 85.71 | 63.03 |
Svc/TlmPacketizer |
92.18 | 100.00 | 77.45 |
Svc/Version |
96.10 | 100.00 | 86.96 |
Utils |
20.04 | 26.44 | 24.07 |
Utils/Types |
92.11 | 95.83 | 77.08 |
Modules without UTs
CFDP/Checksum/GTest, Drv/ByteStreamDriverModel, Drv/Interfaces, Drv/LinuxGpioDriver, Drv/LinuxI2cDriver, Drv/LinuxSpiDriver, Drv/LinuxUartDriver, Drv/Ports, Drv/Ports/DataTypes, FppTestProject/FppTest/interfaces, FppTestProject/FppTest/topology/async, FppTestProject/FppTest/topology/components/Comp, FppTestProject/FppTest/topology/components/Framework, FppTestProject/FppTest/topology/components/Receiver, FppTestProject/FppTest/topology/components/Sender, FppTestProject/FppTest/topology/guarded, FppTestProject/FppTest/topology/ports, FppTestProject/FppTest/topology/sync, FppTestProject/FppTest/topology/top_ports, FppTestProject/FppTest/topology/types, Fw/Cmd, Fw/Com, Fw/Comp, Fw/FilePacket/GTest, Fw/Fpy, Fw/Interfaces, Fw/Obj, Fw/Port, Fw/Ports/CompletionStatus, Fw/Ports/Ready, Fw/Ports/Signal, Fw/Ports/SuccessCondition, Fw/Prm, Fw/SerializableFile/test/TestSerializable, Fw/Sm, Fw/Test, Fw/Types/GTest, Os/Models, Svc/Cycle, Svc/DpPorts, Svc/Fatal, Svc/FatalHandler, Svc/FileDownlinkPorts, Svc/FprimeProtocol, Svc/Interfaces, Svc/PassiveConsoleTextLogger, Svc/Ping, Svc/PolyIf, Svc/Ports/CommsPorts, Svc/Ports/FilePorts, Svc/Ports/OsTimeEpoch, Svc/Ports/TlmPacketizerPorts, Svc/Ports/VersionPorts, Svc/Sched, Svc/Seq, Svc/Subtopologies/CdhCore, Svc/Subtopologies/ComCcsds, Svc/Subtopologies/ComFprime, Svc/Subtopologies/ComLoggerTee, Svc/Subtopologies/DataProducts, Svc/Subtopologies/FileHandling, Svc/Types/TlmPacketizerTypes, Svc/WatchDog, TestDeploymentsProject/Ref/PingReceiver, TestDeploymentsProject/Ref/RecvBuffApp, TestDeploymentsProject/Ref/SendBuffApp, TestDeploymentsProject/Ref/Top, TestDeploymentsProject/Ref/TypeDemo, cmake/test/data/TestDeployment/TestBuildAutocoder, cmake/test/data/TestDeployment/TestChainedAutocoder, cmake/test/data/TestDeployment/TestHeaderAutocoder, cmake/test/data/TestDeployment/TestTargetAutocoder, cmake/test/data/test-fprime-library/TestLibrary/TestComponent, cmake/test/data/test-fprime-library2/TestLibrary2/TestComponent
…ults in communication.md Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
…ver, replaced by mission adapter for flight Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
4155d17 to
3f357c9
Compare
Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
Change Description
Adds comprehensive system-functional documentation for all F Prime components, subtopologies, and core framework modules. Also includes a reusable skill for generating future system-functional documents.
Core: Framework (Fw), OSAL (Os)
Capabilities: Command Dispatch, Rate Group Scheduling, Telemetry (Channel-based and Packetized), Event Management, Health Monitoring, File Management, Communication Stack, CCSDS Protocol, Data Products, Buffer Management, Parameters, Time Services, System Services, Hardware Drivers
Subtopologies: CdhCore, ComFprime, ComCcsds, ComLoggerTee, DataProducts, FileHandling
Skill:
.agents/skills/write-system-functional-doc/SKILL.md— reusable procedure for analyzing F Prime components/subsystems and writing system-functional docsReview Comment Fixes (latest commit)
Visualizations Added
Generated using
fprime-util visualizefor ComFprime and ComCcsds subtopologies. Topology diagrams embedded in communication.md, subtopology-com-fprime.md, and subtopology-com-ccsds.md.Rationale
System engineers need high-level functional descriptions of F Prime capabilities — not code-level API docs, but operational descriptions of what each subsystem does, how it is configured, and how it behaves nominally and off-nominally. These documents fill that gap for the full set of F Prime components and subtopologies.
Testing/Review Recommendations
Future Work
AI Usage (see policy)
AI was used for code generation, documentation writing, and visualization capture. All content was verified against F Prime source code and component SDDs.
IAMAI
Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/4e68d002bc0f4eee871ad1d42275f4a3