Postform

Postform (简称"延迟格式化") 是一个适用于32位微控制器的C++延迟格式化日志系统。本项目受到来自 Knurling-rs 的defmt rust crate的启发/基于。他们做得非常出色，这激励我创建了一个遵循类似操作原则的C++替代方案，同时仍然利用Rust来实现这个日志记录器的宿主端实现。

目录

• 关于本项目
• 项目状态
• 入门
  • 依赖项
  • 获取源代码
  • 构建
  • 用法
• 发布流程
  • 版本管理
• 如何获取帮助
• 贡献
• 许可协议
• 作者
• 致谢

关于本项目

在嵌入式设备中，字符串格式化可能相当昂贵。日志是开发者用于调试和分析其设备性能的主要工具之一。为了提供适用于嵌入式设备的有效日志机制，Postform 不在设备上执行格式化。相反，它被延迟并在宿主计算机上执行。

Postform将原始数据（格式化字符串+所有参数）序列化，并通过给定的传输发送到宿主设备。宿主负责反序列化这些数据，并执行日志格式化并将其显示给用户。

• 格式化字符串。
• 格式化字符串所需的全部参数。

另一方面，由于这些在编译时已知，所以存储和传输格式没有意义。一般来说，简单地存储一个指向格式化字符串的标识符，并让宿主找到对应ID的字符串会更有效。这减少了二进制文件的大小，并优化了运行时性能，因为通常传输ID比传输大型字符串要快。

总的来说，延迟格式化提供了一些 优点

• 较小的内存占用，因为格式化字符串不存储在二进制文件中。
• 更快的日志记录，因为只需传输原始二进制数据，这通常比实际格式化字符串要小。
• 二进制文件中没有字符串使得逆向工程更困难。

而且，正如你所预期的，一些 缺点

• 主机端需要一些工具来读取和解析日志。
• 日志元数据存储在单独的位置，它们需要在防火墙端和主机端保持同步。

回到顶部

项目状态

在此阶段，《Postform》正处于积极开发中。所有贡献都备受赞赏并鼓励。请随意提交有关改进建议、遇到的问题等问题的报告。如果您想贡献，请查看贡献指南。

目前默认构建目标是针对 Cortex-M 处理器，然而《Postform》旨在成为一个针对32位微控制器的平台无关日志库，我们尽可能追求代码的可移植性。实际上，它也用于主机进行测试，以展示代码的实际可移植性。

目前API仍然可能变动，未来可能会有所变化。《Postform》使用语义化版本控制进行版本发布，因此当主版本号发生变化时，您将知道何时添加了破坏性的API功能。然而，在我们达到1.0.0之前，即使次要版本号增加，我们仍然可能做出破坏性的API/ABI更改。

回到顶部

入门

组件

《Postform》由以下组件组成

• libpostform，这是一个C++库，可以将其链接到嵌入式代码中。它处理消息的格式化和序列化，并提供了一些日志数据的示例传输层。
• postform_decoder，这是一个Rust库，可以解析和格式化日志消息。一些其他Rust二进制文件使用此库，以提供根据传输和格式方便使用的日志解析。
• postform_rtt，这是一个Rust二进制文件，通过调试连接连接到目标，并通过RTT传输在运行时读取日志，将它们打印到控制台。
• postform_serial，这是一个Rust二进制文件，使用TTY设备而不是RTT作为传输，并在控制台显示日志消息。
• postform_persist，这是一个Rust二进制文件，从文件中读取由libpostform生成的日志数据，并将消息打印到控制台。

依赖项

libpostform可以与clang和GCC一起构建和使用。目前支持的构建环境为Ubuntu 20.04，默认工具链配置使用clang作为编译器和来自GCC ARM嵌入式工具链的newlib库。libpostform与clang-12进行了测试，但已知它与clang-10也能正常工作。

在此处获取最新的GNU ARM嵌入式工具链 这里。请确保将bin文件夹添加到您的路径中。构建系统需要CMake、Ninja和Cargo，并使用Cargo xtasks来自动化和脚本化构建过程。

要使用Ubuntu apt仓库安装依赖项，请运行

sudo apt install cmake ninja-build clang

此外，要获取cargo和rustc，您可以使用rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

主机端的全部Rust代码依赖都已在Cargo.toml文件中标注。一些依赖需要一些共享库，您可以使用以下命令安装：

sudo apt install -y libusb-1.0-0-dev libftdi1-dev libudev-dev

值得一提的是，可以通过在已包含所有这些依赖的Docker容器中运行构建来避免安装这些依赖。有关如何在Docker中运行构建的更多详细信息，请参阅在Docker容器中运行部分。

获取源代码

本项目托管在GitHub上：GitHub.

您可以通过克隆此仓库来获取仓库：

git clone https://github.com/Javier-varez/Postform postform

构建

如前所述，cargo xtasks用于自动化构建和测试过程。以下命令可用：

• cargo xtask build-firmware cortex_m3 - 使用libpostform为Cortex-M3 MCU构建示例应用。将在fw_build/m3/app/postform_format下可用。
• cargo xtask build-firmware cortex_m0 - 使用libpostform为Cortex-M0 MCU构建示例应用。将在fw_build/m0/app/postform_format下可用。
• cargo xtask test - 运行所有Postform测试。
• cargo xtask build --release - 构建postform_rtt、postform_persist和postform_serial等所有主机二进制文件。
• cargo xtask clean - 清除所有目标构建文件夹。
• cargo xtask run-example-app - 在STM32F103C8微控制器上运行示例应用。应通过ST-Link或兼容的SWD调试器连接。

有关所有可用命令的更多信息，请运行cargo xtask --help。

用法

为了运行示例应用，请运行以下命令：

cargo xtask run-example-app

这将为cortex-m3构建示例固件应用，然后立即触发postform_rtt（如有需要则构建）。然后postform_rtt将通过RTT（使用SWD连接）连接到目标MCU，并从FW ELF文件加载所有调试信息。示例应用是为通过与probe-rs兼容的调试器连接的STM32F103C8微控制器构建的，例如ST-Link或J-Link。

$ cargo xtask run-example-app
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `xtask/target/debug/xtask run-example-app`
$ cmake -G Ninja -DPOSTFORM_BUILD_EXAMPLES=true -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/armv7m.cmake -DPOSTFORM_BUILD_TARGET_APP=true
-- The C compiler identification is Clang 12.0.1
-- The CXX compiler identification is Clang 12.0.1
-- Check for working C compiler: /usr/bin/clang
-- Check for working C compiler: /usr/bin/clang -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/clang++
-- Check for working CXX compiler: /usr/bin/clang++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /home/javier/Documents/code/Postform/fw_build/m3
$ cmake --build .
[14/14] Linking CXX executable app/postform_format
$ cargo run --bin=postform_rtt -- --chip STM32F103C8 fw_build/m3/app/postform_format
    Finished dev [unoptimized + debuginfo] target(s) in 0.05s
     Running `target/debug/postform_rtt --chip STM32F103C8 fw_build/m3/app/postform_format`
0.000001     Debug      : Iteration number: 0
└── File: ../../app/src/main.cpp, Line number: 86
0.000355     Debug      : Is this nice or what?!
└── File: ../../app/src/main.cpp, Line number: 88
0.000374     Info       : I am 28 years old...
└── File: ../../app/src/main.cpp, Line number: 89
0.000388     Warning    : Third string! With multiple args and more numbers: -1124
└── File: ../../app/src/main.cpp, Line number: 91
0.000412     Error      : Oh boy, error 234556 just happened
└── File: ../../app/src/main.cpp, Line number: 92
0.000429     Error      : This is my char array: 123
└── File: ../../app/src/main.cpp, Line number: 94
0.000447     Error      : different unsigned sizes: 123, 43212, 123123123, 123123123, 123123123
└── File: ../../app/src/main.cpp, Line number: 100
0.000484     Error      : different signed sizes: -123, -13212, -123123123, -123123123, -123123123
└── File: ../../app/src/main.cpp, Line number: 104
0.000528     Error      : different octal sizes: 123, 123, 123123, 123123123, 123123123
└── File: ../../app/src/main.cpp, Line number: 110
0.000561     Error      : different hex sizes: f3, 1321, 12341235, 12341234, 1234567812345678
└── File: ../../app/src/main.cpp, Line number: 116
0.000607     Error      : Pointer 0x12341234
└── File: ../../app/src/main.cpp, Line number: 117
0.000625     Debug      : Now if I wanted to print a really long text I can use %k: Lorem ipsum dolor sit amet, consectetur adipiscing
 eleifend quis convallis ut, venenatis quis mauris. Morbi tempor, ex a lobortis luctus, sem nunc laoreet dolor, pellentesque gravida m
pibus purus sed sagittis lobortis. Sed quis porttitor nulla. Nulla in ante ac arcu semper efficitur ut at erat. Fusce porttitor suscip
Morbi tristique tristique nulla, at posuere ex sagittis at. Aliquam est quam, porta nec erat ac, convallis tempus augue. Nam eu quam v
 Cras molestie eros odio, vitae ullamcorper ante vestibulum non. Vestibulum facilisis diam vel condimentum gravida. Donec in odio sit
tis laoreet. Nullam dignissim vel ex vel molestie. Vestibulum id eleifend metus. Curabitur malesuada condimentum augue ut molestie. Vi
└── File: ../../app/src/main.cpp, Line number: 149
1.000002     Debug      : Iteration number: 1
└── File: ../../app/src/main.cpp, Line number: 86
1.000454     Debug      : Is this nice or what?!
└── File: ../../app/src/main.cpp, Line number: 88

在Docker容器中运行

可以在已安装所有依赖项的Docker容器中运行任何xtask命令。如果您不想通过安装上一节中列出的所有依赖项的流程，只是想快速开始，这会很有用。

要在一个Docker容器中运行xtask命令，只需在命令调用中的xtask之后插入docker。例如，要在Docker中运行测试，请使用：

cargo xtask docker test

回到顶部

发布流程

版本管理

本项目采用语义版本控制。发布版本相应地进行标记。版本低于1.0.0的API/ABI可能在任何时候发生重大变化。

回到顶部

如何获取帮助

如果您在设置和使用Postform时需要任何帮助，请随时联系并提交一个issue。

回到顶部

贡献

欢迎并感谢公众的贡献。请查看CONTRIBUTING.md以了解开发过程和贡献类型。

回到顶部

许可协议

本项目采用MIT许可证 - 详细信息请参阅LICENSE.md文件。

回到顶部

作者

• Javier Alvarez - 初始工作 - AllThingsEmbedded

请参阅参与此项目的贡献者列表。

回到顶部

致谢

我要真诚地感谢knurling-rs的团队，他们的工作启发了本项目。毕竟，本项目是C++代码使用中defmt的替代实现defmt。

回到顶部