riot-sys

RIOT 系统调用的绑定

此包包含动态生成的 Rust FFI 绑定到 RIOT 操作系统。

这些绑定本质上是不可安全的；建议在大多数应用程序中使用 riot-wrappers 包中它们的安全抽象。

对于新手来说，请参阅 RIOT 使用 Rust 的文档。这还包含安装说明/依赖关系。

RIOT 集成

此包中存在的函数和结构体，有时还有它们的详细信息，本质上是依赖于将与它一起使用的 RIOT 配置。例如，RIOT 的 thread_t 仅在构建时设置 DEVHELP 时才有成员 name，并且其 flags 成员仅在 thread_flags 模块被使用时才存在。

所有相关信息均通过传递编译器和CFLAGS传递给riot-sys，包括实际使用的RIOT头文件位置和影响ABI的标志。这可以通过两种方式实现：通过通过RIOT_COMPILE_COMMANDS环境变量传递“编译命令”文件的路径（同时包含RIOT_USEMODULES，因为CFLAGS中的这部分在编译命令中缺失），或者通过传递C编译器作为RIOT_CC和CFLAGS（包括RIOT构建系统中的CFLAGS_WITH_MACROS和INCLUDES部分）来传递。当从RIOT的构建系统中调用时，必须注意清除CC和CFLAGS，因为这些将被Cargo（Rust的构建系统）解释为主机编译器和标志。标志将由libclang工具解释；必须传递适合clang而不是GCC的标志。

这些步骤在RIOT的构建系统中已自动化。

RIOT_CC和RIOT_CFLAGS通过Cargo（作为DEP_RIOT_SYS_CC等）提供给依赖的crates；请参阅riot-wrappers的build.sh以获取示例。类似地，根据RIOT中是否存在某些宏定义或功能，提供自定义标记；下面部分将详细介绍。

扩展

目前，只处理所有RIOT头文件的一个子集；所有相关头文件都包含在这个crate的riot-headers.h头文件中。如果您需要访问更多的RIOT API，可以在此处添加更多的包含。

版本控制

riot-sys使用SemVer进行版本控制，并且在0.x阶段努力不进行破坏性更改。请注意，因为它传递RIOT内部信息，所以只有当在相同 RIOT上构建时，SemVer保证才成立。一旦底层C代码更改，所有保证都不成立。使用riot-rs的用户可以检查设置links = "riot-sys"的crates可用的DEP_RIOT_SYS_...变量，以影响这些crates使用的符号。要检查的典型变量是DEP_RIOT_SYS_BINDGEN_OUTPUT_FILE（以确定是否导入了符号，例如，当RIOT重命名某些内容时）和DEP_RIOT_SYS_CFLAGS，其中包含启用的模块。

标记

已弃用，请参阅下面.

下游crates的一些决策需要取决于RIOT中是否存在某些功能。对于许多事情，最好在模块级别进行检查，但对于一些小项目没有标记功能的模块，并且通过数字检查版本不够细致，所以最简单的方法是在bindgen输出中检查具体的字符串。

此crate的build.rs包含一个标记条件列表。这些导致发出MARKER_foo=1项，这些项可以通过显式links = "riot-sys"的crates作为DEP_RIOT_SYS_MARKER_foo=1使用。它们是稳定的，因为它们只在破坏性的riot-sys版本中消失；下游用户可能更早停止使用它们，因为它们最终停止支持旧的RIOT版本。

例如，在PR #17957中，一个特定处理函数的参数发生了根本性的变化；没有任何数量的.into()允许编写合理的抽象。引入了标记coap_request_ctx_t，并且自动存在于所有合并了该特定拉取请求的RIOT版本中。在riot-wrappers中的代码使用条件，如#[cfg(marker_coap_request_ctx_t)] 来决定是否使用旧或新的约定。

这些标记目前是针对bindgen的输出进行检查的，但可以查询riot-sys可以访问的任何属性。标记是在RIOT中发生了某些变化的情况下定义的；测试它们的方式可能会改变。（特别是，当riot-sys停止支持较旧的RIOT版本时，它只需始终发出该标记）。

基于此构建的crates应尽量不根据这些修改自己的API，因为这会给它们增加额外的（难以跟踪）维度。如果可以，它们应提供统一的视图并优雅地降级。（例如，riot-wrappers在其枚举中有phydat_unit_t的单元T，但在还没有T类型的RIOT版本中将它转换为通用未指定单位 – 至少在它支持2022.01期间）。

弃用说明/继任者：截至2023-02，将不会添加新的标记，因为在此处实现此机制已被证明是不切实际的：更改需要在riot-sys中首先进行，然后才能与riot-wrappers一起使用（并进行测试）。相反，导出了BINDGEN_OUTPUT_FILE（可使用DEP_RIOT_SYS_BINDGEN_OUTPUT_FILE），它指向bindgen生成的Rust文件。下游的crates可以检查该文件，可能使用与riot-sys相同的基于字符串的方法，但没有任何跨crates的依赖关系。

访问BINDGEN_OUTPUT_FILE的crates应采取与上面推荐的使用标记相同的谨慎态度。

RIOT的类型和常量以两种形式翻译：通过bindgen（链接在一起），以及通过C2Rust（转译，内联）。这是因为它们都无法表达所有有用的RIOT API集合。

所有bindgen类型都在主模块中重新导出，并通过该模块完全公开。C2Rust类型主要位于[inline]模块中，必要时或方便时在根模块中使用一些pub。

许可协议

此crates受与RIOT操作系统相同的许可协议约束，即LGPL-2.1。

由Christian Amsüss [email protected]维护，作为etonomy项目的一部分，请参阅https://etonomy.org/，以及RIOT团队。