FileHandling Subtopology — Software Design Document (SDD)

The FileHandling subtopology packages the core file-transfer services commonly needed in F´ deployments: file uplink (ground → flight), file downlink (flight → ground), on-board file management, and parameter management via filesystem. By providing these as a pre-wired subgraph, integration engineers avoid repetitive wiring and get a consistent, reusable baseline for file operations.

1. Requirements

2. Design & Core Functions

2.1 Instance Summary

2.2 Configuration Hooks inside the Subtopology

• Uses instance properties (IDs, queue sizes, stack sizes, priorities, CPU affinities) defined in FileHandlingConfig for these static instances (see §4).

2.3 Required Inputs for Operation

• Rate Groups: Connect scheduler outputs to the Run (scheduling) ports of fileDownlink.
• PrmDb file name: Call FileHandling::prmDb.configure(<file name>) from your topology setup code before parameters are loaded; the subtopology does not set a file name itself, and PrmDb asserts if parameters are read or saved without one.
• Communication/Framing Stack: Wire file-packet ports between FileHandling and your COM/framing subtopology (e.g., ComCcsds, ComFprime, FramingFprime, FramingCcsds) to complete uplink/downlink paths.

[!WARNING] This subtopology is not configured to be secure by default. For backwards compatibility, it intentionally does not configure the file-access sandboxes of its components, leaving them fail-open: fileUplink may write, fileDownlink may read, and prmDb (PRM_LOAD_FILE) may load from any absolute path accessible to the process via ground command. Security-conscious deployments must call the following from topology setup code:

• FileHandling::fileUplink.configure(<directory>) — restrict uplinked file writes.
• FileHandling::fileDownlink.configure(<directory>) — restrict downlink reads (note: the configure(cooldown, cycleTime, fileQueueDepth) overload called by this subtopology does not set a sandbox).
• FileHandling::prmDb.configureLoadSandbox(<directory>) — restrict PRM_LOAD_FILE reads (note: prmDb.configure(<file name>) sets the store-file name and is not a load sandbox).

2.4 Limitations

Focused on file transfer and on-board file ops only. It does not provide general uplink/downlink routing for non-file traffic, framing/deframing for non-file data, or broader CDH services.

3. Usage

3.1 Example Usage

topology Flight {
  instance FileHandling.Subtopology

  param connections instance FileHandling.prmDb

  # Schedule the active/queued file components (example)
  connections RateGroups {
    rg.RateGroupMemberOut[0] -> FileHandling.Subtopology.fileDownlinkRun
  }

  connections ComCcsds_FileHandling {
    # File Downlink <-> ComQueue
    FileHandling.Subtopology.fileDownlinkBufferSendOut -> ComCcsds.Subtopology.bufferQueueIn[ComCcsds.Ports_ComBufferQueue.FILE]
    ComCcsds.Subtopology.bufferReturnOut[ComCcsds.Ports_ComBufferQueue.FILE] -> FileHandling.Subtopology.fileDownlinkBufferReturn
    
    # Router <-> FileUplink
    ComCcsds.Subtopology.fileUplinkOut                    -> FileHandling.Subtopology.fileUplinkBufferSendIn
    FileHandling.Subtopology.fileUplinkBufferSendOut     -> ComCcsds.Subtopology.fileUplinkReturnIn
  }

4. Configuration

Configure only the instance properties for the static instances owned by the subtopology. All knobs live under: Svc/Subtopologies/FileHandling/FileHandlingConfig/FileHandlingConfig.fpp. The generated constants header for this module (e.g., FppConstantsAc.hpp) reflects these settings. ([FPrime][2])

4.1 Component properties (FileHandlingConfig.fpp)

• Base ID — Base identifier for the subtopology; component IDs are offset from this base.
• Queue sizes — Queue depths for fileUplink, fileDownlink, fileManager.
• Stack sizes — Task stacks for active components (fileUplink, fileDownlink).
• Priorities — RTOS priorities for the active/queued components as applicable.
• CPU affinities — Core pinning for active component tasks; defaults to TASK_DEFAULT (no pinning).

These knobs tailor runtime footprint and scheduling without modifying the subtopology wiring.

5. Traceability Matrix