Define 映射指南

本文档介绍芯片模板中寄存器宏定义（define）的映射机制。define 映射将 UI 参数值转换为特定固件平台（HAL / LL / STD）的 SDK 宏。

什么是 Define 映射

用户在 UI 中选择的参数值（如 OUT_PP、m2p）是芯片模板内部的统一标识，与具体 SDK 的宏定义（如 GPIO_MODE_OUT_PP、DMA_MEMORY_TO_PERIPHERAL）不同。Define 映射在这两者之间建立对应关系。

UI 值 (OUT_PP)  ──define映射──→  STD: GPIO_MODE_OUT_PP
                                 HAL: GPIO_MODE_OUTPUT_PP
                                 LL:  LL_GPIO_MODE_OUTPUT

文件位置

文件	作用	优先级
common/define.cjs	全局映射表，适用于所有系列	低（被系列覆盖）
chip/{系列}/define.cjs	系列级映射，覆盖或补充全局映射	高

define.cjs 结构

// 三级映射：IP → 参数 → UI值 → { hal, ll, std }
exports.{IP名称} = {
  {参数名称}: {
    {UI值}: {
      hal: 'HAL库宏定义',
      ll:  'LL库宏定义',
      std: 'STD库宏定义'
    }
  }
}

每个 UI 值对应三个固件类型的宏，未使用的类型留空 ''。

实际示例

ADC

exports.ADC = {
  Resolution: {
    bit12: { hal: 'ADC_RESOLUTION_12B', ll: 'LL_ADC_RESOLUTION_12B' },
    bit10: { hal: 'ADC_RESOLUTION_10B', ll: 'LL_ADC_RESOLUTION_10B' }
  },
  DataAlign: {
    right: { hal: '', ll: '', std: 'ADC_DATAALIGN_RIGHT' },
    left:  { hal: '', ll: '', std: 'ADC_DATAALIGN_LEFT' }
  },
  ScanConvMode: {
    enable:  { hal: '', ll: '', std: 'ENABLE' },
    disable: { hal: '', ll: '', std: 'DISABLE' }
  },
  RegularChannel: {
    IN0: { hal: '', ll: '', std: 'ADC_CHANNEL_0' },
    IN1: { hal: '', ll: '', std: 'ADC_CHANNEL_1' }
  }
}

DMA

exports.DMA = {
  direction: {
    m2p: { hal: '', ll: '', std: 'DMA_MEMORY_TO_PERIPHERAL' },
    p2m: { hal: '', ll: '', std: 'DMA_PERIPHERAL_TO_MEMORY' }
  },
  priority: {
    Low:      { hal: '', ll: '', std: 'DMA_PRIORITY_LOW' },
    Medium:   { hal: '', ll: '', std: 'DMA_PRIORITY_MEDIUM' },
    High:     { hal: '', ll: '', std: 'DMA_PRIORITY_HIGH' },
    VeryHigh: { hal: '', ll: '', std: 'DMA_PRIORITY_ULTRA_HIGH' }
  },
  periph_inc: {
    Enable:  { hal: '', ll: '', std: 'DMA_PERIPH_INCREASE_ENABLE' },
    Disable: { hal: '', ll: '', std: 'DMA_PERIPH_INCREASE_DISABLE' }
  },
  channel: {
    DMA0_Channel0: { hal: '', ll: '', std: 'DMA_CH0' }
  }
}

SPI / I2C

exports.SPI = {
  BaudRatePrescaler: {
    div2: { hal: '', ll: '', std: 'SPI_PSC_2' },
    div4: { hal: '', ll: '', std: 'SPI_PSC_4' }
  },
  DataSize: {
    data_size_8:  { hal: '', ll: '', std: 'SPI_FRAMESIZE_8BIT' },
    data_size_16: { hal: '', ll: '', std: 'SPI_FRAMESIZE_16BIT' }
  }
}

exports.I2C = {
  AddressingMode: {
    bits7:  { hal: '', ll: '', std: 'I2C_ADDFORMAT_7BITS' },
    bits10: { hal: '', ll: '', std: 'I2C_ADDFORMAT_10BITS' }
  },
  NoStretchMode: {
    disable: { hal: '', ll: '', std: 'I2C_SCLSTRETCH_DISABLE' },
    enable:  { hal: '', ll: '', std: 'I2C_SCLSTRETCH_ENABLE' }
  }
}

映射调用流程

代码生成时，各外设的 pre.cjs 或 UI 函数通过 defineMap 获取映射：

// ips/DMA/ui/dma_gd32f103_base.cjs — DMA 参数映射
get_ip_dmas: (ip, defineMap) => {
  const firmware = ip.firmware.value   // 'std' | 'hal' | 'll'

  dma.def = {
    channel:    defineMap.DMA.channel[dma.channel][firmware],
    priority:   defineMap.DMA.priority[dma.priority][firmware],
    direction:  defineMap.DMA.direction[dma.direction][firmware],
    mode:       defineMap.DMA.mode[dma.mode][firmware],
    periph_inc: defineMap.DMA.periph_inc[dma.periph_inc][firmware],
    memory_inc: defineMap.DMA.memory_inc[dma.memory_inc][firmware]
  }
}

系列级覆盖

chip/{系列}/define.cjs 可覆盖 common/define.cjs 中的映射。例如 GD32F103 系列无需特殊映射（文件为空的 module.exports = {}），全部使用全局定义。

当需要差异时：

// chip/AT32F403/define.cjs — 仅写与全局不同的部分
module.exports = {
  ADC: {
    Resolution: {
      bit12: {
        hal: 'ADC_RESOLUTION_12B',
        ll:  'LL_ADC_RESOLUTION_12B',
        std: 'ADC_RESOLUTION_12B'    // AT32 的 STD 宏不同
      }
    }
  }
}

已覆盖的外设

common/define.cjs 当前覆盖的外设：

外设	参数数量	示例参数
ADC	20+	Resolution, DataAlign, ScanConvMode, RegularChannel, ExternalTrigConv...
DMA	15+	direction, priority, channel, mode, periph_inc, memory_inc, mem_data_alignment...
I2C	10+	AddressingMode, I2CSpeedMode, DutyCycle, GeneralCallMode, NoStretchMode...
I2S	8+	TransmissionMode, CommunicationStandard, ClockPolarity...
SPI	12+	BaudRatePrescaler, DataSize, CLKPolarity, CLKPhase, NSSMode...
LPTIM	2	ClockPrescaler, UpdateMode
RTC	（部分）	DataFormat, OutputSelection...

最佳实践

1. 通用优先：公共映射放 common/define.cjs，仅系列差异放 chip/{系列}/define.cjs
2. 三级完备：每个 UI 值尽量补全 hal / ll / std，暂不可用的留空
3. 键名一致：define.cjs 中的键名必须与 UI schema 中的 value 值完全一致