文档与版本资源

AC792N_AIoT_SDK 的文档资源体系与版本管理机制总览：涵盖仓库内各级 README 文档、在线文档中心与硬件资料引用、运行时版本上报（sdk_version() / app_version_check()）、各库版本字符串（version.z.S）以及版本号规范与分支策略。

Purpose and Scope

本页面向开发者系统梳理 AC792N_AIoT_SDK（fw-AC792_SDK 仓库，分支 release/AC792N_SDK_V3） 中"文档与版本资源"这一能力的完整构成：

• 文档资源：仓库根目录 README.md / README-en.md、子目录 README（sdk_tools、phone_app、sdk/apps/common/example）、在线文档中心与 doc/ 硬件资料目录的引用关系；
• 版本资源：运行时版本字符串来源（sdk/apps/common/system/version.c）、链接期注入的版本段（__VERSION_BEGIN/__VERSION_END）、各库 version.z.S 汇编版本文件、version.ver、version.h 等；
• 版本规范：major.minor.patch 版本号规则、分支（AC792N_SDK_V3）与发布 tag 的关系。

以下内容不属于本页范围，由兄弟页面另行覆盖：芯片外设驱动与协议栈实现（见"SDK 架构"类页面）、具体方案工程的编译与烧录流程（见"编译与烧录"类页面）、第三方组件（lvgl、mbedTLS、FlashDB 等）的详细 API。本页仅说明这些组件版本资源的存放位置与获取方式。

Overview

AC792N_AIoT_SDK 是一个覆盖 WiFi 视频、大屏音视频、WiFi 音频、智能家居等场景的多媒体 SoC 固件开发包。由于仓库本体只包含 SDK 源码与示例工程（不含完整开发文档），"文档与版本资源"承担了三个关键职责：

1. 导航与入口：根目录 README.md 是唯一的本地文档入口，通过它可跳转到在线文档中心、芯片数据手册、SDK 版本历史、FAQ 与社区支持；
2. 可追溯性：固件在启动早期（early_initcall）即打印 SDK 版本与所有链接进固件的库版本字符串，确保现场设备与源码版本一一对应；
3. 版本治理：通过统一的 major.minor.patch 规则与分支策略（主线开发分支 AC792N_SDK_V3、稳定发布 tag）管理迭代节奏，区分"尝鲜最新特性"与"量产稳定版本"两种使用路径。

典型使用场景：

• 开发前：阅读 README.md 的环境搭建、快速开始、工程结构章节，并跳转在线文档中心获取完整开发文档；
• 定位现场问题：抓取设备串口日志中 SDK Version 与 __VERSION_BEGIN 段输出的版本号，与仓库分支/tag 比对；
• 选择版本：根据 README 第十四章"版本与分支说明"决定跟随主线还是使用稳定发布版本。

Architecture

下图展示了文档资源与版本资源两大体系在仓库中的组织关系，以及运行时版本信息的产生路径：

flowchart TD
    subgraph sg_Docs["文档资源体系"]
        README["README.md<br/>（本地总入口，15 章）"]
        README_EN["README-en.md<br/>（英文版）"]
        SUB_README["子目录 README<br/>sdk_tools / phone_app / example"]
        DOC_CENTER["在线文档中心<br/>doc.zh-jieli.com/AC792"]
        DATASHEET["doc/硬件资料/datasheet<br/>芯片规格书"]
        VERSION_HISTORY["SDK 版本历史<br/>在线页面"]
    end

    subgraph sg_Version["版本资源体系"]
        VERSION_C["sdk/apps/common/system/version.c"]
        VERSION_VER["sdk/cpu/wl83/tools/version.ver"]
        VERSION_ZS["各库 version.z.S<br/>btctrler / btstack / driver / net / server / system"]
        VERSION_H["version.h<br/>lvgl / mbedtls / wolfssl 等"]
    end

    subgraph sg_Runtime["运行时（固件启动）"]
        INITCALL["early_initcall"]
        PRINTER["串口日志输出"]
    end

    README --> DOC_CENTER
    README --> DATASHEET
    README --> VERSION_HISTORY
    README --> SUB_README

    VERSION_C -->|"sdk_version()"| INITCALL
    VERSION_C -->|"遍历 __VERSION_BEGIN..__VERSION_END"| VERSION_ZS
    VERSION_ZS --> INITCALL
    VERSION_VER --> VERSION_C
    INITCALL --> PRINTER

图中各节点说明：

设计意图：将文档入口集中在根 README（降低新手门槛），而把版本信息分散保存在各库源码旁（version.z.S 与库源码同目录维护、随库发布），最后由 version.c 在链接期统一聚合输出——既保证"版本跟着代码走"，又避免维护一份集中的版本清单。

文档资源详解

根目录 README：本地文档总入口

README.md 是仓库唯一的顶层文档，以 15 个章节组织，覆盖从"是什么"到"怎么用"再到"版本怎么选"的完整链路：

注意 README 明确指出："SDK 固件包不含开发文档，开发前请详细阅读 SDK 在线开发文档。"——即本地仓库只承载代码与导航，完整文档托管于在线文档中心（doc.zh-jieli.com/AC792）。

文档中心与硬件资料引用

README 第十二章集中维护了外部资源链接，构成文档体系的"外链层"：

子目录 README

仓库按功能域在子目录维护了补充文档，与根 README 形成层级：

• sdk_tools/README.md：SDK 配套工具链说明；
• phone_app/README.md：手机 App 工程说明；
• sdk/apps/common/example/readme.md：通用示例工程导读；
• 第三方组件自带文档：sdk/apps/common/example/third_party/ 下 coremark、securemark、FlashDB 等各自的 README/LICENSE 文档（如 FlashDB/docs）。

设计意图：本地文档刻意"薄"（导航 + 速查），完整文档"厚"（在线中心），既避免仓库体积膨胀，也保证文档随版本持续更新而无需同步到每个固件分支。

版本资源详解

运行时版本上报：sdk/apps/common/system/version.c

这是版本体系的"汇聚点"。该文件实现两个函数并通过 early_initcall 在系统启动早期执行：

#include "system/includes.h"
#include "generic/log.h"
#include "app_config.h"

extern char __VERSION_BEGIN[];
extern char __VERSION_END[];

const char *sdk_version(void)
{
    return "AC792N SDK on branch [release/AC792N_SDK_V3] tag AC792N_SDK_BETA_V3.1.6_2026-07-08";
}

static int app_version_check()
{
    char *version;

    printf("================= SDK Version    %s     ===============\n", sdk_version());

    for (version = __VERSION_BEGIN; version < __VERSION_END;) {
        printf("%s\n", version);
        version += strlen(version) + 1;
    }
    puts("=======================================\n");

    return 0;
}
early_initcall(app_version_check);

Source: sdk/apps/common/system/version.c

工作机制逐行解析：

1. sdk_version()：返回编译期固化在源码中的 SDK 版本字符串，含分支名（release/AC792N_SDK_V3）与发布 tag（AC792N_SDK_BETA_V3.1.6_2026-07-08）。tag 中的 V3.1.6 即 major.minor.patch 结构（见下文版本号规则），2026-07-08 为发布日期；
2. __VERSION_BEGIN / __VERSION_END：由链接脚本提供的段边界符号。链接器把所有库（version.z.S）中的版本字符串按序放入 __VERSION 段，形成以 \0 结尾的字符串序列；
3. app_version_check()：先打印 SDK 总版本，再遍历 __VERSION_BEGIN 到 __VERSION_END 之间的每个字符串（version += strlen(version) + 1 跳过空字符），逐个打印各库版本；
4. early_initcall(app_version_check)：将函数注册为启动早期回调，保证串口日志一出现就能看到版本信息，便于在产线/现场第一时间核对固件版本。

设计意图：把版本字符串写成汇编段（version.z.S）而非 C 变量，是为了让各库版本能独立地随库文件一起编译、一起发布，链接时无需任何注册代码即可自动汇聚——这是"零耦合聚合"的版本管理模式。

各库版本字符串：version.z.S 系列

仓库在 sdk/include_lib/ 下按库目录维护同名汇编版本文件，例如：

• sdk/include_lib/btctrler/version.z.S
• sdk/include_lib/btstack/version.z.S
• sdk/include_lib/driver/version.z.S
• sdk/include_lib/net/version.z.S
• sdk/include_lib/server/version.z.S
• sdk/include_lib/system/version.z.S

这些文件在链接期被聚合到 __VERSION_BEGIN..__VERSION_END 区间，由 version.c 统一输出。因此一个库升级后，只需更新其自身 version.z.S，固件日志即可反映新版本，无需改动公共代码。

工具与第三方版本文件

版本号规则（major.minor.patch）

README 第十四章明确定义了语义化版本规则（README.md）：

结合 sdk_version() 返回值可见当前发布形态：AC792N_SDK_BETA_V3.1.6（BETA 前缀表示测试阶段发布，V3 为主版本、1 为次版本、6 为补丁）。分支策略上，README 建议：测试/研发尝试最新特性跟随主线 AC792N_SDK_V3；量产用途使用对应稳定发布版本。

核心流程：版本信息从源码到串口日志

sequenceDiagram
    participant SRC as 库源码（version.z.S）
    participant LD as 链接器（__VERSION 段）
    participant FW as 固件（version.c）
    participant BOOT as 系统启动（early_initcall）
    participant UART as 串口日志

    SRC->>LD: 各库版本字符串（\0 分隔）
    LD->>FW: 生成 __VERSION_BEGIN / __VERSION_END 边界符号
    BOOT->>FW: 调用 app_version_check()
    FW->>FW: sdk_version() 返回分支 + tag 字符串
    FW->>FW: 遍历 __VERSION_BEGIN..__VERSION_END
    FW->>UART: "SDK Version AC792N SDK on branch [release/AC792N_SDK_V3] tag ..."
    FW->>UART: 逐行打印各库版本字符串

执行顺序说明：

1. 编译各库时，version.z.S 中的版本字符串被置于 __VERSION 段；
2. 链接阶段，链接脚本为段首尾生成 __VERSION_BEGIN、__VERSION_END 符号，段内字符串以 \0 分隔；
3. 固件启动，early_initcall 机制触发 app_version_check()；
4. 函数先打印 SDK 总版本（分支+tag），再遍历段内字符串逐条打印；
5. 现场工程师通过串口日志即可完整核对 SDK 与各库版本，无需读取 flash 或拆机。

使用示例

示例一：获取 SDK 版本字符串

任意应用代码可通过 sdk_version() 获取当前固件的 SDK 版本（含分支与 tag），用于在 UI/AT 命令/日志中展示：

const char *sdk_version(void)
{
    return "AC792N SDK on branch [release/AC792N_SDK_V3] tag AC792N_SDK_BETA_V3.1.6_2026-07-08";
}

Source: sdk/apps/common/system/version.c

示例二：启动早期自动打印全部版本

固件启动即执行，无需任何应用层调用——这是 early_initcall 注册模式（该宏是杰理 SDK 的启动回调机制，支持在系统初始化早期插入自检逻辑）：

static int app_version_check()
{
    char *version;

    printf("================= SDK Version    %s     ===============\n", sdk_version());

    for (version = __VERSION_BEGIN; version < __VERSION_END;) {
        printf("%s\n", version);
        version += strlen(version) + 1;
    }
    puts("=======================================\n");

    return 0;
}
early_initcall(app_version_check);

Source: sdk/apps/common/system/version.c

示例三：核对版本资源的可追溯信息

升级某个库（如蓝牙协议栈）后，版本信息随库发布。现场验证时抓取串口日志中的 SDK Version 行与后续各库版本行，与仓库分支（release/AC792N_SDK_V3）及 在线版本发布记录 比对即可确认固件出处。

API 参考

const char *sdk_version(void)

返回当前 SDK 的版本字符串，包含分支名与发布 tag。

• 返回值：形如 "AC792N SDK on branch [release/AC792N_SDK_V3] tag AC792N_SDK_BETA_V3.1.6_2026-07-08" 的常量字符串；
• 调用时机：任意时刻可调用；亦被 app_version_check() 在启动早期调用；
• 无参数、无异常抛出（纯常量字符串返回）。

static int app_version_check(void)

启动早期自检回调，打印 SDK 版本并遍历 __VERSION 段输出各库版本。

• 返回值：恒为 0（early_initcall 要求返回 int）；
• 副作用：通过 printf / puts 向串口输出版本信息；
• 注册方式：early_initcall(app_version_check)——无需应用代码显式调用，系统启动时自动执行；
• 依赖符号：__VERSION_BEGIN、__VERSION_END（由链接脚本提供，extern char 声明）。

配置与资源清单

版本体系属于"只读/自动"资源，无运行时配置项；唯一可关注的是维护性信息：

版本号更新是源码级维护：发版时修改 version.c 中的 sdk_version() 字符串与相关 version.z.S，重新编译链接即可，无需任何运行时配置。

故障模式、边界与注意事项

扩展点与运维提示

• 新增库的版本接入：为新库添加 version.z.S 即可自动纳入启动版本打印，无需修改 version.c——这是本机制的核心扩展点；
• 自定义版本标识：应用可在 app_version_check() 之后追加自己的 printf，或在 UI 中调用 sdk_version() 展示版本；
• 版本选型：跟随主线 AC792N_SDK_V3 获得最新特性（可能不稳定）；量产锁稳定 tag（如 AC792N_SDK_BETA_V3.1.6）并配合在线发布记录；
• 环境配套：Windows 编译请使用 sdk/make_prompt.bat 进入预配置命令行（README FAQ 11.2），版本相关文件均随源码仓库分发，无需额外下载。

相关链接

• README.md（本地文档总入口）
• README.md 第十四章：版本与分支说明
• README-en.md（英文版）
• sdk_version() 与 app_version_check() 实现
• wl83 工具版本 version.ver
• 在线文档中心（完整开发文档）
• SDK 版本历史（在线发布记录）
• 相关兄弟页面：环境搭建与快速开始（README 第四章、第五章）、编译与烧录指南（README 第八章、第九章）、工程结构说明（README 第六章）。