一句话结论：RT-Thread 驱动开发的本质不是“操作寄存器”， 而是把一个硬件对象翻译成一个 rt_device 对象，并让它的 ops、ref_count、rx_indicate、自动初始化级别全部符合内核约定。 做到这一点，上层 90% 的代码可以换 MCU 而一行不改；做不到，驱动就退化成一个挂 rt_device 外壳的裸机 API。 这份指南按“先选框架 → 再选路线 → 填 ops → 接中断 → 交付核查”的顺序，把每一步的决定点和坑点摊开写。

这份文档解决什么

写 RT-Thread 驱动时，真正卡住人的通常不是某个寄存器怎么配，而是下面这些结构性判断： 我这颗芯片该走经典模型还是 DM？init 和 open 到底谁负责初始化硬件？ 驱动注册早了总线还没起来怎么办？中断里能调哪些 API？环形缓冲满了该覆盖还是丢弃？ 设备名起冲突了为什么注册悄悄失败？这些问题的答案散落在源码、示例和社区帖子里， 本指南把它们收拢成一套可照做的流程，并给出可直接编译的骨架代码与可逐条勾选的核查清单。

面向 RT-Thread 4.x / 5.x 主线。凡涉及具体结构体字段与 API 签名的写法，均以你所用版本的头文件 rtdef.h / drivers/*.h 为准。

1 · 驱动体系全景

本章解决“我在给谁写代码”：先把 RT-Thread 把驱动切成哪几层、每层负责什么说清楚， 然后看清 rt_device 这一个结构体为什么能让上层与硬件解耦，最后给出框架选型的两级决策。

1.1 四层模型：谁负责什么

RT-Thread 的驱动体系通常被画成三层（应用层 / 管理层 / 驱动层）。真正落地时「驱动层」还要再拆成 设备驱动框架层与硬件底层驱动两层，否则说不清「为什么我这颗 UART 只需要写 5 个函数」。 图 1 给出完整四层视图。

这四层的边界不是形式主义，而是变更成本的分界线：从上往下的调用是允许的， 一旦出现反向依赖（例如应用直接 include MCU 头文件操作寄存器），换平台的代价就从「重写 drv 文件」 变成「重构整个项目」。表格给出每层的产出物与明令禁止的事。

1.2 rt_device：一个结构体撑起的抽象

整个抽象的支点是 struct rt_device。它的头部继承自 rt_object， 因此能被内核的对象容器统一管理（这也是 list_device 能把所有外设一起列出来的原因）； 真正的行为则由一组函数指针决定。主线源码里存在两种等价形态，由 RT_USING_DEVICE_OPS 宏切换：

/* rtdef.h —— 设备控制块（字段顺序与注释按 4.x/5.x 主线整理） */
struct rt_device
{
    struct rt_object          parent;      /* 继承对象基类：名字、类型、链表节点 */
    enum rt_device_class_type type;        /* 设备类别：字符 / 块 / SPI 总线 / I2C 总线 … */
    rt_uint16_t               flag;        /* 设备特性：RDWR / INT_RX / DMA_RX / STREAM … */
    rt_uint16_t               open_flag;   /* 打开时的模式：只读 / 只写 / 非阻塞 … */
    rt_uint8_t                ref_count;   /* 引用计数：open 加 1，close 减 1 */
    rt_uint8_t                device_id;   /* 次设备号，通常保留为 0 */

    /* 数据收发回调：由应用层设置，驱动在事件发生处调用 */
    rt_err_t  (*rx_indicate)(rt_device_t dev, rt_size_t size);
    rt_err_t  (*tx_complete)(rt_device_t dev, void *buffer);

#ifdef RT_USING_DEVICE_OPS
    const struct rt_device_ops *ops;       /* 形态 A：ops 打包成一张表，结构体更小 */
#else
    rt_err_t   (*init)(rt_device_t dev);   /* 形态 B：函数指针直接内联在对象内 */
    rt_err_t   (*open)(rt_device_t dev, rt_uint16_t oflag);
    rt_err_t   (*close)(rt_device_t dev);
    rt_ssize_t (*read)(rt_device_t dev, rt_off_t pos, void *buffer, rt_size_t size);
    rt_ssize_t (*write)(rt_device_t dev, rt_off_t pos, const void *buffer, rt_size_t size);
    rt_err_t   (*control)(rt_device_t dev, int cmd, void *args);
#endif
    void                      *user_data;  /* 驱动私有数据：HAL 句柄、寄存器基址、配置指针 */
};

字段虽多，日常真正要操心的只有三个：flag（声明设备能力，决定内核怎么对待它）、 ref_count（决定 init/open 是否重复执行）、user_data（承载私有数据， 是从 rt_device 反查回驱动实例的唯一正规通道）。其余字段由管理层维护，驱动不该自行改动。

1.3 两套框架：经典模型与 DM

RT-Thread 目前存在两套并行演进的驱动框架。若把「设备怎么被发现」当作区分点，两者差别一目了然：

1.4 选型决策：什么时候走哪条路

框架选定之后还有第二级决策：是复用现成的设备框架，还是自建一个 rt_device。图 2 把两级决策画成一棵树， 顺着走能直接落到本指南对应章节。

1.5 驱动在 BSP 工程中的落位

最后一个容易被忽略的问题是：驱动文件放哪里？放错位置带来的后果是别人根本编不到你的 C 文件， 或者同一个外设被两个 BSP 各维护一份。主线推荐的布局如下。

rt-thread/
├─ bsp/
│  └─ stm32/                          # 具体芯片系列 BSP
│     ├─ applications/                # 应用层：main.c、用户线程（不写驱动）
│     ├─ drivers/                     # ④ 硬件底层驱动：drv_uart.c / drv_spi.c / drv_gpio.c
│     ├─ board/
│     │  ├─ board.c                   # 板级初始化、堆初始化
│     │  └─ Kconfig                   # 板级配置项（在这里开出设备开关）
│     ├─ Libraries/
│     │  └─ HAL_Drivers/              # MCU 厂商 HAL 与 RT-Thread 的适配层
│     ├─ SConscript
│     └─ Kconfig
├─ components/
│  └─ drivers/
│     ├─ include/drivers/             # ③ 框架头文件：serial.h / spi.h / i2c.h / pin.h
│     ├─ serial/                      # ③ 串口框架实现
│     ├─ spi/                         # ③ SPI 框架实现
│     └─ …                            # ③ 其余框架
└─ include/rtdef.h                    # ② rt_device 定义所在

# 新加一个外设驱动时的最小改动集合
# 1) 新建          bsp/stm32/drivers/drv_xxx.c          芯片无关部分的框架对接
# 2) 硬件相关部分放进  Libraries/HAL_Drivers/drv_xxx.c    或第三方 HAL
# 3) 改            bsp/stm32/drivers/SConscript         让文件参与编译
# 4) 改            bsp/stm32/board/Kconfig              开出 RT_USING_XXX 开关
# 5) 不要在 applications/ 里注册设备

2 · 设备对象的生命周期

本章解决“驱动对象是怎么被内核接管、被应用找到、被反复打开又归还的”。 理解 ref_count 与 open_flag 的语义，能一次性消灭「硬件被初始化两次」「close 之后还能 read」「多次 open 只 close 一次」这类经典故障。

2.1 注册与动态创建

注册有两件事：给设备起一个全局唯一的名字，并把对象挂进内核的对象容器。 绝大多数驱动用静态设备对象（编译期分配），少数场景才在运行时用 rt_device_create 动态申请。

/* 方式一：静态（推荐）—— 结构体通常是某个私有 struct 的第一个成员 */
static struct rt_device   my_dev;          /* 或某个 struct myxxxx 的 parent 成员 */

static int my_dev_register(void)
{
    my_dev.type      = RT_Device_Class_Char;
    my_dev.flag      = RT_DEVICE_FLAG_RDWR;
    my_dev.init      = my_init;
    my_dev.open      = my_open;
    my_dev.close     = my_close;
    my_dev.read      = my_read;
    my_dev.write     = my_write;
    my_dev.control   = my_control;
    /* user_data 可选，见 2.6 节 */

    return rt_device_register(&my_dev, "mydev", RT_DEVICE_FLAG_RDWR);
}
INIT_DEVICE_EXPORT(my_dev_register);

/* 方式二：动态 —— attach_size 会额外分配一段内存挂在对象尾部 */
rt_device_t dev = rt_device_create(RT_Device_Class_Char, sizeof(struct my_priv));
if (dev == RT_NULL) { LOG_E("create failed"); return -RT_ENOMEM; }
/* 通过 dev->user_data 使用那段附加内存 */
struct my_priv *priv = (struct my_priv *)dev->user_data;
rt_device_register(dev, "mydev", RT_DEVICE_FLAG_RDWR);
/* 不再使用时：rt_device_destroy(dev); 会_unregister 并释放内存 */

2.2 查找、打开与引用计数

rt_device_find 返回的是对象指针，只代表设备已被注册，不代表硬件可用。 真正的可用性由 rt_device_open 保证，而它的行为完全围绕 ref_count 展开：

把这套语义翻译成驱动编写时的三条要求：

1. init 幂等且只负责「让硬件可工作」：时钟使能、引脚复用、DMA 通道申请。内核保证它只在第一次 open 时被调用一次，所以不要在里面做多次累加的事情。
2. open 负责使能申请者所需的能力：开中断、启动接收。多任务先后 open 同一设备时，open 只在计数为 0 时被回调一次；如果你的外设必须按「每个使用者一份资源」来开，请在自己的 priv 里再记一层计数。
3. close 必须能接受被推迟：只有 ref_count 归零才会回调 close。任何一方忘了 close，硬件就一直开着，低功耗场景会被这个问题咬到。

2.3 读写语义与阻塞策略

read / write 的返回值类型是 rt_ssize_t（有符号），这一点非常关键： 正数表示实际传输的字节数，0 通常表示无数据 / 结束，负数则是取反的错误码。 把 rt_ssize_t 当成 rt_size_t 来判断，会让 -RT_EIO 变成一个天文数字。

2.4 control 命令码设计

control 是 ioctl 的角色，承载「不属于读写的一切」：波特率、采样率、通道选择、寄存器诊断、进入低功耗等。 它的自由度也是它最容易失控的地方——命令码一旦发散，驱动就再也无法被替换。建议按下述规则统一：

/* 驱动侧：命令码集中定义在一个头文件里，供驱动与应用共享 */
#define MY_CMD_BASE          0x80          /* 避开内核通用命令区段 */

#define MY_CMD_SET_SPEED     (MY_CMD_BASE + 0)   /* args: uint32_t*  期望速率 */
#define MY_CMD_GET_SPEED     (MY_CMD_BASE + 1)   /* args: uint32_t*  实际速率 */
#define MY_CMD_SET_MODE      (MY_CMD_BASE + 2)   /* args: struct my_mode* */
#define MY_CMD_DUMP_REG      (MY_CMD_BASE + 3)   /* args: NULL，仅打印调试信息 */

static rt_err_t my_control(rt_device_t dev, int cmd, void *args)
{
    switch (cmd)
    {
    case RT_DEVICE_CTRL_SUSPEND:            /* 通用命令，低功耗钩子（见 10.6 节） */
        my_hw_lp_enter();
        return RT_EOK;
    case RT_DEVICE_CTRL_RESUME:
        my_hw_lp_exit();
        return RT_EOK;
    case MY_CMD_SET_SPEED:
        if (args == RT_NULL) return -RT_EINVAL;
        return my_hw_set_speed(*(rt_uint32_t *)args);
    default:
        LOG_W("unknown cmd 0x%x", cmd);
        return -RT_ENOSYS;                  /* 不认识的命令绝不返回 RT_EOK */
    }
}

2.5 rx_indicate 与 tx_complete

这是 RT-Thread 驱动最经典的异步通知机制：应用层把回调挂到设备的回调位上，驱动在事件发生处调用它。 图 4 给出一次「查找 → 打开 → 中断通知 → 读取 → 关闭」的完整时序。

/* ---- 应用层：设置回调 ---- */
static rt_sem_t rx_sem = RT_NULL;

static rt_err_t uart_rx_ind(rt_device_t dev, rt_size_t size)
{
    /* 注意：这里可能运行在中断上下文 */
    if (size > 0)
        rt_sem_release(rx_sem);
    return RT_EOK;
}

void app_entry(void)
{
    rx_sem = rt_sem_create("rx", 0, RT_IPC_FLAG_FIFO);
    rt_device_t dev = rt_device_find("uart2");
    rt_device_set_rx_indicate(dev, uart_rx_ind);         /* 挂回调 */
    rt_device_open(dev, RT_DEVICE_FLAG_INT_RX);          /* 以中断接收方式打开 */

    while (1)
    {
        if (rt_sem_take(rx_sem, RT_WAITING_FOREVER) == RT_EOK)
        {
            rt_size_t len = rt_device_read(dev, -1, buf, sizeof(buf));
            if (len > 0) handle(buf, len);
        }
    }
}

/* ---- 驱动侧：事件发生处调用（通常在 ISR 尾部）---- */
static struct rt_device *g_dev;   /* 注册时保存 */

void USART2_IRQHandler(void)
{
    rt_interrupt_enter();
    /* 1) 清中断标志  2) 把字节搬进 ringbuffer */
    ...
    /* 3) 通知上层：一定判空 */
    if (g_dev->rx_indicate != RT_NULL)
        g_dev->rx_indicate(g_dev, bytes_in_fifo);
    rt_interrupt_leave();
}

2.6 私有数据与容器反查

一个设备的全部状态（HAL 句柄、缓冲区、配置项）需要有一个落脚点。RT-Thread 的惯用做法是 让 rt_device 作为私有结构体的第一个成员，然后用 rt_container_of 从 rt_device_t 反查回来。

struct my_device
{
    struct rt_device      parent;      /* ← 必须是第一个成员！ */
    UART_HandleTypeDef   *huart;       /* HAL 句柄 */
    rt_uint32_t           irq_err_cnt; /* 统计信息 */
    struct rt_ringbuffer *rb;          /* 接收缓冲 */
    rt_uint32_t           baud;        /* 当前配置 */
};

static struct my_device g_devobj;      /* 静态分配，避免堆碎片 */

static rt_err_t my_open(rt_device_t dev, rt_uint16_t oflag)
{
    struct my_device *priv = (struct my_device *)dev->user_data;   /* 做法 A：用 user_data */
    /* 或者 */
    priv = rt_container_of(dev, struct my_device, parent);          /* 做法 B：容器反查 */
    ...
}

两种做法都常见，差别在于：user_data 是显式的、任何人可读的一枚指针； rt_container_of 则完全依赖结构体布局。建议遵循这条取舍： 私有结构体与 rt_device 同生共死时用 rt_container_of（语义最清晰，无需额外初始化）； 只有当私有数据可能被替换、或需要与其他非设备上下文共享时才放到 user_data。 二者混用时一定要保证指向同一个地方，否则会出现「两处状态不同步」的隐蔽 bug。

3 · 自动初始化与启动时序

本章解决“谁在什么时候调用我的注册函数”。RT-Thread 不用你去 main 里逐个 init()， 而是把函数指针放进特定链接段由内核遍历执行。这份便利的代价是：一旦依赖关系摆错阶段，故障会以「设备不存在」的形式随机出现。

3.1 六阶段宏与 .rti_fn 段

所有自动初始化宏最终都收敛到同一个 INIT_EXPORT(fn, level)，它把一个函数指针塞进名为 .rti_fn.<level> 的链接段。启动代码 rt_components_init() 按段名排序依次遍历这些函数—— 阶段其实就是链接段名字里的那一位数字。

/* rtdef.h —— 机制本身只有两行 */
typedef int (*init_fn_t)(void);

#define INIT_EXPORT(fn, level)                                              \\
    RT_USED static const init_fn_t __rt_init_##fn                           \\
    __attribute__((section(".rti_fn." level))) = fn

/* 由此派生的六个标准阶段 */
#define INIT_BOARD_EXPORT(fn)           INIT_EXPORT(fn, "1")
#define INIT_PREV_EXPORT(fn)            INIT_EXPORT(fn, "2")
#define INIT_DEVICE_EXPORT(fn)          INIT_EXPORT(fn, "3")
#define INIT_COMPONENT_EXPORT(fn)       INIT_EXPORT(fn, "4")
#define INIT_ENV_EXPORT(fn)             INIT_EXPORT(fn, "5")
#define INIT_APP_EXPORT(fn)             INIT_EXPORT(fn, "6")

3.2 依赖顺序与踩坑

同一 Stage 内各函数的执行先后取决于链接顺序（本质上是编译单元被打包进镜像的顺序）， 这在工程里几乎不可控。因此凡是存在依赖，就必须把它们放到不同阶段去。图 6 给出最常见的翻车现场与修法。

除了「从设备早于总线」之外，还有四种顺序问题在真实项目里高频出现：

3.3 自定义初始化级别

六个阶段不够细怎么办？INIT_EXPORT 的 level 是字符串，可以直接给出小数点后的段位， 例如 "3.5" 会排在 "3" 之后、"4" 之前。这比调整链接顺序可靠得多。

/* 自定义：总线之后、普通外设之前 */
#define MY_BUS_EXPORT(fn)  INIT_EXPORT(fn, "3.1")
#define MY_DEV_EXPORT(fn)  INIT_EXPORT(fn, "3.5")

MY_BUS_EXPORT(rt_hw_spi_bus_init);   /* 注册 spi0 / spi1 总线 */
MY_DEV_EXPORT(rt_hw_spi_dev_init);   /* 挂载 spi 从设备，此时总线一定在场 */

/* 注意：命名建议带上项目前缀，避免与主线后续新增的宏冲突 */

3.4 DM 框架下的启动顺序

开启 RT_USING_DM 后，阶段表多出三项，顺序大致如下（具体名称与版本相关，以 rtdef.h 为准）：

4 · 驱动开发的两条路线

本章解决“我这颗外设到底该怎么写”。选对路线，可能只需要填五个函数； 选错路线，可能在重复实现别人早就写好并经过量产验证的缓冲区逻辑。

4.1 决策依据

判断顺序建议如下，只要有一条回答「是」就走复用路线：

1. 该外设是否属于某个已有设备框架（见 4.2 节清单）？
2. 是否需要融进现有生态——FinSH 控制台、ulog、at 组件、sensor 框架、各种软件包？
3. 是否需要跟别人写的应用代码对接，而对方只会用标准 rt_device_* API？
4. 未来是否可能换 MCU / 换同类型芯片？

四个问题都回答「否」，才有理由自建设备：通常是专用 ASIC、自定义 FPGA 逻辑、 或者需要一种框架没定义的流式/块式混合语义的器件。

4.2 内置设备框架清单

下表列出主线 components/drivers 里常见的框架。写驱动前先在这张表里找一遍， 能找到就用它的注册函数，不要另起炉灶。

4.3 两条路线工作量对比

图 7 把两条路线各自要做的东西摊开。真正的差异不在代码行数，而在谁负责 infra。

4.4 从裸机驱动改造而来

很多项目手上有现成的裸机驱动：初始化函数、查询式收发、几个延时会要塑料??。 把它们改造成标准 RT-Thread 驱动，推荐按下面五步做，每一步都是可以单独验证的。

1. 先跑通裸机：用逻辑分析仪或串口确认硬件 OK。带着硬件问题进 RTOS 会把问题复杂度翻倍。
2. 抽设备私有结构体：把裸机里散落的全局变量集中到一个 struct xxx { struct rt_device parent; … } 里。
3. 把 gpio/init 拆成 init 钩子：原裸机初始化中「一次性的、全局的」部分进 init，「每次打开才需要的」进 open。
4. 查询式收发转中断 + 缓冲：裸机的轮询 while 必须移除（会阻塞整个线程），改成 ISR 收 + 上层 read，见第 8 章。
5. 补 control 与收尾：把裸机里那些配置宏换算成 control 命令，确认 close 能让硬件进入可重入状态。

/* 改造前后对照 —— 一个典型的报错根源 */

/* 【裸机思维】下面这段搬到 RTOS 里一定会出问题 */
void uart_send(uint8_t *buf, uint16_t len)
{
    for (uint16_t i = 0; i < len; i++)
    {
        while (!(USART2->SR & USART_SR_TXE));   /* ✗ 忙等：把整个线程卡死 */
        USART2->DR = buf[i];
    }
    while (!(USART2->SR & USART_SR_TC));        /* ✗ 同上 */
}

/* 【RT-Thread 写法】写侧可以是阻塞的（框架用完成量同步），
   但阻塞必须是「线程挂起」而不是「while 轮询」 */
static rt_ssize_t my_write(rt_device_t dev, rt_off_t pos, const void *buffer, rt_size_t size)
{
    /* 交给框架：由框架的完成量 or ISR 驱动后续字节 */
    rt_size_t n = rt_hw_serial_write((struct rt_serial_device *)dev, pos, buffer, size);
    return (rt_ssize_t)n;
}
/* read 侧：拿不到数据就让出 CPU */
static rt_ssize_t my_read(rt_device_t dev, rt_off_t pos, void *buffer, rt_size_t size)
{
    rt_size_t len = rt_hw_serial_read((struct rt_serial_device *)dev, pos, buffer, size);
    if (len == 0 && !(dev->open_flag & RT_DEVICE_OFLAG_NONBLOCKING))
    {
        /* 等待 rx_indicate 释放的信号量等 —— 由上层负责等待，
           驱动内部只负责在有数据时返回字节数 */
    }
    return (rt_ssize_t)len;
}