Ccsds::CfdpManager

CFDP Introduction

The CCSDS File Delivery Protocol (CFDP) is a space communication standard designed for reliable, autonomous file transfer in space missions. CFDP provides a robust mechanism for transferring files between ground systems and spacecraft even in environments with long propagation delays, intermittent connectivity, or high error rates.

CFDP is particularly well-suited for:

• Spacecraft-to-ground file transfers: Downlinking F' event logs, telemetry data files, science data products, and diagnostic files
• Ground-to-spacecraft file transfers: Uplinking F' flight software updates, parameter files, and command sequences
• Delay-tolerant and disruption-tolerant delivery: Automatic retry and recovery mechanisms for challenging communication links

The protocol supports two operational modes:

• Class 1 (Unacknowledged): Unreliable transfer with no acknowledgments, suitable for real-time or non-critical data where speed is prioritized
• Class 2 (Acknowledged): Reliable transfer with acknowledgments, retransmissions, and gap detection, ensuring complete and verified file delivery

Protocol Data Units (PDUs)

CFDP uses Protocol Data Units (PDUs) - structured messages with a common header and type-specific payloads:

• Metadata: Initiates transfer with filenames, file size, and options
• File Data: Carries file content segments with offset information
• EOF: Signals completion of file transmission with checksum
• FIN: Reports final delivery status (Class 2 only)
• ACK: Confirms receipt of EOF or FIN (Class 2 only)
• NAK: Requests retransmission of missing segments (Class 2 only)

For complete protocol details, refer to the CCSDS 727.0-B-5 - CCSDS File Delivery Protocol (CFDP) Blue Book specification.

CFDP as an F' Component

The CfdpManager component provides an F' implementation of the CFDP protocol and is designed to replace the standard F' FileUplink and FileDownlink components with the addition of guaranteed file delivery. CfdpManager implements both CFDP Class 1 and Class 2 protocols, providing options for both unacknowledged and acknowledged transfers with retransmissions, gap detection, and reliable file delivery even over lossy or intermittent communication links.

Substantial portions of this implementation were ported from NASA's CF (CFDP) Application in the Core Flight System (cFS) version 3.0.0. The ported code includes:

• Core CFDP engine and transaction management logic
• Protocol state machines for transmit and receive operations
• Utility functions for file handling and resource management
• Chunk and gap tracking for Class 2 transfers

The F' implementation adds new components built specifically for the F' ecosystem:

• CfdpManager component wrapper: Integrates CFDP into F' architecture with standard port interfaces, commands, events, telemetry, and parameters
• Object-oriented PDU encoding/decoding: Type-safe PDU classes based on F' Serializable interface for consistent serialization
• F' timer implementation: Uses F' time primitives for protocol timers

For detailed attribution, licensing information, and a breakdown of ported vs. new code, see ATTRIBUTION.md.

Class Diagram

The CfdpManager component diagram shows the port organization by functional grouping:

Ports are organized as follows:

• Top (System Ports): Scheduling and system health - run1Hz, pingIn, pingOut
• Left (Uplink Ports): Receive CFDP PDUs from remote entities - dataIn, dataInReturn
• Right (Downlink Ports): Send CFDP PDUs to remote entities - dataOut, dataReturnIn, bufferAllocate, bufferDeallocate
• Bottom (File Transfer Ports): Port-based file send interface - fileIn, fileDoneOut

Port Descriptions

System Ports

Downlink Ports

Uplink Ports

File Transfer Ports

Usage Examples

The following diagram shows typical CfdpManager port connections with other F' components:

This example demonstrates:

• Uplink data flow: FprimeRouter deframes incoming CFDP PDUs and sends them to CfdpManager via dataIn
• Downlink data flow: CfdpManager sends outgoing CFDP PDUs to ComQueue via dataOut for transmission
• Port-based file transfers: DpCatalog initiates file transfers via CfdpManager's fileIn port and receives completion notifications via fileDoneOut

Component Design

Assumptions

The design of CfdpManager assumes the following:

1. File transfers occur by exchanging CFDP Protocol Data Units (PDUs) as defined in CCSDS 727.0-B-5.

2. PDUs are transported in buffers provided by downstream components via the bufferAllocate port for transmission and received via the dataIn port from upstream components.

3. Multiple file transfers can occur simultaneously, managed across configurable channels with independent transaction pools.

4. Files are stored on non-volatile storage accessible via standard file I/O operations.

5. The run1Hz port is invoked periodically at 1 Hz to drive protocol timers and state machine execution.

6. For Class 2 transfers, the remote entity implements the CFDP protocol correctly and responds to PDUs according to the specification.

7. Received files are written to a temporary directory (ChannelConfig.tmp_dir per-channel parameter) during transfer and moved to their final destination upon successful completion.

8. Port-initiated file transfers (via fileIn) use default configuration parameters (FileInDefaultChannel, FileInDefaultDestEntityId, FileInDefaultClass, FileInDefaultKeep, and FileInDefaultPriority).

Security Considerations

CfdpManager follows a layered security architecture where authentication and authorization are enforced at lower network protocol layers rather than at the application layer:

• Physical/Network Layer Security: Hardware encryption at the radio level, or network-layer protocols like Bundle Protocol Security or IPsec
• Application Layer: CfdpManager assumes CFDP traffic originates from authenticated sources validated at lower layers

CfdpManager accepts destination file paths as specified in incoming CFDP Metadata PDUs without application-layer path validation. This approach is consistent with the CCSDS 727.0-B-5 CFDP standard, which assumes operation over authenticated communication channels.

For mission deployments, ensure radio links employ hardware encryption or cryptographic authentication, ground systems implement proper authentication and authorization controls, and operational procedures include verification of file paths before commanding transfers.

Input Robustness

Because CfdpManager processes PDUs received from an external link, it must remain available even when the received bytes are malformed, degenerate, or hostile. The receive path treats structural properties of an incoming PDU as untrusted input and rejects or safely ignores them rather than relying on an FW_ASSERT, which would raise a FATAL and remove the deployment from service. Assertions in the CFDP code are reserved for internal invariants that cannot be influenced by received data.

A specific case handled here is a syntactically valid FileData PDU that declares a file offset but carries zero file-data octets (its PDU payload length equals the encoded offset length). Such an empty segment conveys no data: the receive handler treats it as a successful no-op — no file write and no gap-tracking update — so it can never produce a zero-length interval in the chunk tracker. This closes the denial-of-service reported in GHSA-mh5x-2m6h-8267, where a single zero-length Class 2 FileData PDU could reach a gap-tracking assertion and terminate the process. Note that this is an availability hardening measure; it does not by itself remove the need for the authenticated lower layers described above.

Main Class Hierarchy

CfdpManager (CfdpManager.hpp)

• Top-level F' component that integrates CFDP into the F' framework
• Provides F' port handlers for commands, data input/output, and periodic execution
• Owns a single Engine instance and delegates all protocol operations to it
• Manages component parameters and provides events/telemetry to the F' system

Engine (Engine.hpp)

• Core protocol engine that manages CFDP lifecycle and operations
• Owns multiple Channel instances (one per configured CFDP channel)
• Handles PDU routing and dispatching to appropriate transactions
• Manages transaction creation, initialization, and cleanup
• Implements top-level protocol state machine coordination

Channel (Channel.hpp)

• Encapsulates channel-specific operations and configuration
• Owns a pool of Transaction instances for that channel
• Manages playback directories and polling directories
• Handles transaction queuing with priority-based scheduling
• Controls flow state (normal/frozen) and PDU throttling

Transaction (Transaction.hpp)

• Represents individual file transfer operations
• Implements both TX (transmit) and RX (receive) state machines
• Handles Class 1 (unacknowledged) and Class 2 (acknowledged) protocol states
• Implementation split across TransactionTx.cpp and TransactionRx.cpp
• Manages file I/O, checksums, timers, and retry logic for each transaction

PDU Type Hierarchy

PduBase (Types/PduBase.hpp)

• Abstract base class for all CFDP Protocol Data Units
• Inherits from F' Fw::Serializable for consistent encoding/decoding
• Contains common PduHeader with transaction identification

Concrete PDU types (all in Types/ directory):

• MetadataPdu (MetadataPdu.hpp): Initiates file transfer with filename, size, and options
• FileDataPdu (FileDataPdu.hpp): Carries file data segments with offset information
• EofPdu (EofPdu.hpp): Signals end of file transmission with checksum and final size
• FinPdu (FinPdu.hpp): Indicates transaction completion with delivery status (Class 2 only)
• AckPdu (AckPdu.hpp): Acknowledges receipt of EOF or FIN directives (Class 2 only)
• NakPdu (NakPdu.hpp): Requests retransmission of missing file segments (Class 2 only)

Supporting Types and Utilities

Classes:

• Timer (Timer.hpp): CFDP timer implementation using F' time primitives for ACK timeouts and inactivity detection
• CfdpChunkList (Chunk.hpp): Gap tracking for Class 2 transfers; tracks received file segments and identifies missing data for NAK generation
• Clist (Clist.hpp): Intrusive circular linked list for efficient transaction queue management

Structs (defined in Types.hpp):

• History: Transaction history records for completed transfers; stores filenames, direction, status, and entity IDs
• Playback: Playback request state for directory playback and polling operations; manages directory iteration and transaction parameters
• CfdpChunkWrapper: Wrapper around CfdpChunkList for pooling and reuse across transactions

Utilities:

• Utils (Utils.hpp): Utility functions for transaction traversal, status conversion, and protocol helpers

Transmission and Receive Throttling

Transmission Throttling

Transmission throttling governs how many outgoing PDUs can be sent in a single execution cycle of the component. This mechanism prevents the CFDP engine from overwhelming downstream components (such as communication queues or radio interfaces) with excessive PDU traffic in a single scheduler invocation.

Configuration:

Transmission throttling is controlled by the ChannelConfig.max_outgoing_pdus_per_cycle parameter, which specifies the maximum number of outgoing PDUs that can be transmitted per channel per execution cycle. This limit applies to all outgoing PDU types including Metadata, File Data, EOF, ACK, NAK, and FIN PDUs.

Implementation:

The transmission throttling mechanism is implemented through a per-channel outgoing PDU counter that is reset at the beginning of each execution cycle. When a transaction requests a buffer to send a PDU, the implementation checks if the counter has reached the configured limit. If under the limit, the buffer is allocated and the counter is incremented. If the limit is reached, buffer allocation is denied and the transaction is deferred to the next cycle, with processing resuming from where it left off.

Buffer Management:

The transmission throttling mechanism works in conjunction with buffer allocation from downstream components. Two failure modes can occur: throttling limit reached (the max_outgoing_pdus_per_cycle limit is reached and no buffer allocation is attempted) or buffer exhaustion (the downstream buffer pool is exhausted and buffer allocation fails even when under the throttling limit). In both cases, the transaction defers PDU transmission until the next cycle by returning to a pending state and resuming processing in the next execution cycle. For Class 2 transactions, protocol timers (ACK, NAK, inactivity) continue running and will eventually trigger retransmissions or transaction abandonment if PDUs cannot be sent.

Receive Throttling

Unlike transmit operations that are driven by the periodic run1Hz scheduler port, receive operations in CfdpManager are driven by the dataIn async input port. Incoming CFDP PDUs arrive via this port and are processed immediately by the component's thread when the port handler is invoked, without per-cycle limits. Receive throttling was implemented in NASA's CF (CFDP) application because CF processes received PDUs during scheduled execution cycles. In contrast, CfdpManager processes incoming PDUs asynchronously as they arrive, so there is no architectural reason to throttle incoming PDUs.

Directory Playback and Polling

CfdpManager supports two related mechanisms for transferring the contents of a directory:

• Directory playback (PlaybackDirectory command): a one-shot operation that sends every file currently in the source directory as individual CFDP transactions and completes when the directory has been fully processed.
• Directory polling (PollDirectory command): a recurring operation that re-checks the source directory on a fixed interval and automatically sends any new files found. Each channel supports up to MaxPollingDirPerChan independent polling slots, identified by a poll index. The file is deleted from the directory after a successful transfer.

Poll cycle behavior:

Each polling slot owns an interval timer that is evaluated once per run1Hz cycle:

1. A poll slot is armed by the PollDirectory command with a non-zero interval (in seconds). A zero interval is rejected at command validation with an InvalidPollInterval event.
2. The interval timer only counts down while the slot's playback is not busy. While a directory playback triggered by a previous poll is still in progress (transactions pending or active), the timer is held so polls do not stack up.
3. When the timer expires, the slot initiates a playback of the source directory and re-arms the timer for the next interval. Re-arming happens regardless of whether the playback started successfully — playbackDirInitiate emits its own event on failure, and re-arming ensures the poll retries on the next interval rather than stalling.

Polling continues until stopped with the StopPollDirectory command. Stopping is only honored for a slot that is currently enabled; stopping an inactive slot produces a PollDirNotActive event.

Sequence Diagrams

The following sequence diagrams illustrate the external protocol exchanges between spacecraft and ground systems during CFDP transactions. These diagrams focus on the PDU-level interactions and do not depict the internal state machine transitions or detailed transaction processing logic within the CfdpManager component.

Class 1 TX Transaction (Unacknowledged)

This diagram shows a Class 1 file transmission from spacecraft to ground. Class 1 is unacknowledged and provides no retransmission or delivery guarantees.

sequenceDiagram
    participant Ground
    participant Spacecraft

    Ground->>Spacecraft: SendFile command
(source file, destination file)

    Note over Spacecraft: Initialize transaction

    Spacecraft->>Ground: Metadata PDU
(filename, size)

    loop File Data Transfer
        Spacecraft->>Ground: File Data PDU
(offset, data segment)
    end

    Spacecraft->>Ground: EOF PDU
(checksum, file size)

    Note over Spacecraft: Transaction complete
(no acknowledgment)
    Note over Ground: Verify checksum
Keep or discard file

Key characteristics:

• No acknowledgments (ACK, NAK, or FIN PDUs)
• No retransmissions or gap detection
• Sender completes immediately after sending EOF
• Receiver validates checksum and keeps/discards file independently

Class 2 TX Transaction (Acknowledged)

This diagram shows a Class 2 file transmission from spacecraft to ground with gap detection and retransmission. The scenario includes a missing File Data PDU that is detected and retransmitted via NAK.

sequenceDiagram
    participant G_ACK as Ground
ACK Timer
    participant G_NACK as Ground
NACK Timer
    participant Ground
    participant Spacecraft
    participant S_ACK as Spacecraft
ACK Timer

    Ground->>Spacecraft: SendFile command
(source file, destination file)

    Note over Spacecraft: Initialize transaction

    Spacecraft->>Ground: Metadata PDU
(filename, size)

    Spacecraft->>Ground: File Data PDU (1)
    Spacecraft--xGround: File Data PDU (2) [LOST]
    Spacecraft->>Ground: File Data PDU (3)

    Spacecraft->>Ground: EOF PDU
(checksum, file size)

    activate S_ACK
    Note over S_ACK: Armed on
EOF send

    Ground->>Spacecraft: ACK(EOF)

    deactivate S_ACK
    Note over S_ACK: Cancelled on
ACK(EOF) received

    Note over Ground: Gap detected
(missing PDU (2))

    Ground->>Spacecraft: NAK
(request PDU (2))

    activate G_NACK
    Note over G_NACK: Armed on
NAK send

    Spacecraft->>Ground: File Data PDU (2) [RETRANSMIT]

    deactivate G_NACK
    Note over G_NACK: Cancelled on
gap fill

    Note over Ground: All data received
Verify checksum

    Ground->>Spacecraft: FIN PDU
(delivery complete, file retained)
    Note over Ground: File saved and
ready for use

    activate G_ACK
    Note over G_ACK: Armed on
FIN send

    Spacecraft->>Ground: ACK(FIN)
    Note over Spacecraft: Transaction complete

    deactivate G_ACK
    Note over G_ACK: Cancelled on
ACK(FIN) received

    Note over Ground: Transaction complete

Key characteristics:

• Full acknowledgment and retransmission support
• EOF is acknowledged to confirm reception
• Ground detects missing data and sends NAK with gap information
• Spacecraft retransmits requested segments
• NAK processing during file data transmission:
  • NAKs received during file data transmission (before EOF is sent) are processed immediately
  • Requested gap segments are queued and retransmitted with priority over new file data
  • This allows gaps to be filled immediately upon detection, rather than waiting for EOF acknowledgment
• FIN PDU from receiver confirms final delivery status
• Timers ensure protocol progress and detect failures
  • Spacecraft ACK timer: Armed when EOF is sent with duration ChannelConfig.ack_timer, cancelled when ACK(EOF) or FIN is received. If the timer expires before receiving acknowledgment, the spacecraft retransmits EOF and rearms the timer. After ChannelConfig.ack_limit retries without acknowledgment, the transaction is abandoned with status ACK_LIMIT_NO_EOF
• Transaction completes only after FIN/ACK exchange

Class 2 RX Transaction (Acknowledged)

This diagram shows a Class 2 file reception at the spacecraft from ground with gap detection and retransmission. The scenario includes a missing File Data PDU that is detected and retransmitted via NAK.

sequenceDiagram
    participant G_ACK as Ground
ACK Timer
    participant Ground
    participant Spacecraft
    participant S_NAK as Spacecraft
NAK Timer
    participant S_ACK as Spacecraft
ACK Timer

    Note over Ground: Initialize transaction

    Ground->>Spacecraft: Metadata PDU
(filename, size)

    Ground--xSpacecraft: File Data PDU (1) [LOST]
    Ground->>Spacecraft: File Data PDU (2)
    Ground--xSpacecraft: File Data PDU (3) [LOST]
    Ground->>Spacecraft: File Data PDU (4)

    Ground->>Spacecraft: EOF PDU
(checksum, file size)

    activate G_ACK
    Note over G_ACK: Armed on
EOF send

    Spacecraft->>Ground: ACK(EOF)

    deactivate G_ACK
    Note over G_ACK: Cancelled on
ACK(EOF) received

    Note over Spacecraft: Gaps detected
(missing PDUs (1) and (3))

    Spacecraft->>Ground: NAK
(request PDUs (1) and (3))

    activate S_NAK
    Note over S_NAK: Armed on
NAK send

    Ground->>Spacecraft: File Data PDU (1) [RETRANSMIT]
    Ground->>Spacecraft: File Data PDU (3) [RETRANSMIT]

    deactivate S_NAK
    Note over S_NAK: Cancelled on
gaps filled

    Note over Spacecraft: All data received
Verify checksum

    Spacecraft->>Ground: FIN PDU
(delivery complete, file retained)
    Note over Spacecraft: File saved and
ready for use

    activate S_ACK
    Note over S_ACK: Armed on
FIN send

    Ground->>Spacecraft: ACK(FIN)
    Note over Ground: Transaction complete

    deactivate S_ACK
    Note over S_ACK: Cancelled on
ACK(FIN) received

    Note over Spacecraft: Transaction complete

Key characteristics:

• Full acknowledgment and retransmission support
• EOF is acknowledged to confirm reception
• Spacecraft detects missing data and sends NAK with gap information
• Ground retransmits requested segments
• FIN PDU from receiver confirms final delivery status
• Timers ensure protocol progress and detect failures
  • Spacecraft NAK timer: Armed when NAK is sent with duration ChannelConfig.ack_timer, cancelled when all requested data is received. If the timer expires before receiving retransmitted data, the spacecraft sends another NAK and rearms the timer. After ChannelConfig.nack_limit retries without data, the transaction is abandoned with status NAK_LIMIT_REACHED
  • Spacecraft ACK timer: Armed when FIN is sent with duration ChannelConfig.ack_timer, cancelled when ACK(FIN) is received. If the timer expires, the spacecraft retransmits FIN and rearms the timer. After ChannelConfig.ack_limit retries without ACK(FIN), the transaction is abandoned
• Transaction completes only after FIN/ACK exchange

Configuration

CfdpManager uses compile-time configuration defined in two files:

• CfdpCfg.fpp: FPP constants and types visible to both FPP and C++ code
• CfdpCfg.hpp: C++ preprocessor definitions for implementation details

FPP Constants (CfdpCfg.fpp)

These constants are defined in the Svc.Ccsds.Cfdp module and must be configured at compile time:

FPP Types (CfdpCfg.fpp)

These types define the size of CFDP protocol fields:

C++ Configuration Constants (CfdpCfg.hpp)

Protocol Configuration

Resource Pool Configuration

Events

The CFDP Manager provides comprehensive event reporting covering all aspects of file transfer operations, organized by functional category. Most events are warning-level to alert operators of potential issues, while activity-high events mark significant milestones like transfer start/completion and transaction control operations.

Command/Control Events

PDU Serialization/Deserialization Errors

RX Transaction Events

TX Transaction Events

File Transfer Complete Events

Transaction Control Events

Miscellaneous/Diagnostic Events

Commands

Parameters

Deep Space Timer Configuration

The timer parameters (ack_timer, inactivity_timer, ack_limit, nack_limit) must be configured appropriately for the communication delay environment:

• Near-Earth Operations: Default values (ack_timer=3s, inactivity_timer=30s) are appropriate for round-trip light times of 1-2 seconds
• Lunar Operations: Modest increases recommended (ack_timer=5-10s, inactivity_timer=60-120s) for ~2.5 second round-trip light times
• Deep Space Operations: Significant increases required (ack_timer and inactivity_timer scaled to mission-specific round-trip light times, which can range from minutes to hours)

Critical Relationship: The ack_timer must be longer than the round-trip light time to avoid premature retransmissions. The inactivity_timer should be several times larger than ack_timer to account for file segmentation and processing delays.

CfdpManager's per-channel parameter architecture supports multiple mission profiles simultaneously. Different channels can be configured for near-Earth, lunar, and deep space operations, allowing the system to communicate with multiple destinations concurrently.

Telemetry

Telemetry is emitted as the ChannelTelemetry array, one ChannelTelemetry struct per CFDP channel. Each struct contains the following fields:

Receive Counters

Sent Counters

Fault Counters

Queue Depths

Activity Counters

Requirements