芯片包结构

本文档详细介绍芯片模板的目录结构和文件组织方式。理解芯片包的结构是进行芯片模板开发的基础。

顶层目录结构

chip-template/
├── chip/                  # 芯片配置
│   └── {series}/          # 系列级配置
│       ├── code.cjs       # IP 类型到模板版本的映射
│       ├── define.cjs     # 系列特定的寄存器/宏定义
│       ├── ide.cjs         # IDE 设置（驱动路径、固件文件）
│       └── {chip-model}/  # 芯片型号级配置
│           ├── info.cjs   # 芯片元数据
│           ├── pins.cjs   # 引脚复用功能映射
│           ├── nvic.cjs   # NVIC 中断定义
│           ├── dma.cjs    # DMA 通道分配
│           └── ui.cjs     # 图形化配置 UI 配置
├── ips/                   # 外设 IP 模板
│   └── {IP}/              # 如 GPIO、ADC、SPI 等
│       ├── code/          # 代码生成模板
│       │   └── {version}/ # 版本化模板
│       │       ├── pre.cjs    # 初始化脚本
│       │       ├── std.c.ejs  # Standard 固件模板
│       │       ├── hal.c.ejs  # HAL 固件模板
│       │       └── ll.c.ejs   # LL 固件模板
│       ├── ui/            # UI 配置
│       │   ├── base.cjs   # 基础配置（通用）
│       │   └── {series}.cjs # 系列特定配置
│       └── doc/           # IP 文档
├── common/                # 通用模板
│   ├── gpio/              # GPIO 通用模板
│   ├── dma/               # DMA 通用模板
│   ├── nvic/              # NVIC 通用模板
│   └── ...                # 其他通用模板
├── sdk/                   # 固件 SDK
├── data/                  # 提取用的源数据
└── scripts/               # 构建和提取脚本

系列配置层（Series Level）

系列配置定义了该系列下所有芯片型号的共享属性。

code.cjs — IP 版本映射

定义该系列支持的 IP 类型和使用的模板版本：

// chip/GD32F103XX/code.cjs
module.exports = {
  ADC: {
    ip_type: 'ADC',
    version: '1.0'        // 使用的 code 模板版本
  },
  GPIO: {
    ip_type: 'GPIO',
    version: '1.0'
  },
  USART: {
    ip_type: 'USART',
    version: '1.0'
  },
  // ... 其他 IP
}

define.cjs — 宏定义映射

定义寄存器宏和常量映射，用于固件适配：

// chip/GD32F103XX/define.cjs
module.exports = {
  GPIO: {
    mode: {
      AIN: 'GPIO_MODE_AIN',
      IN_FLOATING: 'GPIO_MODE_IN_FLOATING',
      IPD: 'GPIO_MODE_IPD',
      // ...
    },
    speed: {
      GPIO_OSPEED_10MHZ: 'GPIO_OSPEED_10MHZ',
      GPIO_OSPEED_2MHZ: 'GPIO_OSPEED_2MHZ',
      GPIO_OSPEED_50MHZ: 'GPIO_OSPEED_50MHZ'
    }
  }
}

ide.cjs — IDE 设置

定义不同 IDE 平台的配置信息：

// chip/GD32F103XX/ide.cjs
module.exports = {
  keil: {
    device: 'GD32F103ZE',
    cpu: 'Cortex-M3'
  },
  iar: {
    device: 'GD32F103ZE',
    cpu: 'Cortex-M3'
  },
  eide: {
    // VSCode EIDE 插件配置
  },
  cmake: {
    toolchain: 'arm-none-eabi-gcc'
  }
}

芯片型号配置层（Model Level）

每个具体的芯片型号有自己独立的配置。

info.cjs — 芯片元数据

// chip/GD32F103XX/GD32F103ZET6/info.cjs
module.exports = {
  name: 'GD32F103ZET6',
  series: 'GD32F103XX',
  flash: 512,              // Flash 大小 (KB)
  ram: 64,                 // RAM 大小 (KB)
  io: 112,                 // IO 口数量
  package: 'LQFP144',      // 封装类型
  ips: [                   // 外设列表
    { name: 'ADC', max: 3 },     // 3 个 ADC 实例
    { name: 'CAN', max: 1 },
    { name: 'GPIO', max: 1 },    // GPIO 作为单例
    { name: 'SPI', max: 3 },
    { name: 'TIM', max: 8 },     // 8 个定时器
    { name: 'USART', max: 5 },
    // ...
  ]
}

ips 数组格式说明：

• name：外设类型名称（如 'ADC'、'TIM'）
• max：该外设的最大实例数量

pins.cjs — 引脚复用功能映射

// chip/GD32F103XX/GD32F103ZET6/pins.cjs
module.exports = [
  {
    name: 'PA0',
    port: 'GPIOA',
    pin: 'GPIO_PIN_0',
    af: [
      { name: 'Reset_State', value: '-1' },
      { name: 'GPIO_Input', value: 'GPIO_Input' },
      { name: 'USART1_TX', value: 'GPIO_ALTERNATE_USART1_TX' },
      { name: 'TIM2_CH1', value: 'GPIO_REMAP_TIM2_CH1' }
    ]
  },
  // ... 其他引脚
]

nvic.cjs — 中断定义

module.exports = {
  ip_names: {
    // 中断号 → 关联的外设名称
    'USART1_IRQn': 'USART1',
    'TIM2_IRQn': 'TIM2',
    'ADC1_2_IRQn': 'ADC1',
    // ...
  }
}

ip_names 过滤机制

只有当 ip_names 中引用的 IP 存在于 info.cjs.ips 中时，对应的中断才会被包含在生成的代码中。这确保只为该芯片型号实际存在的外设生成中断处理代码。

外设 IP 组织

每个 IP 外设的模板按以下结构组织：

ips/GPIO/
├── code/1.0/              # 代码模板版本 1.0
│   ├── pre.cjs            # 数据预处理脚本
│   ├── std.c.ejs          # Standard 固件 C 代码模板
│   ├── hal.c.ejs          # HAL 固件 C 代码模板
│   └── ll.c.ejs           # LL 固件 C 代码模板
├── ui/                    # UI 配置
│   ├── gpio_base.cjs      # 基础 UI 配置
│   └── gd32f103.cjs       # 特定系列 UI 配置
└── doc/                   # 文档
    └── GPIO优化说明.md

支持的 IDE 和固件类型

IDE 类型

IDE	说明	项目文件格式
Keil MDK	ARM 官方 IDE	.uvprojx
IAR EWARM	IAR 嵌入式 IDE	.ewp
EIDE	VSCode 嵌入式插件	.eide
CMake	跨平台构建系统	CMakeLists.txt
Makefile	GNU Make 构建	Makefile

固件类型

固件	全称	特点
HAL	Hardware Abstraction Layer	高度抽象，易用，代码量较大
LL	Low Layer	接近寄存器操作，轻量，高性能
STD	Standard Peripheral Library	传统标准外设库

版本管理架构

芯片模板的版本管理遵循以下层次：

芯片型号配置（最高优先级）
    ↓ 覆盖
特定系列版本（如 gd32f103.cjs）
    ↓ 覆盖
通用基础版本（如 gpio_base.cjs）

具体说明请参见 版本管理机制。