embedded-code-skill

name	embedded-code-skill
description	Generate, rewrite, or review embedded C code. Use when creating/rewriting/reviewing embedded C for microcontrollers, drivers, firmware. Triggers automatically when user mentions: generate, create, write code, implement driver, rewrite, refactor, review, check, audit.
user-invocable	true

Embedded C 代码生成规范

概述

本规范用于生成生产级嵌入式 C 代码，适用于 STM32、PowerPC、RISC-V 等平台。

核心原则: 像嵌入式软件架构师一样思考，生成可演进、可测试、可移植的代码。

---

思维方式

生成代码时必须以嵌入式软件架构师的思维进行:

维度	要求
系统视角	设计可演进的系统，考虑模块边界、接口契约、依赖关系
资源意识	内存精确计算缓冲区，CPU 减少中断嵌套，优化关键路径
实时性	ISR 应尽可能短，考虑 WCET，防范优先级反转/死锁/队列溢出
可靠性	看门狗策略、异常恢复、关键数据冗余存储
硬件无关	寄存器抽象为结构体，驱动与业务逻辑分离
可测试	公共接口易 mock，状态机可单步测试，边界条件覆盖

---

编码规范

1. 类型规范

类型	用途	禁止
uint8_t	单字节、GPIO	char, signed char
uint16_t	16位寄存器	short, unsigned short
uint32_t	32位寄存器、时间戳	int, long, unsigned int
int32_t	有符号值	-
uint64_t	64位数据	-
bool	布尔标志	-

必须包含的头文件:

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

2. 命名规范

元素	格式	示例
变量	snake_case	sensor_value, data_count
全局变量	g_snake_case	g_system_ticks
常量/宏	SCREAMING_SNAKE	MAX_BUFFER_SIZE, SPI_CR_EN
函数	camelCase	initUart(), getSensorData()
结构体类型	snake_case_t	uart_config_t
枚举类型	snake_case_t	gpio_state_t
枚举值	PREFIXED_SNAKE	GPIO_STATE_LOW
指针	p_snake_case	p_rx_buffer
寄存器结构体	module_name_reg_t	spi_reg_t
寄存器头文件	module_reg.h	spi_reg.h

3. 错误处理

所有 public 函数必须:

1. 返回 embedded_code_status_t 枚举类型
2. 验证所有输入指针（NULL 检查）
3. 返回具体错误码

typedef enum {
    EmbedCode_Ok = 0,
    EmbedCode_ErrNullPtr = -1,
    EmbedCode_ErrInvalidArg = -2,
    EmbedCode_ErrTimeout = -3,
    EmbedCode_ErrBusy = -4,
    EmbedCode_ErrNotInit = -5
} embedded_code_status_t;

#define VALIDATE_NOT_NULL(ptr) \
    do { if ((ptr) == NULL) return EmbedCode_ErrNullPtr; } while(0)

4. 注释规范

注释语言: 优先使用中文

原则	说明
中文优先	便于团队阅读和维护
解释 WHY	注释应说明原因和意图，而非描述代码在做什么
代码自说明	如果代码本身已清楚表达含义，无需注释

Doxygen 文件头格式:

/**
 * @file spi_reg.h
 * @brief SPI 寄存器结构体定义
 * @author Claude Code
 * @date 2026-04-10
 */

行内注释示例:

config |= SPI_CR_EN_MASK;  /* 启用 SPI，低电平有效 */

5. 寄存器结构体定义

每个外设模块必须有独立的 reg.h 文件:

必需元素	说明
XXX_BASE_ADDR	基地址定义，格式：XXX_BASE_ADDR
xxx_reg_t	寄存器结构体，使用 volatile uint32_t
XXX_XXX_MASK/SHIFT	位字段宏定义
XXX_REG	结构体指针访问宏

reg.h 模板:

/**
 * @file spi_reg.h
 * @brief SPI 外设寄存器定义
 */
#ifndef SPI_REG_H
#define SPI_REG_H

#include <stdint.h>

/* 基地址 */
#define SPI_BASE_ADDR  (0xA0010000U)

/* 寄存器结构体 */
typedef struct {
    volatile uint32_t CTRL;     /* 0x00: 控制寄存器 */
    volatile uint32_t STATUS;   /* 0x04: 状态寄存器 */
    volatile uint32_t DATA;     /* 0x08: 数据寄存器 */
} spi_reg_t;

/* 位字段定义 */
#define SPI_CTRL_EN_MASK      (1U << 0)
#define SPI_CTRL_MODE_MASK    (3U << 2)

/* 寄存器访问 */
#define SPI_REG  ((spi_reg_t *) SPI_BASE_ADDR)

#endif /* SPI_REG_H */

6. 寄存器赋值规范

禁止直接赋字面值，必须使用已定义的宏:

// ❌ 错误
SPI_REG->CTRL = 0x47U;
SPI_REG->BAUD = 250U;

// ✅ 正确
SPI_REG->CTRL = SPI_CTRL_INIT_VAL;
SPI_REG->BAUD = SPI_BAUD_DIV;

7. 安全编码

禁止	必须
malloc, free, calloc, realloc	固定大小缓冲区
new, delete	环形缓冲区用于数据流
VLA (变长数组)	精确计算的缓冲区大小

#define BUFFER_SIZE 256U
uint8_t buffer[BUFFER_SIZE];

8. 数据结构

场景	方式
相关配置数据	struct
相关常量集合	enum
相关状态数据	struct

/* 配置结构体 */
typedef struct {
    uint32_t base_address;
    uint16_t interrupt_priority;
    bool     enable_dma;
} peripheral_config_t;

/* 句柄结构体 */
typedef struct {
    bool                initialized;
    peripheral_config_t config;
} peripheral_handle_t;

---

工作模式

GENERATE 模式

直接应用本规范生成代码，无需保留任何旧代码。

REWRITE 模式

核心原则: 功能流程优先

⚠️ 用户提供的源代码代表着原有的功能实现流程。即使代码有错误，在修改前必须先完整理解其功能流程，再进行符合规范的改写。不得为符合规范而破坏原有的功能流程。

执行步骤:

步骤	内容
Step 1: 理解原代码	梳理数据流、识别状态机/算法、标注寄存器操作
Step 2: 识别重写部分	确定需重构的函数/模块
Step 3: 按规范重写	类型/命名/结构体符合规范，功能逻辑保持一致
Step 4: 回查验证	验证功能流程未改变，所有规范已满足

关于原代码中的 bug：

• 原代码的 bug 属于"功能流程"的一部分
• 如果 bug 是用户期望保留的行为（如已知的工作around），保持原样
• 如果原代码有语法错误无法编译，标注问题但不擅自修复
• 除非用户明确要求，否则不修改原代码的功能逻辑

REVIEW 模式

检查现有代码是否符合嵌入式 C 规范。

执行步骤:

步骤	内容
Step 1: 对照检查	按回查清单逐项检查
Step 2: 标注问题	列出不符合规范的地方
Step 3: 提出建议	提供具体的修改建议

---

项目文件结构

project/
├── inc/
│   ├── module_reg.h      # 寄存器结构体定义（每个外设必须有）
│   ├── module_config.h   # 配置参数
│   └── module.h          # 公共接口
└── src/
    └── module.c          # 实现

---

PDCA 工作流

┌─────────────────────────────────────────────────────────┐
│  P (Plan) - 分析需求，检查完备性                         │
│    • 确定模式: GENERATE / REWRITE / REVIEW              │
│    • 检测领域/架构/外设关键词                            │
│    • 检查关键信息是否完备（基地址等）                     │
│    ⚡ REWRITE模式: 优先理解原代码功能流程                │
├─────────────────────────────────────────────────────────┤
│  D (Do) - 生成/重写代码                                 │
│    • GENERATE: 直接应用本规范                           │
│    • REWRITE: 保持原功能流程，应用本规范                 │
│    • 创建或更新 reg.h 寄存器结构体定义                   │
│    • 生成符合规范的代码                                  │
├─────────────────────────────────────────────────────────┤
│  C (Check) - 回查验证                                   │
│    • 对照回查清单逐项检查                               │
│    • 验证寄存器结构体定义是否正确                        │
│    ⚡ REWRITE模式: 验证功能流程是否保持一致             │
├─────────────────────────────────────────────────────────┤
│  A (Act) - 修正输出                                     │
│    • 修正所有发现的问题                                  │
│    • 重新回查确认                                       │
│    • 输出合格代码                                        │
└─────────────────────────────────────────────────────────┘

---

回查清单

生成后必须逐项检查:

#	检查项	不合格则修正
1	是否有对应的 reg.h 文件?	创建 reg.h
2	寄存器是否用 volatile uint32_t 结构体定义?	重构为结构体
3	位字段是否有宏定义 (MASK/SHIFT)?	添加位字段宏
4	类型是否仅用 stdint.h?	替换所有非标准类型
5	命名是否符合规范表?	修正所有命名
6	所有 public 函数有错误处理?	添加状态返回
7	无任何 malloc/free/VLA?	替换为固定缓冲区
8	注释是否使用中文?	重写注释
9	文件头是否完整 (Doxygen)?	添加 Doxygen
10	生成的代码是否符合规范?	修正生成代码
⚡ 11	REWRITE 模式: 原代码的功能流程是否保持一致?	确保数据流/状态机/算法逻辑不变
⚡ 12	寄存器赋值是否都使用宏?	添加宏定义，禁止字面值赋值

---

常见错误

错误 1: 寄存器定义散落各处

// ❌ 错误
#define SPI_CTRL_ADDR  (*(volatile uint32_t *)0xA0010000)
void spiInit(void) { SPI_CTRL_ADDR = 0x47; }

// ✅ 正确 - 独立的 reg.h，统一的命名风格
#include "spi_reg.h"
void spiInit(void) { SPI_REG->CTRL = SPI_CTRL_INIT_VAL; }

错误 2: 魔法数字

// ❌ 错误 - 含义不清
if (SPI_REG->STATUS & 0x04) { }
SPI_REG->CTRL |= (1U << 7);

// ✅ 正确 - 命名位字段宏
if (SPI_REG->STATUS & SPI_STATUS_TF_EMPT_MASK) { }  /* TX FIFO empty */
SPI_REG->CTRL |= SPI_CTRL_SCPOL_MASK;               /* 时钟极性 */

错误 3: 使用 __I/__IO 前缀

// ❌ 错误 - ARM CMSIS 特有，不具可移植性
typedef struct {
    __I uint32_t DATA;
    __IO uint32_t CTRL;
} spi_reg_t;

// ✅ 正确 - 标准 volatile
typedef struct {
    volatile uint32_t DATA;
    volatile uint32_t CTRL;
} spi_reg_t;

错误 4: 直接赋字面值

// ❌ 错误 - 魔法数字
SPI_REG->BAUD = 250U;
SPI_REG->CTRL = 0x08U;

// ✅ 正确 - 使用宏定义
SPI_REG->BAUD = SPI_BAUD_DIV;
SPI_REG->CTRL = SPI_CTRL_INIT_VAL;

---

输出格式

GENERATE 模式输出每个外设模块:

module/
├── module_reg.h    # 寄存器结构体定义
├── module.h        # 公共接口
└── module.c       # 实现