cd09 芯片平台与预编译库

cd09 是杰理 AC82N 通用 MCU SDK 所支持的芯片平台代号（对应 AC822B / AC823B / AC825A / AC826B 系列），本页介绍该平台的硬件特性、sdk/cpu/cd09 开源平台层、liba 目录下预编译静态库（.a）的组成与作用，以及 MaskROM 符号映射（maskrom_stubs.ld）这一平台特有的链接机制。

Purpose and Scope

本页覆盖 cd09 芯片平台本身相关的全部工程内容：

• cd09 平台对应的芯片型号、应用领域与核心硬件特性；
• sdk/cpu/cd09/liba/ 下预编译库（cpu.a、system.a、update.a、ump3_dec_lib.a、ui_platform.a、lib_speed_pitch.a）的职责划分；
• UBOOT 工程的预编译库（uboot.a、uboot_driver.a）；
• sdk/cpu/cd09/ 下的开源平台驱动（GPADC、GPIO、MCPWM、NorFlash、PAP、PLCNT、HADC、电源管理）与 MaskROM 链接脚本。

以下主题属于其他目录页，不在本页展开：

• GP MCU 应用工程（apps/gp_mcu）与各外设示例（cpu/demo）——见应用与示例相关页面；
• UBOOT 工程的完整编译/烧录流程——见 UBOOT 工程页面；
• 编译工具链与烧录工具的安装——见环境搭建页面。

概述

AC82N 系列是杰理科技推出的无蓝牙功能的通用 MCU SoC，面向高精度测量（体脂秤、血压计、耳温枪、精密仪器仪表）与低功耗产品（电池供电设备、便携仪器、RTC 闹钟唤醒应用）两大场景。其核心特性包括：

• 24 位高精度 HADC：有效精度最高可达 19 bit；
• 高速 SARADC：采样率可达 1 Msps；
• 超低功耗处理器与低功耗 RTC：支持闹钟与唤醒，适合电池供电；
• 丰富片上外设：HADC、SARADC、IIC、SPI、MCPWM、UART、USB、触摸按键等；
• 支持 APA 语音播报。

与常规 MCU SDK 不同，该 SDK 采用源码 + 预编译库混合交付模式：平台底层（CPU 核、系统服务、升级、MP3 解码、UI 平台、变速变调等）以 .a 静态库形式提供，必须配合对应命名规则的库文件编译；而外设驱动（GPADC、GPIO、MCPWM、NorFlash 等）与电源管理以开源 C 源码形式提供，方便开发者修改与裁剪。芯片启动时，MaskROM（固化在芯片内的只读程序）通过固定地址导出 ROM API，链接脚本 maskrom_stubs.ld 将这些符号映射到绝对地址，使应用与库可以直接调用 ROM 中的函数（如 memcpy、LZ4 解压、NorFlash 操作、cbuf 环形缓冲等），从而显著减小固件体积。

架构

下图展示了 cd09 平台的软件分层：应用层与预编译库层位于上层，开源平台驱动层位于中层，MaskROM / 硬件位于底层，UBOOT 工程与主 SDK 共享同一芯片平台。

flowchart TD
    subgraph sg_App["应用层"]
        GPApp["apps/gp_mcu 主应用"]
        Demos["cpu/demo 外设示例"]
    end

    subgraph sg_Libs["预编译库层 (sdk/cpu/cd09/liba)"]
        CPUA["cpu.a"]
        SYSA["system.a"]
        UPD["update.a"]
        MP3["ump3_dec_lib.a"]
        UIP["ui_platform.a"]
        SPP["lib_speed_pitch.a"]
    end

    subgraph sg_Uboot["UBOOT 工程 (include_lib/liba/cd09)"]
        UBA["uboot.a"]
        UBDA["uboot_driver.a"]
    end

    subgraph sg_Open["开源平台驱动层 (sdk/cpu/cd09)"]
        GPADC["gpadc.c"]
        GPIO["gpio_func.c / gpio_irq.c"]
        MCPWM["mcpwm.c"]
        NFL["norflash.c"]
        HADC["hadc/hadc_analog.c · hadc_digital.c"]
        PWR["power/power_app.c · power_config.c"]
        MISC["pap.c · plcnt.c"]
    end

    subgraph sg_ROM["MaskROM / 硬件层"]
        LD["maskrom_stubs.ld 符号映射"]
        ROM["MaskROM 固定地址 API"]
        HW[("AC822B/823B/825A/826B SoC")]
    end

    GPApp --> CPUA
    GPApp --> SYSA
    GPApp --> UPD
    GPApp --> MP3
    GPApp --> UIP
    GPApp --> SPP
    GPApp --> UBA
    CPUA --> GPADC
    CPUA --> GPIO
    CPUA --> MCPWM
    CPUA --> NFL
    CPUA --> HADC
    CPUA --> PWR
    CPUA --> MISC
    GPADC --> LD
    NFL --> LD
    PWR --> LD
    LD --> ROM
    ROM --> HW
    UBA --> HW

架构说明：

• 预编译库层是平台能力的主要载体：cpu.a 提供 CPU 核相关服务，system.a 提供系统服务（任务调度、内存、日志等），update.a 提供固件升级能力，ump3_dec_lib.a 提供 MP3 解码，ui_platform.a 提供 UI 平台支持，lib_speed_pitch.a 提供变速变调处理；UBOOT 工程的 uboot.a / uboot_driver.a 则为引导阶段提供驱动与启动逻辑。这些库以二进制形式交付，内部符号不随仓库公开。
• 开源平台驱动层弥补了二进制库与硬件之间的缝隙：外设驱动全部以 C 源码开放，开发者可以直接阅读、修改和裁剪；电源管理（power/）通过 power_param 配置低功耗行为。
• MaskROM 层是芯片固化的引导与基础服务程序。maskrom_stubs.ld 把 ROM 中函数的绝对地址绑定为链接器符号，使上层代码无需复制实现即可调用（如 memcpy、LZ4 解压、NorFlash MSFC 读写、cbuf 环形缓冲），既节省 Flash 空间又保证行为一致性。

平台硬件概览

cd09 平台承载了 AC82N 系列的全部 SoC 型号。根据 README.md 的说明，该平台的芯片矩阵如下：

这些芯片均为无蓝牙的通用 MCU SoC，SDK 定位"通用 MCU"（GP-MCU），因此工程结构围绕外设驱动、低功耗与测量类应用展开，而非无线连接类应用。平台的关键硬件资源决定了上层软件的设计取舍：

• HADC（高精度 ADC）：24 位 Σ-Δ 架构，有效精度最高 19 bit，用于体脂秤、血压计、耳温枪等测量场景；对应开源驱动 hadc/hadc_analog.c 与 hadc/hadc_digital.c。
• SARADC：1 Msps 高速采样，用于普通模拟量采集；对应 gpadc.c。
• 低功耗 RTC：支持闹钟唤醒，电池供电产品的常开外设；与 power/ 电源管理配合实现深度休眠。
• MCPWM / UART / IIC / SPI / USB / 触摸按键：丰富的片上外设，分别由 mcpwm.c、gpio_func.c、gpio_irq.c 等开源驱动支撑。

预编译库清单

所有预编译库以 .a（静态库）形式存放于 sdk/cpu/cd09/liba/，UBOOT 工程的库位于 sdk/UBOOT工程/include_lib/liba/cd09/。由于这些库以二进制交付，仓库中不包含其源码，以下职责说明依据库命名、SDK 整体架构与 README 描述整理：

使用约束：README 明确指出"需配合对应命名规则的库文件 (lib.a) 进行编译"——即库文件与 SDK 版本、芯片型号必须严格匹配，混用不同版本的预编译库可能导致链接失败或运行时行为异常（详见"故障模式与注意事项"章节）。

MaskROM 符号映射：maskrom_stubs.ld

maskrom_stubs.ld 是 cd09 平台最独特的工程文件：它不是普通的链接脚本，而是将 MaskROM（芯片出厂固化的只读程序）中函数的绝对地址绑定为链接器全局符号的"符号表"。上层代码引用这些符号时，链接器直接填入 ROM 地址，函数体不占 Flash 空间。

脚本内容示例（节选）：

  __local_irq_enable = ABSOLUTE(0x3f43f00);
  __local_irq_disable = ABSOLUTE(0x3f43f04);
  request_irq_rom = ABSOLUTE(0x3f43f08);
  memcpy = ABSOLUTE(0x3f43f28);
  memmove = ABSOLUTE(0x3f43f2c);
  memset = ABSOLUTE(0x3f43f34);
  ic_pll_init = ABSOLUTE(0x3f43f4c);
  sfc_suspend = ABSOLUTE(0x3f43f50);
  sfc_resume = ABSOLUTE(0x3f43f54);
  LZ4_decompress_safe_continue = ABSOLUTE(0x3f43fa4);
  msfc_norflash_erase = ABSOLUTE(0x3f43fcc);
  msfc_norflash_write = ABSOLUTE(0x3f43fd0);
  msfc_norflash_read = ABSOLUTE(0x3f43fd4);
  cbuf_read = ABSOLUTE(0x3f43fd8);
  cbuf_write = ABSOLUTE(0x3f43fdc);
  cbuf_init = ABSOLUTE(0x3f43ff4);

Source: maskrom_stubs.ld

设计意图：把标准库函数（memcpy/memset/strcmp 等）、压缩解压（LZ4）、Flash 操作（MSFC NorFlash 读写擦除）、环形缓冲（cbuf）与 ICU 缓存控制等高频/基础能力固化在 ROM 中，SDK 通过绝对地址直接复用。这样既避免在每个固件中重复携带这些代码（节省 Flash），又保证不同固件版本之间基础行为一致。

脚本中还可看到平台的内存布局常量：

开发者应将这些地址视为只读平台契约：它们由芯片 MaskROM 版本决定，不应在应用代码中改动或重新分配。

开源平台驱动层

sdk/cpu/cd09/ 下的 C 源码是平台对外设的完整开源实现，也是开发者最常修改的部分：

这些驱动与预编译库的分工遵循"库管核、源码管外设"的原则：CPU 核、系统服务等难以裁剪且必须与芯片版本强一致的部分以二进制交付；外设驱动则需要按产品硬件裁剪（如复用引脚、调整采样通道），因此开放源码。开发者修改外设驱动时，仍通过 MaskROM 符号（如 msfc_norflash_*、cbuf_*）调用底层 ROM 服务，从而保持与预编译库的兼容。

电源管理接口

cd09 平台的电源管理以"接口头文件 + 应用实现 + 配置 + 校准"四部分组织。公共接口定义在 power_api.h，对外只暴露一个全局配置对象：

#ifndef ___POWER_API_H___
#define ___POWER_API_H___

extern const struct low_power_param power_param;

#endif

Source: power_api.h

设计意图：power_api.h 刻意保持极简——仅声明 power_param，不暴露任何函数原型。低功耗的完整流程（进入/退出低功耗、唤醒源配置、时钟切换）由 power_app.c 实现，参数由 power_config.c 提供，校准逻辑在 power_trim.c。这种"接口最小化"设计让上层（应用与预编译库）只依赖一个常量结构体即可驱动整个电源管理模块，具体实现细节可随芯片版本演进而自由修改。

配置项（struct low_power_param，定义于 power_app.c / power_config.c）：

核心流程

启动流程

芯片上电后依次经历 MaskROM → UBOOT → 主应用三个阶段，预编译库在不同阶段各司其职：

sequenceDiagram
    participant HW as SoC (AC822B/823B/825A/826B)
    participant ROM as MaskROM (固化程序)
    participant UBOOT as uboot.a + uboot_driver.a
    participant APP as cpu.a + system.a + update.a
    participant FLASH as NorFlash (MSFC)

    HW->>ROM: 上电复位，进入 MaskROM
    ROM->>ROM: mask_init / 时钟初始化 (ic_pll_init)
    ROM->>FLASH: msfc_norflash_init 读取引导数据
    ROM->>UBOOT: 加载并跳转 UBOOT
    UBOOT->>FLASH: 读取主固件 (msfc_norflash_read)
    UBOOT->>APP: 跳转主应用入口
    APP->>APP: system.a 初始化系统服务
    APP->>ROM: 经 maskrom_stubs.ld 调用 ROM API
    APP->>FLASH: update.a 提供升级能力 (如需)

流程要点：

1. MaskROM 阶段：芯片上电后运行固化程序，mask_init 完成基础初始化，并通过 MSFC 接口（msfc_norflash_init 等）从 NorFlash 读取引导信息。
2. UBOOT 阶段：uboot.a 与 uboot_driver.a 提供引导逻辑与基础驱动，负责把主固件从 Flash 读入 RAM 并跳转。UBOOT 的库与主 SDK 的库分开存放（sdk/UBOOT工程/include_lib/liba/cd09/），二者独立编译、通过约定的入口衔接。
3. 主应用阶段：cpu.a 提供 CPU 核服务，system.a 提供系统服务；应用与库通过 maskrom_stubs.ld 映射的绝对地址直接调用 ROM 函数，避免重复实现。

编译链接流程

预编译库在链接阶段被静态链接进固件，同时 maskrom_stubs.ld 负责解析 ROM 符号：

flowchart LR
    SRC["应用源码 (.c/.h)"] --> CC["杰理 clang 工具链<br/>(pi32)"]
    LIBA["cd09 预编译库 (.a)"] --> LD["链接器"]
    LD["链接器"] --> LDS["maskrom_stubs.ld<br/>ROM 绝对地址符号"]
    CC --> LD
    LD --> FW["固件镜像 (含升级头)"]
    FW --> BURN["USB 升级工具 / 生产烧写工具"]

编译环境要求（来自 README.md）：Windows 推荐 Code::Blocks IDE，Linux 支持 Makefile 命令行；工具链为杰理自研 pi32 架构的 clang（Linux 下解压到 /opt/jieli，需存在 /opt/jieli/pi32/bin/clang）。

使用示例

示例 1：验证工具链安装（编译前置条件）

# 验证工具链是否安装成功
clang --version

Source: README.md

示例 2：链接脚本中的 ROM 符号绑定

以下节选展示 maskrom_stubs.ld 如何将中断开关、缓存控制与标准库函数绑定到 MaskROM 绝对地址，这是平台库与应用能够"零成本"复用 ROM 服务的关键机制：

  __local_irq_enable = ABSOLUTE(0x3f43f00);
  __local_irq_disable = ABSOLUTE(0x3f43f04);
  request_irq_rom = ABSOLUTE(0x3f43f08);
  memcpy = ABSOLUTE(0x3f43f28);
  memset = ABSOLUTE(0x3f43f34);
  ic_pll_init = ABSOLUTE(0x3f43f4c);
  IcuFlushinvAll = ABSOLUTE(0x3f43f74);
  LZ4_decompress_safe_continue = ABSOLUTE(0x3f43fa4);
  msfc_norflash_read = ABSOLUTE(0x3f43fd4);
  cbuf_init = ABSOLUTE(0x3f43ff4);

Source: maskrom_stubs.ld

示例 3：低功耗配置对象声明

power_api.h 是平台唯一对外公开的电源接口，上层只需引用 power_param 即可参与低功耗配置：

extern const struct low_power_param power_param;

Source: power_api.h

配置选项

说明：struct low_power_param 的字段定义位于 power_app.c/power_config.c，本页未逐一读取其成员（源码预算限制）；实际字段（如唤醒源、休眠模式、时钟策略）以 power_config.c 为准。

API 参考：MaskROM 导出符号

maskrom_stubs.ld 导出的符号即 cd09 平台的"ROM API"。按功能分组如下（地址取自 maskrom_stubs.ld）：

中断与时钟

P33 端口操作

标准库函数

memcpy（0x3f43f28）、memmove（0x3f43f2c）、memcmp（0x3f43f30）、memset（0x3f43f34）、strcmp（0x3f43f38）、strlen（0x3f43f3c）、strchr（0x3f43f40）、__iumoddi3（0x3f43f44）、__divdf3（0x3f43f48）。这些符号在链接时被解析为 ROM 地址，应用无需链接 libc 中对应实现。

Flash / SFC / MSFC 存储

压缩解压与环形缓冲

缓存（ICU）与杂项

注意：这些是地址绑定符号而非函数声明——调用时需按各模块头文件中的原型使用；本仓库未提供 ROM API 的完整头文件，具体原型需查阅杰理文档中心或 SDK 内对应模块头文件。

故障模式与注意事项

1. 预编译库与 SDK 版本不匹配：.a 库必须与 SDK 版本、芯片型号严格匹配（README 明确要求"配合对应命名规则的库文件进行编译"）。混用会导致链接错误（符号缺失/重复）或运行时崩溃，升级 SDK 时务必同步替换 liba 目录。
2. MaskROM 地址不可变：maskrom_stubs.ld 中的绝对地址由芯片固化程序决定，不同芯片版本（或 MaskROM 版本）可能不同。切勿修改这些地址或在应用代码中占用 0x3f43f00 附近区间。
3. 二进制库缺乏符号可见性：cpu.a、system.a 等为闭源交付，无法在仓库内查看内部实现；排查问题时需依赖文档中心、日志输出与公开头文件，而非源码调试。
4. 平台驱动与 ROM 服务耦合：开源驱动（如 norflash.c）依赖 ROM 的 MSFC 接口，修改驱动时需保持与 ROM API 的调用约定一致（如 4 字节地址模式切换 msfc_norflash_enter_4byte_addr）。
5. 工具链版本敏感：编译需使用杰理 pi32 clang 工具链（Linux 路径 /opt/jieli/pi32/bin/clang），GCC 等通用工具链无法正确编译/链接该平台（涉及特殊链接脚本与 ROM 符号）。

性能与运维要点

• Flash 空间优化：标准库、LZ4 解压、cbuf、MSFC 等高频基础能力复用 ROM，固件体积显著减小，这是平台采用"预编译库 + ROM 符号映射"的根本动机。
• 缓存一致性：sfc_drop_cache、IcuFlushinvAll 等 ROM API 用于保证 Flash 读取与 CPU 缓存的一致性；在低功耗休眠前后需正确调用 sfc_suspend/sfc_resume 与 Flash 电源控制，避免休眠唤醒后 Flash 访问异常。
• 低功耗调优：power_trim.c 提供校准入口，量产时应在产线完成低功耗参数校准；RTC 闹钟唤醒是低功耗产品的关键路径，配置 power_param 时应核对唤醒源与时钟策略。
• 升级流程：update.a 提供升级能力，与 USB 升级工具/生产烧写工具配合；升级固件需要正确的升级头与版本匹配，参见升级工具文档。

扩展点

• 开源外设驱动：gpadc.c、gpio_*、mcpwm.c、hadc/* 等为完整源码，可按产品硬件自由裁剪与扩展（如新增采样通道、复用 GPIO 功能）。
• 电源管理策略：通过 power_config.c 调整低功耗参数、在 power_app.c 中扩展休眠/唤醒流程。
• UBOOT 阶段：UBOOT 工程独立于主 SDK 编译，uboot_driver.a 与 uboot.a 之间的接口决定了引导流程的可定制边界。
• 预编译库不可扩展：cpu.a/system.a/ump3_dec_lib.a 等为闭源二进制，不支持二次开发；需要平台级能力变更时应通过杰理官方渠道申请，而不是修改二进制。

测试与验证建议

仓库中未包含针对 cd09 平台库的单元测试源码（预编译库为闭源）。建议的验证方式：

• 使用 cpu/demo 下的外设示例（HADC、GPADC、UART、SPI、IIC、MCPWM、RTC、GPTimer）验证开源驱动与预编译库的协同工作；
• 通过升级工具验证 update.a 的升级链路；
• 使用低功耗示例验证 RTC 唤醒与 power_param 配置的正确性。

相关链接

• README.md（平台与芯片型号说明）
• maskrom_stubs.ld（MaskROM 符号映射）
• power_api.h（低功耗接口）
• cd09 预编译库目录
• UBOOT 工程预编译库目录
• 环境搭建与烧录升级：见文档中心 AC82 系列文档