peripherals-from-datasheet

根据数据手册实现外设

目的

指导 Agent 通过一套可重复的方法，根据 MCU 参考手册编写外设驱动：定位寄存器映射、解读位定义、遵循初始化顺序、遵守时序约束，并编写易于维护的寄存器级代码。可与 skills/baremetal/datasheet-and-refmanual-reading 搭配使用，了解文档导航方法（作为独立技能保留）。

适用场景

• 不使用厂商 HAL，从头开始编写驱动
• 在不同 MCU 系列之间移植外设
• 根据参考手册验证 HAL 的行为
• 调试示例中“本应正常工作”的外设

工作流

1. 浏览参考手册

Typical RM structure
├── Memory map (peripheral base addresses)
├── Peripheral chapter (UART, SPI, GPIO, ...)
│   ├── Functional description
│   ├── Register map (table of offsets)
│   ├── Register bit definitions
│   └── Timing / electrical notes
└── Electrical characteristics (clock limits, setup/hold)

先阅读编程模型章节，再复制寄存器写入操作。

2. 提取寄存器映射

/* From RM — USART base 0x40004400 */
typedef struct {
    volatile uint32_t SR;   /* 0x00 status */
    volatile uint32_t DR;   /* 0x04 data */
    volatile uint32_t BRR;  /* 0x08 baud */
    volatile uint32_t CR1;  /* 0x0C control */
    /* ... */
} USART_TypeDef;

#define USART2 ((USART_TypeDef *)0x40004400UL)

确认偏移量列与结构体布局一致（为保留字填充）。

3. 初始化顺序检查清单

Peripheral bring-up order
├── 1. Enable bus clock (RCC/APB/AHB register)
├── 2. Reset peripheral (if RM requires)
├── 3. Configure pins (GPIO alternate function)
├── 4. Configure peripheral registers (mode, baud, etc.)
├── 5. Enable peripheral (UE, TE, RE bits)
├── 6. Enable NVIC IRQ (if interrupt-driven)
└── 7. Verify status flags before first transaction

错误 — 在启用时钟前启用 UART：

USART2->CR1 |= USART_CR1_UE;  /* USART clock still off — no effect */

4. 位定义规范

/* From RM: CR1 M[1:0], PCE, PS, TE, RE, UE */
#define USART_CR1_UE   (1U << 13)
#define USART_CR1_TE   (1U << 3)
#define USART_CR1_RE   (1U << 2)

在注释中记录 RM 章节编号，以便审查追溯。

5. 时序与忙等待

/* RM: poll BUSY flag until reset complete */
while (RCC->CR & RCC_CR_PLLRDY == 0)
    ;

遵守电气特性章节中规定的启动时间（振荡器稳定、PLL 锁定）。

6. 良好与糟糕的驱动结构

良好 — 分层，并引用 RM：

void usart2_init(uint32_t baud) {
    rcc_enable_usart2();
    gpio_config_usart2_pins();
    usart2_set_baud(baud);
    USART2->CR1 = USART_CR1_TE | USART_CR1_RE | USART_CR1_UE;
}

糟糕 — 使用魔数，且未启用时钟：

*(uint32_t*)0x4000440C = 0x2000;  /* what peripheral? which bit? */

7. Agent 使用示例

/peripherals-from-datasheet Walk me through USART init from STM32 RM
/peripherals-from-datasheet What sections of the ref manual matter for SPI timing?

常见问题

症状	原因	修复方法
外设无响应	未启用时钟	先设置 RCC/APB 使能位
波特率错误	对 PCLK 的假设有误	根据实际时钟树重新计算
GPIO AF 错误	从错误的表中获取 MUX 值	对照引脚分配表和 AF 表核对
IRQ 卡住	状态标志清除顺序错误	查阅 RM 中的“清除标志”小节
数据静默损坏	字节序或宽度不匹配	确保寄存器访问大小一致

相关技能

• skills/baremetal/datasheet-and-refmanual-reading — 快速浏览 RM
• skills/baremetal/mmio-and-bit-manipulation — 寄存器访问模式
• skills/baremetal/gpio-baremetal — 在启用外设前配置引脚复用
• skills/embedded/linker-scripts — 内存映射对齐