bitinfo

bitinfo 是一个工具，通过解码它们的值来使处理寄存器更容易。

是什么？

让我们从一个工具的工作示例开始。假设你正在调试一个新传感器，并想知道一个寄存器是否包含预期的值。你读取它，得到一个难以理解的 0x4E0。这可以通过手工解码，但这就是 bitinfo 发挥作用的地方。这难道不比手工解码更好吗？

borgel$ bitinfo STPM.DSP_CR3.0x4E0
 STPM.DSP_CR3 0x4E0 -> |                                           |
-----------------------+-------------------------------------------+-----------------------------------------------------------------------
 SAG_TIME_THR          | 1248                                      | The sag time
 ZCR_SEL               | V1 / 7.8125 kHz                           | Selection bit for ZCR/CLK pin, (output depends on ZCR/CLK enable bit)
 ZCR_EN                | CLK                                       |
 TMP_TOL               | 12.5%                                     | Tamper tolerance
 TMP_EN                | tamper disable                            | Tamper detect enable
 S/W Reset             | 0x0                                       | Software reset
 S/W Latch 1           | 0x0                                       |
 S/W Latch 2           | 0x0                                       |
 S/W Auto Latch        | Disabled                                  | Auto latch
 LED_OFF1              | LED output on                             | LED pin output disable
 LED_OFF2              | LED output on                             | LED pin output disable
 EN_CUM                | Cumulative is the sum of channel energies | Cumulative energy calculaton
 REF_FRQ               | 50 Hz                                     | Reference line frequency

bitinfo 允许开发者指定配置文件，描述设备寄存器的层次结构（在本例中为 STPM.DSP_CR3），然后根据这些描述解码任意数值。

获取它

目前可在所有具有 Rust 工具链的平台上获取，请访问 http://crates.io。只需

cargo install --force bitinfo
# the `--force` forces `cargo` to install the latest version if you have an earlier one

使用它

使用 bitinfo 需要两个方面的知识；如何调用它以及如何配置寄存器描述。

调用

安装后，bitinfo 是一个单独的二进制文件，可以从 shell 中调用。 bitinfo 将帮助您描述一个数字，即使它不知道如何将其解码为特定的寄存器值。

borgel$ bitinfo 0xa5
165 -> 165 0xA5 0b10100101
borgel$ bitinfo 0x0F0
 240 | 240 0xF0 0b11110000

任何常见的数值格式都可以正常工作（0x 十六进制，0b 二进制和 0 十进制）。

它还可以描述第 i 位设置的位。

borgel$ bitinfo --bits 0xa5
 165 | 165 0xA5 0b10100101
-----+---------------------
     | 0th set
     | 2th set
     | 5th set
     | 7th set

但是，当描述具有描述性配置文件的价值时，该工具更有用。如果在包含 bitinfo 配置文件的目录树中工作，可以指定特定的设备进行查询。

borgel$ bitinfo R2-Device.Register1.0x1A
 R2-Device.Register1 0x1A -> |
-----------------------------+--------------------
 A nibble of decimals        | 10
 A bamboozler to control     | Bamboozler enabled

为了解码特定的寄存器，bitinfo 必须

• 在其搜索路径中有适当的配置文件可见
• 使用对要解码的寄存器的命名引用进行调用，该寄存器必须在适当命名的可见配置文件中存在

请注意

• 分隔符可以是 .:/ 的任何组合
• 设备和寄存器名称区分大小写，必须与配置文件完全匹配

配置

bitinfo 使用配置文件来描述它可以解码的寄存器和字段。要查看一个高度注释的示例配置，该配置描述了所有允许的字段，请检查示例目录中的此样本。

配置文件必须按照以下模式命名 .bitinfo.<可选名称>.yaml 才能被工具检测到。可选名称可用于组织目的，以便在同一个地方清楚地描述多个配置文件，但可以省略。它目前在解码过程中不被使用。

bitinfo 通过两种方式搜索配置文件：检查包括当前目录在内的每个目录，以及通过在命令行中指定目录。每次执行 bitinfo 都会搜索这些路径并加载所有匹配名称模式的配置文件。它将所有配置一起搜索以解决用户查询，因此大型项目可以将寄存器描述分散到多个文件中。

预期用例是项目在项目根目录中包含配置（以便它们在项目下方随处可见）或在特定模块的源附近包含特定于该模块的配置。

示例

一个非常简单的配置可能看起来像这样

R1-Device:
   description: This is the top level of organization. Think part number like LIS2DH or STM32F104
   preferred_format: hex
   fields:
      BField1:
         start: 0
         width: 1
         description: I'm not sure what a bamboozler is, are you?
         # sometimes it can be handy to describe what the flag states mean
         patterns:
            0b0: Bamboozler disabled
            0b1: Bamboozler enabled

对此设备的查询将看起来像这样

# bamboozler disabled
borgel$ bitinfo --configs ../examples/ R1-Device.0
 R1-Device 0x1A -> |                     |
-------------------+---------------------+---------------------------------------------
 BField1           | Bamboozler disabled | I'm not sure what a bamboozler is, are you?

# and with the bamboozler enabled
borgel$ bitinfo --configs ../examples/ R1-Device.1
 R1-Device 0x0A -> |                    |
-------------------+--------------------+---------------------------------------------
 BField1           | Bamboozler enabled | I'm not sure what a bamboozler is, are you?

这有点简化。最常用的配置至少包含一个额外的组织层，看起来更像是这样

R2-Device:
   description: This is the top level of organization. Often an entire device (CPU, complex sensor, etc)
   registers:
      Register1:
         description: A second level of organization. Think of a peripheral or register in a CPU or sensor
         fields:
            A decimal slice:
               start: 0
               width: 4
               preferred_format: dec
            BField2:
               start: 4
               width: 1
               patterns:
                  0b0: Bamboozler disabled
                  0b1: Bamboozler enabled

请注意，这里的 寄存器 可以嵌套到任意深度。

对上述设备的查询命令将如下所示

borgel$ bitinfo --configs ../examples/ R2-Device.Register1.0x1A
 R2-Device.Register1 0x1A -> |
-----------------------------+--------------------
 A nibble of decimals        | 10
 A bamboozler to control     | Bamboozler enabled

请注意，上述示例是在相对于存储库中的源目录的情况下运行的，这就是为什么将示例目录作为显式搜索路径传递的原因。

请参阅示例目录以获取有关可用字段及其用法的详细说明。

已知限制

• 尽管没有理由它需要限制为32位寄存器，但在某些地方假定是这样
• 仅通过完全工作的Rust安装（但任何平台！）
• 输出格式选项有限（具体来说，没有选项）
• 可能还有更多。欢迎PR！