Postform

Postform (缩写为"延迟格式化") 是一个用于32位微控制器的C++延迟格式化日志系统。本项目受到 defmt Rust crate from Knurling-rs 的启发/基于此。它们做得非常出色，这激励我创建了一个遵循类似操作原则的C++替代品，仍然利用Rust来为日志记录器的宿主端实现提供支持。

目录

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

关于项目

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

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

• 格式化字符串。
• 为格式化字符串所需的所有参数。

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

总的来说，延迟格式化提供了一些 好处

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

正如您所预料的，还有一些缺点

• 需要在主机端进行一些工具配置，以便读取和解释日志。
• 日志的元数据是分开存储的，FW端和主机端都需要保持同步。

回到顶部

项目状态

Postform 目前正处于积极开发中。所有贡献都备受赞赏并受到鼓励。请随时提交有关改进建议、遇到的问题等问题的issue。如果您想做出贡献，请查看贡献指南。

目前默认构建目标是针对 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 上。

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

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命令，只需在命令调用中将docker插入到xtask之后。例如，要在Docker中运行测试，请使用

cargo xtask docker test

回到顶部

发布流程

版本管理

本项目使用语义版本控制。发布版本将相应地标记。版本低于1.0.0的版本可以在任何时候进行破坏性API/ABI更改。

回到顶部

如何获取帮助

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

回到顶部

贡献

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

回到顶部

许可证

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

回到顶部

作者

• Javier Alvarez - 初始工作 - AllThingsEmbedded

还可以查看参与此项目的贡献者列表。

回到顶部

致谢

我衷心感谢knurling-rs的好人们，他们的作品启发了本项目。毕竟，这个项目是对defmt的C++代码使用的一种替代实现。

回到顶部