4. 寄存器配置工具链：设备树(DTS)解析、寄存器描述文件(JSON/YAML)格式与解析库

在多芯片网关的 HAL 驱动适配中，寄存器配置的标准化与工具链建设是保障驱动可移植性的核心环节。本章聚焦于三种主流的寄存器配置描述方式：设备树（Device Tree Source, DTS）、JSON 格式与 YAML 格式，并深入解析对应的解析库与工程化实践。

4.1 设备树（DTS）解析：从硬件描述到驱动实例

设备树是一种用于描述硬件配置的树形数据结构，广泛应用于 ARM、RISC-V 等嵌入式平台。DTS 文件通过节点（node）和属性（property）描述 SoC 内部寄存器映射、中断号、时钟频率等信息。

4.1.1 DTS 文件结构与寄存器节点

一个典型的 DTS 寄存器节点包含 reg 属性，用于定义寄存器基地址和地址范围。以下示例展示了一个 SPI 控制器的 DTS 节点：

/dts-v1/;

/ {
    soc {
        spi0: spi@ff010000 {
            compatible = "vendor,spi-v1";
            reg = <0x0 0xff010000 0x0 0x1000>;
            interrupts = <0 32 4>;
            clocks = <&clk_spi>;
            #address-cells = <1>;
            #size-cells = <0>;
            status = "okay";
        };
    };
};

4.1.2 DTS 解析流程与 libfdt 库

在 HAL 驱动中，解析 DTS 通常依赖 libfdt（Flat Device Tree）库。该库提供了一组 C 语言 API，用于遍历节点、读取属性值。解析流程如下：

1. 加载 DTB：将编译后的 DTB 二进制数据加载到内存缓冲区。
2. 初始化 FDT：调用 fdt_check_header() 校验魔数，fdt_totalsize() 获取总大小。
3. 查找节点：使用 fdt_path_offset() 或 fdt_node_offset_by_compatible() 定位目标节点。
4. 读取属性：通过 fdt_getprop() 获取寄存器地址、中断号等属性值。
5. 解析 reg：根据 #address-cells 和 #size-cells 解析地址与长度数组。

#include <libfdt.h>

int parse_spi_reg(void *fdt_blob) {
    int offset;
    const uint32_t *reg;
    int len;

    offset = fdt_node_offset_by_compatible(fdt_blob, -1, "vendor,spi-v1");
    if (offset < 0) return -1;

    reg = (const uint32_t *)fdt_getprop(fdt_blob, offset, "reg", &len);
    if (!reg || len < 8) return -1;

    uint64_t base_addr = ((uint64_t)fdt32_to_cpu(reg[0]) << 32) | fdt32_to_cpu(reg[1]);
    uint64_t size     = ((uint64_t)fdt32_to_cpu(reg[2]) << 32) | fdt32_to_cpu(reg[3]);

    // 映射寄存器基地址
    return 0;
}

4.2 寄存器描述文件：JSON 格式与解析

JSON（JavaScript Object Notation）因其轻量、易读、跨语言支持广泛，成为 HAL 驱动中寄存器描述文件的常用格式。一个寄存器描述 JSON 文件通常包含模块名、寄存器列表、位域定义等。

4.2.1 JSON 寄存器描述结构

以下示例展示了一个 UART 控制器的寄存器描述 JSON 文件：

{
  "module": "uart0",
  "base_address": "0xFF020000",
  "registers": [
    {
      "name": "UART_CTRL",
      "offset": "0x00",
      "size": 32,
      "description": "控制寄存器",
      "fields": [
        { "name": "TX_EN",  "bit": 0, "width": 1, "description": "发送使能" },
        { "name": "RX_EN",  "bit": 1, "width": 1, "description": "接收使能" },
        { "name": "MODE",   "bit": 4, "width": 2, "description": "模式选择" }
      ]
    },
    {
      "name": "UART_STATUS",
      "offset": "0x04",
      "size": 32,
      "description": "状态寄存器",
      "fields": [
        { "name": "TX_FULL", "bit": 0, "width": 1, "description": "发送 FIFO 满" },
        { "name": "RX_EMPTY","bit": 1, "width": 1, "description": "接收 FIFO 空" }
      ]
    }
  ]
}

4.2.2 JSON 解析库选型与对比

4.2.3 cJSON 解析示例

#include "cJSON.h"

void parse_uart_registers(const char *json_str) {
    cJSON *root = cJSON_Parse(json_str);
    if (!root) return;

    cJSON *regs = cJSON_GetObjectItem(root, "registers");
    int reg_count = cJSON_GetArraySize(regs);

    for (int i = 0; i < reg_count; i++) {
        cJSON *reg = cJSON_GetArrayItem(regs, i);
        const char *name = cJSON_GetObjectItem(reg, "name")->valuestring;
        uint32_t offset = strtoul(cJSON_GetObjectItem(reg, "offset")->valuestring, NULL, 16);

        cJSON *fields = cJSON_GetObjectItem(reg, "fields");
        int field_count = cJSON_GetArraySize(fields);

        for (int j = 0; j < field_count; j++) {
            cJSON *field = cJSON_GetArrayItem(fields, j);
            const char *fname = cJSON_GetObjectItem(field, "name")->valuestring;
            int bit = cJSON_GetObjectItem(field, "bit")->valueint;
            int width = cJSON_GetObjectItem(field, "width")->valueint;
            // 生成位域掩码
            uint32_t mask = ((1u << width) - 1) << bit;
        }
    }
    cJSON_Delete(root);
}

4.3 寄存器描述文件：YAML 格式与解析

YAML（YAML Ain't Markup Language）以缩进和键值对为核心语法，比 JSON 更易读，尤其适合人工编写和维护的寄存器描述文件。YAML 支持注释、锚点、别名等高级特性，在复杂硬件描述中优势明显。

4.3.1 YAML 寄存器描述示例

module: spi1
base_address: 0xFF030000
clock_freq: 50000000

registers:
  - name: SPI_CR1
    offset: 0x00
    size: 32
    description: "控制寄存器 1"
    fields:
      - { name: CPOL,  bit: 0, width: 1, desc: "时钟极性" }
      - { name: CPHA,  bit: 1, width: 1, desc: "时钟相位" }
      - { name: BR,    bit: 3, width: 3, desc: "波特率分频" }

  - name: SPI_DR
    offset: 0x0C
    size: 32
    description: "数据寄存器"
    access: read-write

4.3.2 YAML 解析库对比

4.3.3 libyaml 解析核心流程

#include <yaml.h>

int parse_yaml_registers(const char *filename) {
    FILE *fh = fopen(filename, "rb");
    yaml_parser_t parser;
    yaml_event_t event;

    yaml_parser_initialize(&parser);
    yaml_parser_set_input_file(&parser, fh);

    int in_registers = 0;
    do {
        yaml_parser_parse(&parser, &event);
        if (event.type == YAML_SCALAR_EVENT) {
            const char *value = (const char *)event.data.scalar.value;
            if (strcmp(value, "registers") == 0) in_registers = 1;
            else if (in_registers && strcmp(value, "offset") == 0) {
                // 读取下一个 scalar 作为偏移量
                yaml_parser_parse(&parser, &event);
                uint32_t offset = strtoul((const char *)event.data.scalar.value, NULL, 16);
            }
        }
        yaml_event_delete(&event);
    } while (event.type != YAML_STREAM_END_EVENT);

    yaml_parser_delete(&parser);
    fclose(fh);
    return 0;
}

4.4 工具链集成与最佳实践

在实际的多芯片网关项目中，寄存器配置工具链通常包含以下环节：

1. 源文件管理：使用 YAML 作为主格式维护寄存器数据库，支持注释和版本控制。
2. 格式转换：通过 Python 脚本将 YAML 转换为 JSON，供嵌入式端使用。
3. 代码生成：从 JSON 自动生成 C 头文件（寄存器地址宏、位域掩码）和 HAL 驱动骨架。
4. 运行时解析：在驱动初始化阶段，使用 cJSON 或 libfdt 解析配置，动态映射寄存器。

4.5 本章小结

寄存器配置工具链是 HAL 驱动适配的基石。DTS 解析依赖 libfdt 库，适用于 Linux 内核生态；JSON 格式轻量高效，cJSON 是嵌入式首选解析库；YAML 格式可读性强，适合人工维护的寄存器数据库。在实际工程中，建议采用 YAML 维护源文件、JSON 运行时解析、代码生成自动化的三层工具链架构，以最大化驱动可移植性和开发效率。