F´（F Prime）框架 Svc::DpWriter 数据产品落盘组件完全指南：端口、文件格式与配置详解

嵌入式系统编程【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址https://gitcode.com/gh_mirrors/fp/fprime点击查看免费下载Svc::DpWriter是 F´F Prime飞行软件与嵌入式系统框架中的一个活动组件active component负责把填充好数据的产品容器data product container缓冲区写入磁盘。它在数据产品链路中位于Svc::DpManager之后是数据产品产生 → 管理 → 落盘流水线的最终存储环节。读完本文你将掌握 DpWriter 的端口定义、缓冲区校验与处理流程、可配置的文件命名格式、遥测/事件接口以及如何将其接入实际拓扑。1. 组件概览与职责Svc::DpWriter的核心职责可用一句话概括接收装满数据产品容器的缓冲区执行请求的加工处理如数据压缩然后把缓冲区内容写为磁盘文件。其完整工作流如下接收包含已填充数据产品容器的缓冲区。这些缓冲区通常来自一个或多个数据产品生产组件在到达 DpWriter 之前一般会先经过 Svc::DpManager 实例并可能再经过 Svc::BufferAccumulator 实例。对收到的每个缓冲区B执行请求的处理如数据压缩处理以就地in place更新方式修改缓冲区内存将B写入磁盘若通知端口已连接则发出写入已发生的通知。例如 Svc::DpCatalog 实例可接收该通知并据此更新数据产品目录catalog。从实现上看DpWriter 由 FPP 模型文件 Svc/DpWriter/DpWriter.fpp 定义实现类位于 Svc/DpWriter/DpWriter.hpp 与 Svc/DpWriter/DpWriter.cpp继承自动生成的DpWriterComponentBase。2. 需求与验证设计文档以需求表形式固化了组件的契约全部通过单元测试验证需求描述理由验证方法SVC-DPWRITER-001Svc::DpWriter应提供一个用于接收指向已填充数据产品容器的Fw::Buffer对象的端口DpWriter 的用途是将数据产品写入磁盘单元测试SVC-DPWRITER-002Svc::DpWriter应提供一组用于发送Fw::Buffer对象以供处理的端口该需求支持对缓冲区中的数据进行下游处理单元测试SVC-DPWRITER-003收到数据产品容器C后Svc::DpWriter应使用C头部中的处理类型字段来选择要调用的零个或多个处理端口按端口顺序调用处理类型字段是一个位掩码掩码中位2^n置 1 表示选择端口索引n单元测试SVC-DPWRITER-004收到Fw::BufferB并在执行完任何请求的处理后Svc::DpWriter应将B写入磁盘DpWriter 的用途是将数据产品写入磁盘单元测试SVC-DPWRITER-005Svc::DpWriter应提供一个用于通知其他组件数据产品已写入的端口该需求允许Svc::DpCatalog或类似组件实时更新其目录单元测试SVC-DPWRITER-006Svc::DpManager应提供报告已接收缓冲区数量、已写入数据产品数量、已写入字节数、写入失败次数和错误次数的遥测该需求建立了组件的遥测接口单元测试上述需求的测试场景可在 Svc/DpWriter/test/ut/README.md 中找到BufferSendIn::OK规则一次性覆盖 SVC-DPWRITER-001 至 005SchedIn::OK规则覆盖 SVC-DPWRITER-006另有InvalidBuffer、BufferTooSmallForPacket、InvalidHeaderHash、InvalidHeader、BufferTooSmallForData、FileOpenError、FileWriteError等失败路径规则。3. 组件设计3.1 组件结构图下图展示了DpWriter组件的整体结构来源Svc/DpWriter/docs/img/DpWriter.png。3.2 端口定义DpWriter 的端口在 DpWriter.fpp 中声明完整清单如下种类名称端口类型用途async inputschedInSvc.Sched调度输入端口async inputbufferSendInFw.BufferSend接收要写入磁盘的数据产品outputprocBufferSendOut[DpWriterNumProcPorts] Fw.BufferSend处理数据产品outputdpWrittenOutDpWritten发送DpWritten通知outputdeallocBufferSendOutFw.BufferSend释放数据产品缓冲区command recvcmdIn—命令接收端口command regcmdRegIn—命令注册端口command respcmdResponseOut—命令响应端口time gettimeGetOutFw.Time时间获取端口telemetrytlmOutFw.Tlm遥测端口eventeventOutFw.Log事件端口text eventtextEventOutFw.LogText文本事件端口其中bufferSendIn与schedIn为异步输入端口意味着缓冲区处理会在独立线程队列上下文中执行不会阻塞数据产品生产链路。3.3 状态维护设计文档记录组件维护以下内部状态numDataProducts (U32)已写入的数据产品数量。numBytes (U64)已写入的字节数。从 DpWriter.hpp 的成员变量可以看出实现层面细化为五个计数器m_numBuffersReceived已接收缓冲区数、m_numBytesWritten已写字节数、m_numSuccessfulWrites成功写入次数、m_numFailedWrites失败写入次数与m_numErrors错误次数。这些计数器在schedIn_handler中被作为遥测发出详见第 6 节。3.4 编译期配置处理端口数量配置常量DpWriterNumProcPorts指定用于连接处理组件的端口数组大小默认值为 5。该常量在DpWriter.fpp中被引用以实例化procBufferSendOut端口数组。文件名称格式配置DP_FILENAME_FORMAT指定数据产品文件名格式默认值为%s/Dp_%08 PRI_FwDpIdType _%08 PRIu32 _%08 PRIu32 .fdp即形如Dp_容器ID_时间秒_时间微秒.fdp。3.5 运行期配置可通过调用configure函数提供 DP 文件名前缀dpFileNamePrefix该前缀用于构造待写入文件的名称// DpWriter.hpp void configure(const Fw::StringBase dpFileNamePrefix); // DpWriter.cpp 中的实现 void DpWriter::configure(const Fw::StringBase dpFileNamePrefix) { this-m_dpFileNamePrefix dpFileNamePrefix; }如果不调用configureDP 文件名前缀默认为空字符串。文件名前缀的确切含义取决于格式字符串——通常它是一个目录路径前缀。例如参考部署 Ref/Top/RefTopology.cpp 中dpWriter.configure(dpDir);即把下载目录路径作为前缀传入。4. 端口处理逻辑Port Handlers4.1 schedInschedIn处理器把内部状态变量作为遥测发出。对应实现见 DpWriter.cpp依次输出NumBuffersReceived、NumBytesWritten、NumSuccessfulWrites、NumFailedWrites、NumErrors五项遥测。4.2 bufferSendInbufferSendIn处理器接收缓冲区B的可变引用执行一串严格的校验与处理流水线见 DpWriter.cpp校验缓冲区有效性若B无效发出InvalidBuffer警告事件。校验缓冲区大小若B的大小不足以容纳一个数据产品容器报文Fw::DpContainer::MIN_PACKET_SIZE发出BufferTooSmallForPacket警告事件。MIN_PACKET_SIZE定义为Header::SIZE 2 * HASH_DIGEST_LENGTH头部 头部哈希 数据哈希见 Fw/Dp/DpContainer.hpp。校验头部哈希通过container.checkHeaderHash(storedHash, computedHash)检查头部哈希有效性失败则发出InvalidHeaderHash警告事件。反序列化报文头部通过deserializePacketHeader调用container.deserializeHeader()失败则发出InvalidHeader警告事件携带反序列化错误码。校验数据大小将报文头部记录的数据大小container.getPacketSize()与缓冲区大小比对超出则发出BufferTooSmallForData警告事件。执行加工处理从容器头部读取ProcType字段得到位掩码M按端口顺序遍历procBufferSendOut若端口号N在M中置位则调用procBufferSendOut第N号端口并传入B。此步骤就地更新B指向的内存。核心逻辑见performProcessingDpWriter.cppconst Fw::DpCfg::ProcType::SerialType procTypes container.getProcTypes(); for (FwIndexType portNum 0; portNum NUM_PROCBUFFERSENDOUT_OUTPUT_PORTS; portNum) { if ((procTypes (1 portNum)) ! 0) { this-procBufferSendOut_out(portNum, buffer); } }这正是需求 SVC-DPWRITER-003 所述的位掩码语义位2^n置 1 即调用端口索引n。多个处理端口可以同时被选中并按端口号升序调用。构造文件名并写盘使用DP_FILENAME_FORMAT格式化文件名其中时间戳取自timeGetOut端口由容器头部中的 time tag 提供秒与微秒随后调用writeFileDpWriter.cpp通过Os::File::open(..., Os::File::OPEN_CREATE)创建文件并写入容器报文数据。发送通知若写盘成功且dpWrittenOut已连接则通过sendNotification发送文件名、优先级与文件大小DpWriter.cpp。释放缓冲区若B有效则通过deallocBufferSendOut发送B以释放内存。任何一步校验失败都会使流程提前终止并累加错误计数m_numErrors写盘失败则额外累加m_numFailedWrites成功则累加m_numSuccessfulWrites。5. 文件格式5.1 数据格式每个文件存储一条序列化后的数据产品记录record其格式遵循 数据产品文档 描述的序列化格式每个数据产品容器在序列化形式上依次为头部Header→ 头部哈希Header Hash→ 数据Data→ 数据哈希Data Hash。头部包含PacketDescriptorFW_PACKET_DP、容器 ID、优先级、时间标签、处理类型位掩码、用户数据、数据产品状态与数据大小等字段数据部分则是一系列单值记录或数组记录。写入磁盘时DpWriter 以container.getPacketSize()作为待写字节数即整个容器的序列化总长度。5.2 文件命名每个文件的名称由可配置的格式字符串DP_FILENAME_FORMAT格式化而成。格式字符串必须按顺序包含以下四个参数的格式说明格式说明符类型DP 文件名前缀%s容器 ID%PRI_FwDpIdType时间秒%PRI_u32时间微秒%PRI_u32DP 文件名前缀的确切含义取决于格式字符串——典型情况下它是一个目录路径前缀。仓库默认格式为%s/Dp_%08 PRI_FwDpIdType _%08 PRIu32 _%08 PRIu32 .fdp即生成形如前缀/Dp_8位容器ID_8位秒_8位微秒.fdp的文件名。容器 ID 来自container.getId()时间戳来自container.getTimeTag()见 DpWriter.cpp。6. 地面接口Ground Interface6.1 命令种类名称描述asyncCLEAR_EVENT_THROTTLE清除事件节流throttle计数该命令在 DpWriter.cpp 中实现会依次清除七个警告事件BufferTooSmallForData、BufferTooSmallForPacket、FileOpenError、FileWriteError、InvalidBuffer、InvalidHeaderHash、InvalidHeader的节流计数并以Fw::CmdResponse::OK响应。6.2 遥测设计文档中的NumDataProducts/NumBytes在 FPP 模型中被细化为五个遥测通道见 DpWriter.fpp全部为update on change类型由schedIn周期触发输出名称类型描述NumBuffersReceivedU32已接收的缓冲区数量NumBytesWrittenU64已写入的字节数NumSuccessfulWritesU32成功写入次数NumFailedWritesU32失败写入次数NumErrorsU32错误次数这五项遥测对应需求 SVC-DPWRITER-006。参考部署在 Ref/Top/RefPackets.xml 中将这些通道纳入了下行遥测包。6.3 事件FPP 模型实际定义的事件如下警告事件均带throttle 10节流名称严重级别描述InvalidBufferwarning high接收到的缓冲区无效BufferTooSmallForPacketwarning high缓冲区过小无法容纳数据产品报文携带缓冲区大小与最小要求大小InvalidHeaderHashwarning high头部哈希无效携带缓冲区大小、存储哈希与计算哈希InvalidHeaderwarning high报文头部反序列化失败携带缓冲区大小与错误码BufferTooSmallForDatawarning high缓冲区过小无法容纳头部指定的数据大小FileOpenErrorwarning high打开文件出错携带状态码与文件名FileWriteErrorwarning high写入文件出错携带状态码、已写字节数与目标字节数FileWrittenactivity low文件写入成功携带字节数与文件名注设计文档中的BufferInvalid、BufferTooSmall、InvalidPacketDescriptor分别对应 FPP 模型中的InvalidBuffer、BufferTooSmallForPacket/BufferTooSmallForData、InvalidHeader/InvalidHeaderHash请以 DpWriter.fpp 中的最终命名为准。7. 使用示例与拓扑接入7.1 拓扑连接下面的拓扑图展示了如何将Svc::DpWriter连接到DpManager组件与一个处理器组件来源Svc/DpWriter/docs/img/top/product-write.png。图中使用以下实例dpManager一个 Svc::DpManager 实例。dpProcessor一个处理数据产品容器的组件。dpWriter一个Svc::DpWriter实例。producer一个产生数据产品的组件。连接关系见 Svc/DpWriter/docs/img/top/product-write.txtproducer.productSendOut[0] - dpManager.productSendIn[0] dpManager.productSendOut[0] - dpWriter.bufferSendIn[0] dpWriter.procBufferSendOut[0] - dpProcessor.bufferSendIn[0] dpWriter.deallocBufferSendOut[0] - bufferManager.bufferSendIn[0]参考部署 Ref/Top 中给出了真实的接入方式见 topology.fpprateGroup3Comp.RateGroupMemberOut[5]驱动dpWriter.schedIn以周期刷新遥测dpMgr.productSendOut[0]连接dpWriter.bufferSendIndpWriter.deallocBufferSendOut连接dpBufferManager.bufferSendIn完成缓冲区回收。7.2 时序流程下图展示缓冲区发送到 DpWriter、被处理并写入磁盘的完整时序7.3 单元测试组件测试采用 STest 规则/场景Rule/Scenario模式测试代码位于 Svc/DpWriter/test/ut测试说明见 README。测试通过Os::Stub::File::Test::StaticData模拟文件打开/写入的成败状态覆盖了正常写入、无效缓冲区、缓冲区过小、头部哈希无效、头部反序列化失败、数据越界、文件打开失败、文件写入失败以及CLEAR_EVENT_THROTTLE命令等全部路径是验证本组件行为的最佳参考。8. 小结Svc::DpWriter是 F´ 数据产品框架的落盘终点它以异步端口接收来自DpManager的容器缓冲区经过缓冲区有效性、大小、头部哈希与反序列化等五重校验后按处理类型位掩码调度零个或多个处理端口最终以DP_FILENAME_FORMAT格式命名文件写入磁盘并通过dpWrittenOut通知DpCatalog等下游组件更新目录。编译期可通过DpWriterNumProcPorts与DP_FILENAME_FORMAT定制端口数量与文件命名运行期可通过configure注入文件名前缀配合五项遥测通道与八个事件通道可完整观测数据产品的写入健康状态。理解该组件的端口语义与校验流程是构建可靠的数据产品存储链路如遥测归档、科学数据下传的基础。赞分享嵌入式系统编程【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址https://gitcode.com/gh_mirrors/fp/fprime点击查看免费下载相关推荐F´ 框架 Svc::DpWriter 数据产品落盘组件完全指南从端口设计到文件格式与实战拓扑F´ 框架 Svc::DpWriter 数据产品落盘组件完全指南从端口设计到文件格式与实战拓扑 本篇技术指南聚焦 F´F Prime飞行软件与嵌入式系统框嵌入式系统编程F´ 数据产品框架 Fw::Dp 完全指南DpContainer 序列化格式与端口详解F´ 数据产品框架 Fw::Dp 完全指南DpContainer 序列化格式与端口详解 F´F Prime飞行软件与嵌入式系统框架通过 Fw::Dp 构建嵌入式系统编程F´ (F Prime) 飞行软件框架中的 Svc::ActiveRateGroup 速率组调度组件详解F´ F Prime 飞行软件框架中的 Svc::ActiveRateGroup 速率组调度组件详解 Svc::ActiveRateGroup 是 F´ 飞行软嵌入式系统编程上一篇MyViewOfLinuxSystems实战教程如何用draw.io绘制Linux系统架构图下一篇Polymarket Copy Trading Bot安全防护私钥管理、API安全与风险控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考