F´ (F Prime) 事件日志端口深度解析：Fw::Log 与 Fw::LogText 端口的设计、序列化与使用指南

嵌入式系统编程【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址https://gitcode.com/gh_mirrors/fp/fprime点击查看免费下载导读本文聚焦 F´F Prime飞行软件框架中负责事件日志Event Log传输的核心接口——Fw::Log与Fw::LogText端口。作为框架遥测、命令、事件三通道中的事件通道这两个端口分别承载二进制序列化事件与可打印文本事件是组件向地面软件或日志系统上报运行时状态的标准途径。读完本文你将掌握这两个端口的参数语义、严重性severity分级体系、配套的缓冲区与字符串类型、相关配置宏以及自动代码生成器如何基于 FPP 定义生成事件上报代码的完整链路。1. 概述两类端口的分工在 F´ 框架中组件通过事件Event向外部汇报运行中发生的情况例如命令执行、告警条件、诊断信息等。事件的传递依赖两个互补的端口定义见 Fw/Log/Log.fppFw::Log端口用于传递 ISF 事件的序列化形式。它携带事件 IDid、时间标签timeTag、严重性severity以及一个包含事件参数序列化结果的缓冲区args。由于采用二进制序列化该端口是事件数据上报地面系统的主通道数据量紧凑、可直接打包进下行遥测包。Fw::LogText端口用于传递 ISF 事件的可打印文本形式。它同样携带 ID、时间标签与严重性但将事件参数格式化为一串人类可读的文本text。该端口面向开发与调试场景正如 Fw/Log/Log.fpp 中的注释所提示Use for development and debugging, turn off for flight用于开发与调试飞行时关闭。两者的存在意味着一个事件在生成时会同时广播到两条路径二进制数据供遥测与存储文本供控制台与调试工具显示。文本日志功能受配置宏FW_ENABLE_TEXT_LOGGING控制可在编译期整体关闭以节省代码空间详见第 5 节。Fw::Log 与 Fw::LogText 端口结构图2. 端口参数详解2.1 Fw::Log 端口参数Fw::Log端口共携带 4 个参数其 FPP 定义位于 Fw/Log/Log.fpp参数说明id事件标识符Event identifier类型为FwEventIdType由自动代码生成器为每个事件分配唯一 IDtimeTag事件发生的系统时间Fw.Time由组件在触发事件时记录severity事件严重性取值为Fw::LogSeverity枚举见第 3 节args事件参数的序列化结果Fw::LogBuffer引用即事件携带的业务数据注意 FPP 定义中id与severity前的$符号表示直接传递不经过序列化而timeTag与args则以ref引用方式传递避免拷贝开销体现嵌入式场景对性能的考量。2.2 Fw::LogText 端口参数参数说明id事件标识符timeTag事件发生的系统时间severity事件严重性Fw::LogSeveritytext事件的可读文本描述类型为Fw::TextLogStringref引用传递2.3 端口在组件接口中的角色在组件的 FPP 接口描述中这两类端口被统一抽象为事件端口event port。以 Fw/Interfaces/EventInterface.fppi 为例 Text event port text event port logTextOut Event port event port logOutlogOut映射到Fw::Log二进制事件logTextOut映射到Fw::LogText文本事件。组件在 FPP 中声明事件后自动代码生成器会为每个事件生成对应的输出端口实例与触发函数。3. 事件严重性分级LogSeverityFw::LogSeverity枚举完整定义于 Fw/Log/Log.fpp共 7 级从致命错误到最细粒度的诊断信息枚举值数值语义FATAL1已遇到使软件无法继续运行的条件致命、不可恢复WARNING_HI2已遇到严重失败但软件可以继续运行WARNING_LO3已遇到失败但软件基本不受影响COMMAND4与命令处理相关的活动发生ACTIVITY_HI5发生重要的标称正常事件ACTIVITY_LO6发生不重要的标称事件属于重要事件的子集DIAGNOSTIC7活动中通常无需查看的详细事件清单用于调试这一分级体系与 Fw/Log/Log.fpp 中定义的枚举完全一致FATAL 1、WARNING_HI 2、WARNING_LO 3、COMMAND 4、ACTIVITY_HI 5、ACTIVITY_LO 6、DIAGNOSTIC 7。二进制端口与文本端口共享同一枚举因此文本日志中打印的严重性名称与二进制事件中的取值严格对应便于地面软件两侧关联比对。4. 配套序列化类型4.1 Fw::LogBuffer —— 序列化事件参数的缓冲区Fw::LogBuffer用于承载事件的序列化参数见 Fw/Log/LogBuffer.hpp。它派生自Fw::SerializeBufferBase内部维护固定大小的字节数组容量由配置宏FW_LOG_BUFFER_MAX_SIZE决定见第 5 节提供getBuffAddr()/getBuffCapacity()访问内部存储以及基于SerializeBufferBase的serialize/deserialize序列化接口构造函数支持由外部数据初始化LogBuffer(const U8 *args, NATIVE_UINT_TYPE size)、默认构造、拷贝构造与赋值运算符其拷贝与赋值均会校验序列化状态并触发FW_ASSERT见 Fw/Log/LogBuffer.cpp。从实现看LogBuffer本质上是事件参数的载荷容器组件侧将各参数按类型依次序列化写入消费侧如ActiveLogger、地面链路再按相同顺序反序列化还原。其序列化类型 ID 为FW_TYPEID_LOG_BUFF。4.2 Fw::TextLogString —— 文本日志字符串Fw::TextLogString是专为文本日志消息定制的定长字符串类型见 Fw/Log/TextLogString.hpp继承自Fw::StringBase字符串容量STRING_SIZE FW_LOG_TEXT_BUFFER_SIZE默认 256 字节见第 5 节序列化类型 ID 为FW_TYPEID_LOG_STR支持从const char*、StringBase及其自身的赋值构造并重载了对应赋值运算符。其容量设计意图在 config/FpConfig.h 中有明确注释Should be large enough for format string and arguments应足够容纳格式化字符串及参数。4.3 Fw::LogStringArg —— 事件中的字符串参数类型当事件的某个参数被声明为字符串时自动代码生成器会使用Fw::LogStringArg作为其类型见 Fw/Log/LogString.hpp容量STRING_SIZE FW_LOG_STRING_MAX_SIZE默认 200 字节与TextLogString共享序列化类型 IDFW_TYPEID_LOG_STR提供完整的构造与赋值重载可直接与const char*互操作。该类型由 Fw/Log/README 明确描述为 Used by the code generator when a string argument type is declared当声明字符串参数类型时由代码生成器使用。值得注意FW_LOG_STRING_MAX_SIZE的注释还提示该常量会截断断言失败事件报告中的文件名属于嵌入式资源约束下的有意取舍。5. 相关配置宏config/FpConfig.h日志端口相关的全部可调参数集中在 config/FpConfig.h均以#ifndef包裹允许在编译前通过命令行或上层配置覆盖宏默认值说明FW_LOG_BUFFER_MAX_SIZEFW_COM_BUFFER_MAX_SIZE - sizeof(FwEventIdType) - sizeof(FwPacketDescriptorType)序列化事件参数缓冲区大小由通信缓冲大小扣除事件 ID 与包描述符后得出FW_LOG_STRING_MAX_SIZE200事件字符串参数LogStringArg的最大字节数会截断断言事件报告中的文件名FW_LOG_TEXT_BUFFER_SIZE256文本日志消息字符串TextLogString的最大字节数需能容纳格式化串与全部参数FW_ENABLE_TEXT_LOGGING1是否启用文本日志端口置 0 可关闭文本输出、节省代码空间其中FW_ENABLE_TEXT_LOGGING与FW_SERIALIZABLE_TO_STRING控制序列化对象是否生成toString()方法存在依赖关系——后者必须开启才能支持文本日志因为文本格式化需要将非基本类型参数转换为字符串。6. 自动代码生成链路事件如何被触发Fw::Log/Fw::LogText端口的实际调用由 FPP 自动代码生成器生成无需手写。以 Autocoders/Python/src/fprime_ac/generators/templates/component/cpp.tmpl 中生成的触发函数为证其典型流程为组件代码调用生成的事件触发函数如log_ACTIVITY_HI_EventName(...)生成代码首先将时间标签Fw::Time与事件参数依次序列化进Fw::LogBuffer若二进制日志端口已连接则调用m_Event_OutputPort[0].invoke(id, timeTag, Fw::LogSeverity::severity, logBuffer)cpp.tmpl当FW_ENABLE_TEXT_LOGGING开启且文本端口已连接时用snprintf按格式化字符串生成文本支持FW_OBJECT_NAMES控制是否前缀对象名存入FW_LOG_TEXT_BUFFER_SIZE大小的局部缓冲构造Fw::TextLogString后调用m_Event_OutputPort[0].invoke(id, timeTag, Fw::LogSeverity::severity, logString)cpp.tmpl。可见文本端口在生成代码中是被\#if FW_ENABLE_TEXT_LOGGING包裹的可选路径二进制端口则是无条件生成的主路径——这与第 1 节文本日志供调试、飞行时可关闭的设计目标完全吻合。7. 事件打包Fw::LogPacket当二进制事件需要发送给地面软件或测试接口时端口参数会被封装进Fw::LogPacket见 Fw/Log/LogPacket.hpp。该类派生自Fw::ComPacket构造函数将包类型置为FW_PACKET_LOG见 Fw/Log/LogPacket.cpp提供setId/setTimeTag/setLogBuffer设置端getId/getTimeTag/getLogBuffer读取端序列化时依次写入包描述符、事件 ID、时间标签与序列化参数数据其中日志缓冲数据采用仅写入内容、不写入长度的方式其注释明确说明为地面软件而设计见 Fw/Log/LogPacket.cpp反序列化时则将剩余全部字节视为日志载荷恢复为LogBuffer。该行为在单元测试 Fw/Log/test/ut/LogTest.cpp 中得到验证测试构造LogPacket写入 ID10、时间标签与序列化后的U32值 12打包进ComBuffer后再解包断言 ID、时间标签与参数值逐一还原测试还覆盖了Fw::LogStringArg的写串→序列化→反序列化→还原往返LogTest.cpp印证了第 4.3 节字符串参数类型的正确性。8. 事件日志的典型消费方Fw::Log/Fw::LogText端口被框架内的日志聚合组件消费形成完整的事件上报链路。在 Svc/ActiveLogger/ActiveLogger.fpp 等实现中ActiveLogger组件同时接入事件与文本事件端口将各组件上报的事件按严重性分级处理后转发给事件存储、文本日志器如 Svc/ActiveTextLogger、地面遥测通道等下游。这一组件发事件 → 日志端口 → ActiveLogger 聚合分发的架构正是第 2 节端口参数与第 7 节LogPacket打包能力的组合应用。9. 变更记录该端口与配套类型的演进记录如下源自 Fw/Log/docs/sdd.md日期说明2015-09-03Fw::LogBuffer初始版本2015-09-16Fw::LogStringArg初始版本供日志自动代码生成器在声明字符串参数时使用参考文件索引端口定义Fw/Log/Log.fpp设计文档Fw/Log/docs/sdd.md缓冲区实现Fw/Log/LogBuffer.hpp、Fw/Log/LogBuffer.cpp字符串类型Fw/Log/LogString.hpp、Fw/Log/TextLogString.hpp打包类型Fw/Log/LogPacket.hpp、Fw/Log/LogPacket.cpp配置宏config/FpConfig.h单元测试Fw/Log/test/ut/LogTest.cpp代码生成模板Autocoders/Python/src/fprime_ac/generators/templates/component/cpp.tmpl组件接口约定Fw/Interfaces/EventInterface.fppi赞分享嵌入式系统编程【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址https://gitcode.com/gh_mirrors/fp/fprime点击查看免费下载相关推荐F´ 事件日志端口深度解析Fw::Log 与 Fw::LogText 的设计与使用指南F´ 事件日志端口深度解析Fw::Log 与 Fw::LogText 的设计与使用指南 事件Event是 F´F Prime飞行软件与嵌入式系统中面向嵌入式系统编程F´ 命令体系详解Fw::Cmd / Fw::CmdResponse / Fw::CmdReg 端口设计、序列化与配置指南F´ 命令体系详解Fw::Cmd / Fw::CmdResponse / Fw::CmdReg 端口设计、序列化与配置指南 本篇技术指南以 F´F Prim嵌入式系统编程F´F Prime框架核心功能解析Fw 基础架构、端口与序列化体系完全指南F´F Prime框架核心功能解析Fw 基础架构、端口与序列化体系完全指南 F´F PrimeFlight Software and Embedded嵌入式系统编程上一篇5分钟上手Intern-S2-MobiusLMDeploy部署与MTP加速实战教程下一篇PGlite 如何安装并在浏览器与 Node.js 中创建第一个数据库实例并执行查询创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考