Skip to content

Add system-functional docs for Fw, Os, Svc, Drv, Subtopologies, and generation skill#86

Open
devin-ai-integration[bot] wants to merge 11 commits into
develfrom
devin/1779327356-system-functional-cmd-dispatch
Open

Add system-functional docs for Fw, Os, Svc, Drv, Subtopologies, and generation skill#86
devin-ai-integration[bot] wants to merge 11 commits into
develfrom
devin/1779327356-system-functional-cmd-dispatch

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented May 21, 2026

Copy link
Copy Markdown
Related Issue(s) N/A
Has Unit Tests (y/n) n
Documentation Included (y/n) y
Generative AI was used in this contribution (y/n) AI

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 docs

Review Comment Fixes (latest commit)

  • buffer-management.md: Moved Fw::Buffer ref first; fixed BufferManager desc (pool, no leak detection); fixed StaticMemory desc (one outstanding alloc); added pause note to BufferAccumulator
  • ccsds-protocol.md: Added APID assignment note with custom ApidManager replacement; noted no multi-VCID support; fixed sequence count behavior (sync and continue); added Unsupported Features section
  • command-dispatch.md: Added duplicate opcode assertion behavior; added queue priority note
  • event-management.md: FATAL triggers fatal handler; ACTIVITY_LO for background activities; component-level throttling with count-based and time-based modes
  • framework.md: Added cross-links to all corresponding system-functional docs
  • health-monitoring.md: Fixed to warning-then-fatal (two thresholds)
  • communication.md: Removed Hub pattern section; added CCSDS cross-reference; added topology visualization
  • hardware-drivers.md: Noted Linux drivers in core, other packages for other OS/HW
  • rate-group-scheduling.md: Fixed ISR claim; added ActivePhaser as third variant; overruns also called slips; linked to time-services
  • subtopology-com-ccsds.md: Noted custom radio for external variant; added topology/downlink/uplink diagrams
  • subtopology-com-fprime.md: Added topology diagram
  • telemetry-packetizer.md: Fixed packet table definition to FPP modeling; added Rate Logic section (SILENCED/EVERY_MAX/ON_CHANGE_MIN/ON_CHANGE_MIN_OR_EVERY_MAX)
  • time-services.md: Added cross-link to rate group scheduling

Visualizations Added

Generated using fprime-util visualize for 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

  • Review documents for technical accuracy against component SDDs and source code
  • Verify cross-links between documents are correct
  • Verify topology visualizations accurately represent component relationships

Future Work

  • Add additional visualizations for other subtopologies
  • Update documents as new components or capabilities are added

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


Open in Devin Review

@devin-ai-integration

Copy link
Copy Markdown
Author
Original prompt from michael.d.starch

In fprime, under docs there is a folder for system engineering docs. High level functional descriptions. Currently has sequencing and dictionary. Please identify the folder

@devin-ai-integration

Copy link
Copy Markdown
Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR that start with 'DevinAI' or '@devin'.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

Open in Devin Review

devin-ai-integration[bot]

This comment was marked as resolved.

@devin-ai-integration devin-ai-integration Bot changed the title Add system-functional doc for command dispatch and skill for generating them Add system-functional docs for Fw, Os, Svc, Drv, Subtopologies, and generation skill May 21, 2026
- [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)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be first in the list as Fw::Buffer is used for all subsystems

### Buffer Allocation

Two buffer allocation strategies are available:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Buffer manager is an implementation of a buffer pool

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, it does not detect leaks


- **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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a note on how apids are defined. Check me on this….but currently apids are assigned to the fprime data descriptor type

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Visualization please.


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.).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Visualization please

- 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link to the rate group document here. It drives the RGs. Also have that doc link back here.

devin-ai-integration Bot and others added 7 commits May 31, 2026 23:18
…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>
@devin-ai-integration devin-ai-integration Bot force-pushed the devin/1779327356-system-functional-cmd-dispatch branch from 968a88a to 351ee7d Compare May 31, 2026 23:18
@github-actions

github-actions Bot commented May 31, 2026

Copy link
Copy Markdown

Coverage report — base devel

No baseline branch coverage/devel found. This run becomes the seed once it lands on devel.

Overall (line): 81.12% (no baseline)
Regression threshold: 0.50% (line).

Regressions

(none over threshold)

Modules changed

(no measurable change)

New modules

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

devin-ai-integration Bot and others added 2 commits June 1, 2026 22:45
…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>
devin-ai-integration[bot]

This comment was marked as resolved.

Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
@devin-ai-integration devin-ai-integration Bot force-pushed the devin/1779327356-system-functional-cmd-dispatch branch from 4155d17 to 3f357c9 Compare June 17, 2026 01:50
devin-ai-integration[bot]

This comment was marked as resolved.

Co-Authored-By: michael.d.starch <michael.d.starch@jpl.nasa.gov>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant