ddev-hardware

name	ddev-hardware
description	固件/嵌入式项目硬件资源分析与文档化。从 sdkconfig、peripheral_cfg.h、分区表等文件中提取 MCU 算力、存储、外设、GPIO 信息，输出结构化硬件规格文档。

ddev-hardware — 硬件资源搜索与文档化

从固件仓库的配置文件中提取硬件资源信息，输出结构化的 Markdown 硬件规格文档。

触发条件

用户请求分析硬件资源、硬件规格、主板资源、外设清单、引脚定义，或要求"硬件文档""hardware spec""板级资源""GPIO 汇总"。

输入约定

执行前需确认两个信息（若用户未提供则主动扫描）：

1. 当前激活的机型 — 从机型配置头文件中提取（通常是 prt_cfg.h、board_cfg.h、*_cfg.h 中 #define 的宏）
2. 项目根目录 — 当前工作目录或用户指定的路径

执行流程

1. 定位当前机型

在项目根目录下搜索机型定义：

grep -rn "^#define TP\|^#define BOARD_\|^#define PRODUCT_" --include="*_cfg.h" --include="*board*.h" | head -30

规则：

• 以非注释的 #define <NAME> 行为准
• 优先识别含 GEN、DEV、V2、MT 等版本/变体后缀的宏
• 若用户指定了目标机型，直接使用，不做自动检测

2. 提取计算与存储资源

从 ESP-IDF 的 sdkconfig 或等效内核配置文件中提取：

# CPU 核数与频率
grep -E "UNICORE|DEFAULT_CPU_FREQ|NUMBER_OF_CORES" sdkconfig

# 缓存配置
grep -E "INSTRUCTION_CACHE_SIZE|DATA_CACHE_SIZE|CACHE" sdkconfig

# Flash 配置
grep -E "FLASHSIZE|FLASHMODE|FLASHFREQ|FLASH_SIZE" sdkconfig

# PSRAM / 外部 RAM
grep -E "SPIRAM|PSRAM|EXTERNAL_RAM" sdkconfig

必须回答的关键问题：

• MCU 型号是什么？（从 IDF_TARGET 或 CMakeLists 推导）
• CPU 架构/内核？（ESP32→LX6, ESP32-S3→LX7, ESP32-C3/C6→RISC-V，类推）
• 几核？主频多少？
• 片内 SRAM 多大？有无片上 ROM？
• I-Cache / D-Cache 各多大？
• 固件存哪里？（片内 Flash 还是片外 SPI Flash？容量多少？）
• 有无 PSRAM？容量多大？

嵌入式 MCU 的片内 ROM/SRAM 值可从芯片 datasheet 常量获取，不需要从配置文件推导。

3. 提取 Flash 分区布局

搜索项目中的分区表文件：

find . -name "partitions*.csv" -o -name "partitions*.h" | head -10

根据当前机型选择对应的分区表文件，解析 CSV 格式的分区表：

• 跳过 # 注释行
• 提取 Name、Offset、Size 列
• 标注每个分区的用途（根据 Name 推断：factory→出厂固件，ota→OTA 升级区，parameter/nvs→参数存储，font→字库，wave→音频）

必须注明：固件写入的起始偏移、最大可用空间。

4. 提取外设硬件

在项目中搜索外设配置文件（常见文件名：prt_peripheral_cfg.h、peripheral_cfg.h、board_pin.h、pin_mux.h）：

find . -name "*peripheral*" -o -name "*pin_mux*" -o -name "*board_pin*" | head -10

从该文件中逐段扫描，每个 // ===== 或明显的注释分隔块对应一类外设。提取以下信息：

通信接口：

• UART：编号、TX/RX/RTS/CTS 引脚、用途（连接什么模块）
• SPI：总线号、MOSI/MISO/SCK/CS 引脚、频率、连接的设备
• I2C：SCL/SDA 引脚、频率、连接的设备
• I2S：MCLK/BCK/WS/DATA 引脚、采样率、连接的 Codec
• USB：DP/DM/VBUS 引脚、用途
• WiFi：芯片型号、接口类型（SDIO/SPI/UART）、复位引脚
• 蓝牙：是否使能
• 4G/LTE：模块型号、UART 绑定、电源/复位引脚
• 以太网：是否使能、复位引脚

执行机构（若为打印机/电机控制类设备）：

• 打印头/显示：数据总线绑定、锁存/使能引脚
• 电机：驱动芯片型号、各相/步进引脚、使能/休眠引脚、数量
• 切刀/机械：传感器引脚、步数配置

传感器与检测：

• ADC 通道：各通道用途（温度/电压/位置检测）、对应的 GPIO
• GPIO 传感器：纸张检测、位置检测、盖板检测等

音频：

• DAC/Codec 型号、接口类型
• 扬声器控制引脚、PWM 通道

人机交互：

• LED：颜色数量、各 GPIO
• 物理按键：功能、GPIO
• 触摸按键：GPIO

电源与系统：

• 外设供电控制 GPIO
• 系统电源使能 GPIO
• 复位引脚

5. 整理 GPIO 汇总表

将所有 GPIO 整理成统一表格：GPIO 号、功能、方向（I/O）、备注（复用/特殊说明）。

过滤规则：

• PRT_GPIO_UNVALID、-1、0xFF 等无效值不列出
• 同一个 GPIO 被多个功能复用时要明确标注

6. 提取机型差异（可选）

若 prt_cfg.h 中存在多个 #if defined(MODEL_A) ... #elif defined(MODEL_B) 分支，提取当前机型所在分支的 #define 列表，并与相邻机型分支对比，总结功能差异。

7. 输出文档

写入 docs/spec/<MODEL>-hardware-spec.md，按以下结构：

# <MODEL> 硬件资源规格
> 整理自: <源文件列表>
> 日期: <当前日期>

## 一、主控与计算资源
- MCU 型号、内核架构和说明、核数、主频
- I-Cache / D-Cache 大小
- 片内 SRAM / ROM 大小

## 二、存储资源
- 片内存储（SRAM、ROM、RTC 内存）
- 片外 Flash（容量、接口类型、频率、用途）
- 片外 PSRAM（容量、接口类型、频率、用途）
- 明确指出固件烧录到哪个物理介质

## 三、Flash 分区布局
- 主分区表（名称、偏移、大小、用途）
- 子分区（如有）

## 四、通信接口
## 五、打印/执行子系统（根据实际硬件调整标题）
## 六、音频子系统
## 七、人机交互
## 八、电源与系统
## 九、系统参数（任务栈、RTOS 配置等）
## 十、GPIO 汇总
## 十一、机型差异对比（如有多个变体）

注意事项

• 不要假设项目目录名或文件名；所有路径通过 find / grep 搜索得到
• 芯片 datasheet 中的常数值（片内 SRAM/ROM 大小）直接写入文档，无需验证
• 分区表解析时跳过 # 注释行，正确处理 hex 偏移值
• 对于 PRT_GPIO_UNVALID / -1 等占位符，视为"未使用"，不写入汇总
• PSRAM 若配置为自动检测，标注"自动检测"而非猜测具体数值
• 文档中使用物理量单位（KB/MB/MHz）而非 hex 原始值，两者可同时出现
• 若用户指定了机型而当前代码激活的是另一个机型，需要提醒用户