Postform

Postform (简称 "Postponed formatting") 是一个针对 32 位微控制器的 C++ 延迟格式化日志系统。本项目受 defmt rust crate（来自 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 Embedded toolchain 的 newlib 库。 libpostform 使用 clang-12 进行测试，但已知它也可以与 clang-10 一起使用。

获取最新的 GNU ARM Embedded toolchain 这里。请确保将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上：https://github.com/Javier-varez/Postform。

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

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团队，他们的工作启发了本项目。毕竟，这是一个针对C++代码使用的defmt的替代实现。

返回顶部