芯片驱动与板级适配

AC792N SDK 的板级适配（Board Support）与芯片配置体系：通过 board_config.h 统一入口聚合芯片级存储配置（chip_cfg.h）与板卡外设配置（board_*.h），并以 board/wl83 板卡目录为模板在各演示工程间复用，实现"芯片能力"与"板卡外设"的解耦与可裁剪。

Purpose and Scope

本页面向 AC792N 固件 SDK 的芯片驱动与板级适配层，覆盖以下内容：

• 板级配置的层次结构与统一入口 board_config.h 的聚合机制；
• 芯片级存储配置 chip_cfg.h（Flash / SDRAM 容量）及其作用；
• 板卡外设配置 board_demo.h（引脚与外围器件配置）的角色；
• board.c 板级初始化实现文件与构建集成（Makefile / .cbp）；
• CONFIG_NO_SDRAM_ENABLE 的自动推导逻辑与 SDRAM 边界处理；
• 同一 wl83 板卡在多个演示工程间的复用方式与新增板卡的扩展路径。

以下内容不在本页展开，属于其他目录项：

• 具体外设驱动（UART、SPI、I2C、LCD、USB 等）的寄存器级实现细节；
• 应用层业务逻辑、协议栈（BLE/WiFi）行为；
• 量产、烧录与工具链相关说明。

Overview

AC792N 是杰理科技（Jieli）面向无线音频/物联网场景的 SoC 芯片。SDK 采用芯片驱动 + 板级适配分层设计：芯片本身的能力（内置 Flash/SDRAM 容量、型号相关参数）与具体板卡的差异（引脚复用、外设接法）被拆分为两个正交的配置维度，再由板级入口统一聚合。

在 sdk/apps/demo/demo_ble/board/wl83/ 目录中可以看到这套机制的完整落地：

• chip_cfg.h —— 芯片级参数，仅声明 Flash 与 SDRAM 容量（当前为 1MB Flash + 2MB SDRAM）；
• board_demo.h —— 板卡外设配置，描述 wl83 板卡上各外设的引脚/资源分配；
• board_config.h —— 板级配置入口，通过 #define CONFIG_BOARD_DEMO 选定板卡型号，再按顺序包含上述两个文件，并负责 SDRAM 边界条件推导；
• board.c —— 板级初始化的具体实现；
• Makefile 与 .cbp（Code::Blocks 工程）—— 将板级配置挂载进构建系统。

该目录结构被多个演示工程复制使用：demo_ble、demo_hello、demo_ui、demo_wifi、demo_wifi_ext、wifi_bbm、wifi_camera、wifi_soundbox 都各自维护一份 board/wl83。这体现了板级适配层的设计意图：同一硬件板卡可以被不同应用工程独立裁剪与演进，互不干扰。

此外，sdk/apps/common/lcd/include/lcd_board_cfg_template.h 提供了 LCD 板卡配置的模板头文件，说明 SDK 中"板卡配置模板化"是一种通用做法——外设接入新的板卡时，可以模板为起点按需修改。

Architecture

下图展示了 AC792N SDK 中应用层、板级适配层与芯片驱动层之间的依赖关系：

flowchart TD
    subgraph sg_Apps["应用层 (sdk/apps)"]
        DemoBLE["demo_ble"]
        DemoUI["demo_ui"]
        DemoWifi["demo_wifi"]
        WifiCam["wifi_camera"]
        WifiSoundbox["wifi_soundbox"]
    end

    subgraph sg_Board["板级适配层 (board/wl83)"]
        BoardCfg["board_config.h<br/>(板级入口)"]
        ChipCfg["chip_cfg.h<br/>(芯片存储配置)"]
        BoardDemo["board_demo.h<br/>(板卡外设配置)"]
        BoardC["board.c<br/>(板级初始化)"]
        Makefile["Makefile / .cbp<br/>(构建挂载)"]
    end

    subgraph sg_Driver["芯片驱动层 (芯片外设)"]
        Drivers["外设驱动<br/>(flash / sdram / io / uart / lcd ...)"]
    end

    DemoBLE --> BoardCfg
    DemoUI --> BoardCfg
    DemoWifi --> BoardCfg
    WifiCam --> BoardCfg
    WifiSoundbox --> BoardCfg
    BoardCfg --> ChipCfg
    BoardCfg --> BoardDemo
    BoardC --> BoardCfg
    Makefile --> BoardCfg
    BoardDemo --> Drivers
    ChipCfg --> Drivers

架构要点说明：

• 应用层 → 板级适配层：每个应用工程通过自己目录下的 board_config.h 获得板级能力，应用代码不直接触碰芯片参数，保证应用可移植性。
• 板级入口聚合：board_config.h 同时包含 chip_cfg.h 与 board_demo.h，把"芯片能提供什么"与"板卡接了什么"绑定为一个整体，供 board.c 与驱动层使用。
• 板卡目录可复制：wl83 目录作为一个完整的"板卡包"，可以被整体复制为 board/<新板名>/ 后修改，这是 SDK 扩展新板卡的标准路径。
• 驱动层消费配置：芯片外设驱动依据 chip_cfg.h 中的容量信息决定内存布局（如是否启用 SDRAM），依据 board_demo.h 中的引脚配置完成 pinmux 与外设注册。

板级配置层次结构

板级适配层从入口到实现共分为四个文件，职责严格分离：

这种"入口 / 芯片 / 板卡 / 实现"四分离的结构，使得同一芯片可以快速适配多种板卡，同一板卡也可以平滑迁移到不同芯片（仅需替换 chip_cfg.h），这正是板级适配层存在的核心价值。

核心实现分析

1. board_config.h — 板级统一入口

board_config.h 是整个板级适配层的"总开关"文件，全文仅 24 行，承担三个职责：

#ifndef BOARD_CONFIG_H
#define BOARD_CONFIG_H

//板子型号
#define CONFIG_BOARD_DEMO

//芯片型号sdram和flash配置文件
#include "chip_cfg.h"

//不同板子外设配置文件，如有新的板子，在这里同理添加
#include "board_demo.h"

#ifdef CONFIG_NO_SDRAM_ENABLE
#undef  __SDRAM_SIZE__
#define __SDRAM_SIZE__    0
#else
#if (__SDRAM_SIZE__ == 0)
#ifndef CONFIG_NO_SDRAM_ENABLE
#define CONFIG_NO_SDRAM_ENABLE
#endif
#endif
#endif

#endif

Source: board_config.h

职责一：板卡型号选择。 #define CONFIG_BOARD_DEMO 声明当前编译的板卡型号宏。SDK 约定不同的板卡定义不同的型号宏（如 CONFIG_BOARD_XXX），后续代码可以通过该宏做条件编译，选择对应的外设配置分支。这是典型的"编译期配置"（compile-time configuration）设计——板卡差异在编译期就已固化，运行期零开销。

职责二：聚合芯片与板卡配置。 依次包含 chip_cfg.h 与 board_demo.h。头文件注释明确说明了设计意图："芯片型号 sdram 和 flash 配置文件"与"不同板子外设配置文件，如有新的板子，在这里同理添加"。即扩展新板卡的标准动作就是：新建 board_<板名>.h，然后在 board_config.h 中添加对应的 #include——SDK 通过注释把扩展约定直接写进了代码。

职责三：SDRAM 边界推导。 见下文"3. SDRAM 配置推导逻辑"。

2. chip_cfg.h — 芯片级存储配置

chip_cfg.h 是芯片型号相关的核心参数文件，当前 wl83 板卡的配置为：

#ifndef CONFIG_CHIP_CFG_H
#define CONFIG_CHIP_CFG_H

#define __FLASH_SIZE__    (1 * 1024 * 1024)
#define __SDRAM_SIZE__    (2 * 1024 * 1024)

#endif

Source: chip_cfg.h

这两个宏决定了芯片内存子系统的布局：

• __FLASH_SIZE__（1MB）：芯片内置/外挂 Flash 容量，驱动层据此计算固件分区、OTA 区域等；
• __SDRAM_SIZE__（2MB）：SDRAM 容量，决定系统能否启用 SDRAM 作为大块内存池（如用于 LCD 显存、音频缓冲）。

设计意图：把"容量"这类芯片级参数与"引脚"这类板卡级参数分离，是因为同一颗芯片可能配不同容量的存储颗粒，而同一板卡可能更换芯片封装——两个维度独立变化，分开配置才能最小化改动面。demo_hello、demo_ui、demo_wifi、demo_wifi_ext、wifi_bbm、wifi_camera、wifi_soundbox 各工程下的 chip_cfg.h 均采用同名同结构，证实这是一套全 SDK 统一的配置契约。

3. SDRAM 配置推导逻辑（边界条件处理）

board_config.h 中的预处理逻辑实现了 SDRAM 配置的自动归一化：

flowchart TD
    Start["进入 board_config.h"] --> Check{"CONFIG_NO_SDRAM_ENABLE<br/>已定义?"}
    Check -->|"是"| Force0["强制 __SDRAM_SIZE__ = 0<br/>(#undef 后重定义)"]
    Check -->|"否"| CheckSize{"__SDRAM_SIZE__ == 0 ?"}
    CheckSize -->|"是"| DefineNo["定义 CONFIG_NO_SDRAM_ENABLE<br/>(与 SDRAM 容量 0 保持一致)"]
    CheckSize -->|"否"| Keep["保持 SDRAM 配置不变"]
    Force0 --> End(["配置完成"])
    DefineNo --> End
    Keep --> End

该逻辑的精妙之处在于双向一致性：无论用户是从"容量"维度（__SDRAM_SIZE__ = 0）还是从"使能开关"维度（CONFIG_NO_SDRAM_ENABLE）声明无 SDRAM，最终都会收敛到同一组宏状态。这样驱动层只需检查 CONFIG_NO_SDRAM_ENABLE 一个宏即可，避免了多个宏组合带来的组合爆炸与不一致风险。#undef + 重定义的手法则保证用户即使在外层（如 Makefile）预定义了 SDRAM 容量，只要声明了 CONFIG_NO_SDRAM_ENABLE，容量也一定会被清零，杜绝"声明无 SDRAM 却仍按 2MB 布局内存"的隐患。

4. board_demo.h — 板卡外设配置

board_demo.h 是 wl83 板卡的外设配置清单，由 board_config.h 无条件包含。其典型内容是：各外设（UART、SPI、I2C、GPIO、PWM、LCD 等）使用的引脚编号、功能复用选择、外设使能宏等。由于本页示例配置未展开其内部细节，读者可直接查阅源文件：

Source: board_demo.h

值得注意的是，SDK 同时提供了外设板卡配置的模板：lcd_board_cfg_template.h。模板化配置的用意是：LCD 这类外设的板卡差异大（分辨率、接口时序、背光引脚各不相同），提供模板可确保各板卡配置项齐全、命名统一，减少漏配导致的硬件调试成本。

5. board.c 与构建集成

board.c 位于同一板卡目录，负责板级初始化的运行时实现（外设时钟、IO 复用、外设使能等），其具体函数清单以源文件为准：

Source: board.c

板卡目录还包含两个构建文件，构成板级适配的构建集成：

• Makefile —— 编译规则，将本目录的头文件路径加入编译搜索路径，确保各源文件能找到 board_config.h；
• AC792N_DEMO_DEMO_BLE.cbp —— Code::Blocks 工程文件，为 IDE 用户提供同样的工程配置。

Sources:

• Makefile
• AC792N_DEMO_DEMO_BLE.cbp

6. 多 Demo 板级复用（wl83）

wl83 板卡目录被以下 8 个工程各自复制维护，构成板级适配层在 SDK 中的典型复用形态：

设计意图分析：复制而非共享。虽然各工程面向同一块 wl83 硬件，但每个应用对资源的占用不同（如 wifi_camera 需要大显存，demo_hello 可能完全不需要 SDRAM），复制目录允许各工程独立裁剪 chip_cfg.h 的容量宏与 board_demo.h 的外设清单，避免"一处修改、全局受影响"的耦合问题。代价是配置存在多份拷贝，若硬件改版需要各工程同步更新——这是 SDK 在"工程独立性"与"配置单一性"之间做出的明确取舍。

核心流程

板级适配的完整生命周期分为编译期配置与运行期初始化两个阶段：

sequenceDiagram
    participant Dev as 开发者/构建系统
    participant M as Makefile/.cbp
    participant B as board_config.h
    participant C as chip_cfg.h
    participant D as board_demo.h
    participant BC as board.c
    participant DRV as 芯片外设驱动

    Note over Dev,DRV: 编译期
    Dev->>M: 选择工程 (如 demo_ble) 执行构建
    M->>B: 编译时包含板级入口
    B->>C: 读取 Flash/SDRAM 容量宏
    B->>D: 读取板卡外设配置
    B->>B: 推导 CONFIG_NO_SDRAM_ENABLE<br/>(双向一致性归一)
    Note over Dev,DRV: 运行期
    DRV->>BC: 芯片启动后调用板级初始化
    BC->>B: 读取归一化后的配置
    BC->>DRV: 按容量配置内存/存储子系统
    BC->>D: 按引脚配置完成 pinmux 与外设注册
    DRV-->>BC: 外设就绪

流程关键点：

1. 编译期：构建系统（Makefile / .cbp）将板卡目录纳入编译，board_config.h 作为入口被所有源文件包含；chip_cfg.h 与 board_demo.h 的宏在预处理阶段被展开，CONFIG_NO_SDRAM_ENABLE 在此时完成归一化推导——所有配置决策在编译期定格。
2. 运行期：芯片上电启动后，board.c 读取归一化后的宏，完成内存布局（是否启用 SDRAM）与外设初始化（依据 board_demo.h 的引脚分配），最终交付给芯片外设驱动使用。
3. 解耦价值：应用层代码全程只依赖 board_config.h 暴露的宏接口，既不关心芯片具体容量，也不关心板卡引脚细节，因此同一份应用代码可以不加修改地跑在不同板卡上——这正是板级适配层存在的根本原因。

使用示例

示例一：板级配置入口（全量）

这是 demo_ble 工程 wl83 板卡 board_config.h 的完整内容，展示了板级适配入口的标准写法——选定板卡型号、包含芯片配置与板卡外设配置、处理 SDRAM 边界：

#ifndef BOARD_CONFIG_H
#define BOARD_CONFIG_H

//板子型号
#define CONFIG_BOARD_DEMO

//芯片型号sdram和flash配置文件
#include "chip_cfg.h"

//不同板子外设配置文件，如有新的板子，在这里同理添加
#include "board_demo.h"

#ifdef CONFIG_NO_SDRAM_ENABLE
#undef  __SDRAM_SIZE__
#define __SDRAM_SIZE__    0
#else
#if (__SDRAM_SIZE__ == 0)
#ifndef CONFIG_NO_SDRAM_ENABLE
#define CONFIG_NO_SDRAM_ENABLE
#endif
#endif
#endif

#endif

Source: board_config.h

使用要点：新增板卡时，不要修改 chip_cfg.h 的容量宏来"假装"没有 SDRAM，而应显式定义 CONFIG_NO_SDRAM_ENABLE；反之若 SDRAM 容量写为 0，系统会自动定义该宏——两条路径殊途同归，驱动层只需检查单一宏。

示例二：芯片级存储容量配置

#ifndef CONFIG_CHIP_CFG_H
#define CONFIG_CHIP_CFG_H

#define __FLASH_SIZE__    (1 * 1024 * 1024)
#define __SDRAM_SIZE__    (2 * 1024 * 1024)

#endif

Source: chip_cfg.h

使用要点：容量以字节为单位、用宏表达式书写（而非裸数字），便于按 KB/MB 直观换算；更换存储颗粒或芯片封装时，只需同步修改这两个宏，板卡外设配置完全不受影响。

示例三：LCD 板卡配置模板（外设配置模板化）

SDK 将 LCD 这类差异大的外设板卡配置抽象为模板头文件，新板卡可复制后按需修改：

// 模板路径：sdk/apps/common/lcd/include/lcd_board_cfg_template.h
// 用途：作为 LCD 板卡配置的统一起点，保证各板卡配置项齐全、命名一致

Source: lcd_board_cfg_template.h

设计意图：LCD 外设的板卡差异点集中在分辨率、接口时序与背光/复位引脚上，模板化可强制新板卡补齐全部配置项，从源头避免"漏配一个引脚导致屏幕不亮"这类高成本硬件调试问题。

配置选项

板级适配层通过编译期宏进行配置，全部在预处理阶段生效：

配置约束：

• CONFIG_NO_SDRAM_ENABLE 与 __SDRAM_SIZE__ 必须保持一致，board_config.h 的预处理逻辑会自动归一化，但显式声明仍是推荐做法（可读性更好）；
• 容量宏的取值必须与芯片实际封装匹配——配置过大将导致驱动按不存在的内存布局寻址，配置过小则浪费可用资源。

API 参考（板级适配接口）

板级适配层以头文件宏契约而非运行时 API 的形式对外提供服务，其"接口面"如下：

board_config.h — 板级配置入口（无条件包含）

• 用途：所有需要板级信息的源文件通过包含本头文件获得 __FLASH_SIZE__、__SDRAM_SIZE__、CONFIG_NO_SDRAM_ENABLE 等宏；
• 包含链：board_config.h → chip_cfg.h（芯片容量） + board_demo.h（外设配置）；
• 副作用：包含后可能定义 CONFIG_NO_SDRAM_ENABLE（当 __SDRAM_SIZE__ == 0 时）。

chip_cfg.h — 芯片容量契约

• 输出宏：__FLASH_SIZE__、__SDRAM_SIZE__；
• 约束：全 SDK 各工程同名同结构，作为统一的芯片参数契约，驱动层可放心依赖。

board_demo.h — 板卡外设契约

• 输出：板卡外设使能宏与引脚配置；
• 约束：由 board_config.h 无条件包含，引脚分配须与芯片 pinmux 能力匹配。

board.c — 板级初始化实现

• 用途：运行期完成外设时钟、IO 复用与外围器件初始化；
• 调用时机：芯片启动流程中由系统引导调用（具体入口函数名以 board.c 源文件为准）。

说明：板级适配层为编译期宏体系，无传统意义的运行时异常抛出；其"错误"体现为编译告警、链接失败或运行期外设行为异常，详见下一节。

专业注意点

失败模式与边界情况

板级适配层以编译期宏为核心，其"故障"大多在编译或启动阶段暴露：

1. SDRAM 配置不一致：若 CONFIG_NO_SDRAM_ENABLE 已定义但 __SDRAM_SIZE__ 非零（如外层 Makefile 覆盖），board_config.h 通过 #undef 强制清零，保证不会出现"声称无 SDRAM 却按 2MB 布局"的内存越界；反之若容量为 0 而未定义该宏，系统自动补定义。边界情况已由入口文件兜底，但依赖该兜底会降低代码可读性，显式声明更佳。
2. 容量宏与实际封装不匹配：__FLASH_SIZE__ 偏大可能导致链接器产出超尺寸固件或驱动访问不存在的存储区域；偏小则固件可能放不下。这类错误通常在链接阶段（region overflow）或首轮启动时暴露，定位成本较高，应在板卡 bring-up 时优先核对。
3. 板卡外设配置与芯片 pinmux 冲突：board_demo.h 中多个外设复用了同一引脚时，驱动层初始化顺序将决定实际功能，表现为"某个外设莫名失效"。排查时应逐一核对引脚复用表。
4. 多工程配置漂移：wl83 目录在 8 个工程中各有一份拷贝，硬件改版后若未同步更新所有工程，会出现"同一块板卡、不同工程行为不一致"的现象——这是复制式板卡复用的固有代价，改版时需建立同步清单。

并发与一致性

• 板级配置全部在编译期固化，运行期无动态配置，因此不存在运行期并发读写配置的问题；
• 运行期唯一的一致性关注点在启动阶段：board.c 完成外设初始化前，依赖对应外设的中断/任务不应被调度——启动时序由系统引导代码保证，板级适配层只需保证初始化函数的幂等性与顺序正确性。

性能与运维

• 零运行时开销：宏在预处理阶段展开，板级适配层对运行期性能无任何额外成本——这是选择编译期配置而非运行时配置表的关键原因；
• 编译期快速反馈：配置错误多数在编译/链接阶段即可发现，比运行时配置更早暴露问题，降低硬件调试成本；
• 构建侧：Makefile 与 .cbp 双轨并存，命令行与 IDE 用户都能获得一致的板级配置；维护时应保持两者头文件路径同步，否则会出现"命令行能编、IDE 编不过"的割裂。

扩展点：新增板卡的标准路径

SDK 在 board_config.h 注释中明确给出了扩展约定（"如有新的板子，在这里同理添加"），完整流程如下：

flowchart TD
    Start["新增板卡需求"] --> Step1["复制 board/wl83 为 board/<新板名>/"]
    Step1 --> Step2["修改 chip_cfg.h<br/>(核对 Flash/SDRAM 容量)"]
    Step2 --> Step3["新建 board_&lt;新板名&gt;.h<br/>(按外设模板配置引脚)"]
    Step3 --> Step4["修改 board_config.h<br/>定义 CONFIG_BOARD_XXX 并包含新配置"]
    Step4 --> Step5["按需实现 board.c 初始化"]
    Step5 --> Step6["同步 Makefile 与 .cbp 路径"]
    Step6 --> Done["编译验证 + 硬件 bring-up"]

外设级扩展可参考 lcd_board_cfg_template.h 的模板化做法，为同类外设建立统一配置模板，降低新板卡适配成本。

测试覆盖

• 板级适配层本身以头文件宏为主，SDK 未提供针对该层的独立单元测试（属于编译期静态配置，验证手段是各 demo 工程的成功编译与板卡 bring-up 实测）；
• 实际的质量保障来自多工程复用：同一份 board_config.h 逻辑在 8 个工程中被反复编译验证，SDRAM 归一化、容量宏等逻辑的 bug 会在任一工程上暴露，相当于隐式的交叉验证；
• 新增板卡时应至少在最小工程（demo_hello）上完成首次 bring-up，再移植到功能完整的工程（如 wifi_camera），以隔离板级问题与应用问题。

相关链接

• demo_ble 板卡目录 board_config.h — 板级配置入口（本文主要分析对象）
• demo_ble 板卡目录 chip_cfg.h — 芯片 Flash/SDRAM 容量配置
• demo_ble 板卡目录 board_demo.h — 板卡外设配置
• demo_ble 板卡目录 board.c — 板级初始化实现
• LCD 板卡配置模板 lcd_board_cfg_template.h — 外设板卡配置模板化示例
• 其他工程的 wl83 板卡配置（同构复用）：demo_hello/chip_cfg.h、demo_ui/chip_cfg.h、wifi_camera/chip_cfg.h
• 相关目录项：芯片外设驱动细节（UART/SPI/LCD/USB 驱动实现）请参见对应外设驱动目录项；各应用工程的业务行为请参见各 demo 目录项。