Rust 的模块化位字段

持续集成	文档	Crates.io	LoC

• no_std：支持无需 std 库的嵌入式开发。
• 此crate使用并生成100%安全的 Rust 代码。

描述

允许将位字段结构和枚举作为位字段说明符，其工作方式与 C 和 C++ 位字段非常相似。

优点

• 安全性：宏拥抱枚举和结构在编译时检查有效结构。
• 速度：生成的代码与手写代码一样快。（请参见下面的基准测试。）
• 模块化：枚举可以在位字段结构内模块化使用。

归属

实现了 David Tolnay 在其 过程宏研讨会 中引入和指定的 #[bitfield] 宏。

感谢 David Tolnay 为此crate中实现的宏设计了规范。

使用

使用 #[bitfield] 属性注释 Rust 结构，以便将其转换为位字段。可以使用 B1、B2、...、B128 预览类型作为原始类型来声明每个字段的位数。

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: B1,
    status: B2,
}

这会生成一个 new 构造函数以及各种获取器和设置器，允许以安全的方式与位字段交互

示例：构造函数

let data = PackedData::new()
    .with_header(1)
    .with_body(2)
    .with_is_alive(0)
    .with_status(3);
assert_eq!(data.header(), 1);
assert_eq!(data.body(), 2);
assert_eq!(data.is_alive(), 0);
assert_eq!(data.status(), 3);

示例：原始类型

任何实现 Specifier 特质的类型都可以用作位字段字段。除了已经提到的 B1、.. B128 之外，还可以使用预览中的 bool、u8、u16、u32、u64 或 u128 原始类型。

我们可以利用这个知识，将我们的 is_alive 编码为 bool 类型，而不是 B1

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: bool,
    status: B2,
}

let mut data = PackedData::new()
    .with_is_alive(true);
assert!(data.is_alive());
data.set_is_alive(false);
assert!(!data.is_alive());

示例：枚举说明符

对于 enum 类型，可以非常容易地推导出 Specifier 特性，使其也可用作位域类型的字段

#[derive(BitfieldSpecifier)]
pub enum Status {
    Red, Green, Yellow, None,
}

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: bool,
    status: Status,
}

示例：额外的安全保护

为了确保我们的 Status 枚举正好需要 2 位，我们可以为其字段添加 #[bits = 2]

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: bool,
    #[bits = 2]
    status: Status,
}

设置和获取我们的新 status 字段自然如下

let mut data = PackedData::new()
    .with_status(Status::Green);
assert_eq!(data.status(), Status::Green);
data.set_status(Status::Red);
assert_eq!(data.status(), Status::Red);

示例：递归位域

可以将 #[bitfield] 结构体用作 #[bitfield] 结构体的字段。这在存在多个位域具有一些公共字段时非常有用，这是通过向具有 #[derive(BitfieldSpecifier)] 注解的结构体的属性中添加 #[bitfield] 来实现的

#[bitfield]
#[derive(BitfieldSpecifier)]
pub struct Header {
    is_compact: bool,
    is_secure: bool,
    pre_status: Status,
}

#[bitfield]
pub struct PackedData {
    header: Header,
    body: B9,
    is_alive: bool,
    status: Status,
}

通过在 Header 结构体上使用 #[bitfield] 宏和 Status 枚举上的 #[bits: int] 属性，我们可以对生成的实体的位宽有额外的编译时保证

#[derive(BitfieldSpecifier)]
#[bits = 2]
pub enum Status {
    Red, Green, Yellow
}

#[bitfield(bits = 4)]
#[derive(BitfieldSpecifier)]
pub struct Header {
    is_compact: bool,
    is_secure: bool,
    #[bits = 2]
    pre_status: Status,
}

#[bitfield(bits = 16)]
pub struct PackedData {
    #[bits = 4]
    header: Header,
    body: B9,
    is_alive: bool,
    #[bits = 2]
    status: Status,
}

示例：高级枚举说明符

对于我们的 Status 枚举，实际上我们只需要 3 个状态变体：Green、Yellow 和 Red。我们引入了 None 状态变体，因为默认情况下，Specifier 枚举需要具有的变体数量是 2 的幂。我们可以通过在顶部指定 #[bits = 2] 来解决这个问题，从而去除我们的占位符 None 变体，同时保持它需要 2 位的不变性

# use modular_bitfield::prelude::*;

#[derive(BitfieldSpecifier)]
#[bits = 2]
pub enum Status {
    Red, Green, Yellow,
}

然而，现在拥有这样的枚举可能导致位域包含无效的位模式。我们可以安全地使用受保护的getter来访问这些字段。为了演示，我们将使用生成的 from_bytes 构造函数，通过它可以轻松构建可能包含无效位模式的位域

let mut data = PackedData::from_bytes([0b0000_0000, 0b1100_0000]);
//           The 2 status field bits are invalid -----^^
//           as Red = 0x00, Green = 0x01 and Yellow = 0x10
assert_eq!(data.status_or_err(), Err(InvalidBitPattern { invalid_bytes: 0b11 }));
data.set_status(Status::Green);
assert_eq!(data.status_or_err(), Ok(Status::Green));

基准测试

以下是一些基准测试，比较了手写代码和宏生成的代码在某些示例获取器和设置器上的性能，这些获取器和设置器涵盖了相当多的使用场景。

我们可以得出结论，宏生成的代码与手写代码一样快。如果您看到改进任一方面的方法，请提交一个PR。

• cargo bench 运行基准测试
• cargo test 运行基准测试

点击此处查看所有基准测试结果。

总结

模块化位域crate（modular_bitfield）生成的位域...

• 与手写代码一样高效。
• 与替代的 位域 crate 相当高效或更高效。

展示：生成与手写

我们测试了以下 #[位域] struct

#[bitfield]
pub struct Generated {
    pub a: B9,  // Spans 2 bytes.
    pub b: B6,  // Within 2nd byte.
    pub c: B13, // Spans 3 bytes.
    pub d: B1,  // Within 4rd byte.
    pub e: B3,  // Within 4rd byte.
    pub f: B32, // Spans rest 4 bytes.
}

注意： 所有基准测试时间结果均为10次运行的汇总。

获取器性能

get_a/generated     time:   [3.0990 ns 3.1119 ns 3.1263 ns]
get_a/handwritten   time:   [3.1072 ns 3.1189 ns 3.1318 ns]

get_b/generated     time:   [3.0859 ns 3.0993 ns 3.1140 ns]
get_b/handwritten   time:   [3.1062 ns 3.1154 ns 3.1244 ns]

get_c/generated     time:   [3.0892 ns 3.1140 ns 3.1491 ns]
get_c/handwritten   time:   [3.1031 ns 3.1144 ns 3.1266 ns]

get_d/generated     time:   [3.0937 ns 3.1055 ns 3.1182 ns]
get_d/handwritten   time:   [3.1109 ns 3.1258 ns 3.1422 ns]

get_e/generated     time:   [3.1009 ns 3.1139 ns 3.1293 ns]
get_e/handwritten   time:   [3.1217 ns 3.1366 ns 3.1534 ns]

get_f/generated     time:   [3.1064 ns 3.1164 ns 3.1269 ns]
get_f/handwritten   time:   [3.1067 ns 3.1221 ns 3.1404 ns]

设置器性能

set_a/generated     time:   [15.784 ns 15.855 ns 15.932 ns]
set_a/handwritten   time:   [15.841 ns 15.907 ns 15.980 ns]

set_b/generated     time:   [20.496 ns 20.567 ns 20.643 ns]
set_b/handwritten   time:   [20.319 ns 20.384 ns 20.454 ns]

set_c/generated     time:   [19.155 ns 19.362 ns 19.592 ns]
set_c/handwritten   time:   [19.265 ns 19.383 ns 19.523 ns]

set_d/generated     time:   [12.325 ns 12.376 ns 12.429 ns]
set_d/handwritten   time:   [12.416 ns 12.472 ns 12.541 ns]

set_e/generated     time:   [20.460 ns 20.528 ns 20.601 ns]
set_e/handwritten   time:   [20.473 ns 20.534 ns 20.601 ns]

set_f/generated     time:   [6.1466 ns 6.1769 ns 6.2127 ns]
set_f/handwritten   time:   [6.1467 ns 6.1962 ns 6.2670 ns]

许可证

根据您的选择，在Apache License，版本2.0或MIT许可证下许可。

除非您明确声明，否则根据Apache-2.0许可证定义，您有意提交的任何贡献，都应如上所述双重许可，而不附加任何额外条款或条件。