F´（F Prime）文件处理端口族解析：FileAnnounce / FileDispatch / FileWorker 端口定义与在文件上行链路中的应用

F´（F Prime）文件处理端口族解析：FileAnnounce / FileDispatch / FileWorker 端口定义与在文件上行链路中的应用

【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime

在 F´（F Prime）飞行软件与嵌入式系统框架中，Svc/Ports/FilePorts目录集中定义了组件之间进行文件交接与文件读写协作的一组端口。本文以该目录的 SDD 文档（Svc/Ports/FilePorts/docs/sdd.md）为核心，结合仓库内 FPP 源码、FileUplink/FileDispatcher组件及其事件与遥测定义，系统讲解这组端口的设计意图、参数语义、装配方式，以及它们在上行文件分发链路中的真实调用关系，帮助你在自己的部署中正确连接并复用这些文件处理端口。

一、FilePorts 目录定位：组件间文件协作的端口契约层

Svc/Ports/FilePorts目录本身不包含任何业务组件实现，它只承载FPP 端口定义（port definition），作为 F´ 组件模型中"文件协作"的公共契约。目录结构如下：

• Svc/Ports/FilePorts/FileAnnounce.fpp —— 文件就绪通知端口；
• Svc/Ports/FilePorts/FileDispatch.fpp —— 文件分发路由端口；
• Svc/Ports/FilePorts/FileWorkerPorts.fpp —— 文件读写、完成信号、取消与校验等工作级端口；
• Svc/Ports/FilePorts/CMakeLists.txt —— 将上述三个 FPP 文件注册进自动代码生成（autocoder）构建。

从构建层面看，CMakeLists.txt 通过register_fprime_module的AUTOCODER_INPUTS把三个.fpp文件交给 F´ 的 autocoder，生成对应的 C++ 端口基类与序列化代码。因此，任何组件只要在自身的.fpp中声明output port xxx: Svc.FileAnnounce（或input port），即可获得这一统一契约，无需各自重复定义。

提示：本目录中的端口类型都依赖Svc命名空间与FileNameStringSize常量，该常量在 default/config/AcConstants.fpp 中定义为constant FileNameStringSize = 240，即文件名字符串的默认容量上限为 240 字符，可在部署配置中按需调整。

二、FileAnnounce：文件就绪通知端口

2.1 端口定义与参数语义

根据 SDD 文档的 Port Descriptions 表格，FileAnnounce的唯一用途是：当新文件生产完成时，向感兴趣的组件广播该文件已就绪。其完整 FPP 定义位于 Svc/Ports/FilePorts/FileAnnounce.fpp：

module Svc{ @ Port for announcing new files port FileAnnounce( ref file_name: string size FileNameStringSize @< The successfully uplinked file ) }

关键点：

ref关键字意味着调用方与接收方共享同一份字符串内存，F´ 的 autocoder 会为其生成引用类型的序列化接口，这在高频事件通知场景下可减少拷贝开销。

2.2 上游生产者：FileUplink 的 fileAnnounce 输出端口

SDD 文档示例中明确指出：Svc/FileUplink 使用该端口对外宣布文件上行完成。在 Svc/FileUplink/FileUplink.fpp 中可以看到：

@ Announce a received file for further processing output port fileAnnounce: Svc.FileAnnounce

其调用时机由 Svc/FileUplink/docs/sdd.md 的 END 报文处理流程明确规定：

• 收到 END 报文且校验和匹配时，发出FileReceived事件，并在已连接的情况下触发fileAnnounce输出端口，同时累加FilesReceived遥测；
• 若校验和（checksum）不匹配，则只发出BadChecksum警告并累加FilesReceivedFailed遥测，不会触发fileAnnounce。

这意味着fileAnnounce是"校验通过、文件完整落地"的唯一对外信号，下游组件可以放心地基于它开始消费新文件。

2.3 下游消费者：FileDispatcher 的 fileAnnounceRecv 输入端口

FileAnnounce的典型消费者是Svc::FileDispatcher。在其 SDD（Svc/FileDispatcher/docs/sdd.md）中，输入端口fileAnnounceRecv的描述即为"接收新文件的文件名"，端口类型正是Svc.FileAnnounce。数据流如下：

Svc::FileUplink.fileAnnounce ──► Svc::FileDispatcher.fileAnnounceRecv （文件上行校验完成） （依据扩展名映射表路由到处理组件）

三、FileDispatch：按文件类型路由到处理组件的分发端口

3.1 端口定义

FileDispatch.fpp 定义了文件分发端口：

module Svc{ @ Port for dispatching files port FileDispatch( ref file_name: string size FileNameStringSize @< The file to dispatch ) }

它与FileAnnounce参数签名一致（文件名 +FileNameStringSize），但语义不同：FileDispatch用于把文件按类型路由给对应的处理组件，而FileAnnounce只负责"通知就绪"。

3.2 FileDispatcher 中的使用：端口数组 + 扩展名映射表

FileDispatcher把Svc.FileDispatch声明为输出端口数组（见 Svc/FileDispatcher/FileDispatcher.fpp 与 SDD 的 Port Descriptions），并通过用户提供的映射表把文件扩展名映射到具体的端口序号：

• 用户配置表为FileDispatcherTable，结构见 default/config/FileDispatcherCfg.fpp；
• 每条entries记录包含fileExt（要匹配的扩展名/后缀）、port（FileDispatchPort枚举中的端口号）与enabled（初始是否启用，可用ENABLE_DISPATCH命令动态开关）；
• numEntries必须满足0 < numEntries <= Svc::FileDispatcherCfg::FILE_DISPATCHER_MAX_TABLE_SIZE，否则触发断言；
• 匹配命中时发出FileDispatched事件并调用对应输出端口；若输出端口未连接，则发出（带节流的）FileDispatchPortNotConnected事件。

FileDispatch也出现在命令序列器等组件中（如 Svc/CmdSequencer/CmdSequencer.fpp），可见它是一个被多组件复用的通用"文件路由"端口契约。

四、FileWorkerPorts：文件读写工作级端口族

FileWorkerPorts.fpp定义了文件读写链路上更底层的六个端口，通常用于"文件处理 Worker"类组件（如文件压缩、加密、校验等耗时任务）：

其中Fw.Buffer是 F´ 的缓冲区类型（定义见 Fw/Buffer/Buffer.fpp），FwSizeType为框架尺寸类型。这组端口把"读、写、完成、取消、校验"拆成细粒度契约，便于实现可替换的文件处理后端。

五、在部署中连接这些端口

5.1 最小连接示例（拓扑层面）

典型的上行文件分发链路在拓扑（Topology）中按如下方式装配：

instance fileUplink: Svc.FileUplink base id 0x0400 instance fileDispatcher: Svc.FileDispatcher base id 0x0500 connections FileHandling { fileUplink.fileAnnounce -> fileDispatcher.fileAnnounceRecv fileDispatcher.fileDispatch[0] -> fileProcessorA.fileHandler fileDispatcher.fileDispatch[1] -> fileProcessorB.fileHandler }

即：FileUplink校验完成 →fileAnnounce通知FileDispatcher→FileDispatcher按扩展名查表 → 经fileDispatch[port]路由到具体处理组件。

5.2 注意 FileUplink 沙箱配置前提

使用FileAnnounce前需确认上行写入配置已就绪：FileUplink 的写入被限制在configure(directory)指定的沙箱目录内，且沙箱为fail-closed设计——未配置时所有打开操作都以OUTSIDE_SANDBOX拒绝。部署必须在拓扑初始化阶段调用configure(directory)（内置FileHandling子拓扑默认配置为"/"，安全敏感场景须重新限制目录）。只有文件成功写入并通过校验，fileAnnounce才会被触发。

5.3 验证手段

• 单元测试：FileUplink的测试位于 Svc/FileUplink/test/ut，用fprime-util check运行；FileDispatcher的测试位于 Svc/FileDispatcher/test/ut/FileDispatcherTester.cpp，覆盖扩展名匹配、全部禁用、命令启停与 ping 等场景；
• 运行观测：观察FileReceived/UplinkCanceled事件，以及FilesReceived、FilesReceivedFailed、PacketsReceived、Warnings四条遥测（定义见 Svc/FileUplink/Telemetry.fppi），即可确认fileAnnounce是否按预期触发。

六、总结

Svc/Ports/FilePorts用三个 FPP 文件把文件协作的关键语义固化为可复用端口契约：FileAnnounce负责"文件就绪"通知，FileDispatch负责按类型路由，FileWorkerPorts提供读写/完成/取消/校验的工作级接口。理解并正确装配这组端口，是打通 F´ 部署中"文件上行 → 校验 → 通知 → 分发 → 处理"完整链路的基础；结合FileUplink与FileDispatcher的实现与测试，你可以在自己的拓扑中快速复现这条链路并按需扩展处理组件。

【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime