Postform

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

目录

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

关于项目

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

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

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

另一方面，由于这些在编译时已知，因此存储和传输格式没有意义。一般而言，仅存储一个格式字符串的标识符并让宿主查找相应的字符串对于给定的ID更为高效。这减少了二进制文件的大小并优化了运行时性能，因为通常传输ID比传输大型字符串更快。

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

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

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

• 主机端需要一些工具来读取和解析日志。
• 日志元数据被单独存储，FW端和主机端都需要保持同步。

返回顶部

项目状态

Postform目前正处于积极开发中。所有贡献都非常受欢迎并受到鼓励。请随意提交改进建议、遇到的bug等问题。如果您想贡献，请查看贡献指南。

目前默认构建目标是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库。已使用clang-12测试libpostform，但已知它也可以与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命令，只需在命令调用中的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的替代实现。

返回顶部