一句话结论：AliOS Things 的系统设计，本质是用「Rhino 内核 + CSI 硬件抽象 + yaml 组件依赖 + 分级驱动加载」把「无序的外设初始化」变成「可声明的顺序」。 它比 FreeRTOS 多了组件依赖解析与 VFS 统一设备接入，比 Linux 少了设备树与虚拟内存——代价是板级资源全部写死在代码里，改一颗料的引脚就要动 BSP。 线上故障最集中的三处：同一加载级别内的初始化顺序随机、中断上下文调用了阻塞 API、栈与堆被低估。管住这三处，系统稳定性解决八成。

这份文档解决什么

本文是 AliOS Things 系统级开发总文档：从环境搭建、内核原理、启动与加载机制、CSI 抽象与 BSP 移植、组件化配置、设备驱动，到系统组件、调试、性能与低功耗、可靠性、测试、OTA 与发布规范，构成一条完整链路。 驱动开发作为第 8 章子章节嵌入；专项器件（SPI NOR / SPI NAND / SD NAND 等）的具体时序与命令细节，仍以对应器件的设计指南为准，本文只讲「在这一层该如何把驱动挂进系统」。

使用约定

• API 与目录以 AliOS Things 3.x（3.1 / 3.3） 为主线，兼顾 2.x；两代差异明显处均单独标注。目标平台以 Cortex-M3/M4/M33 为主，RISC-V 与 C-Sky（平头哥）差异另行提示。
• 代码示例只保留系统层逻辑；具体寄存器操作统一写成 /* chip 层提供 */ 注释。
• 标 红线 为强制约束，标 警惕 为高频踩坑点，标 建议 为经验推荐值。
• 文中出现的默认数值（栈大小、优先级、阈值、目录名）以 SDK 模板与官方仓库为参考；不同版本目录名差异较大（如 2.x 顶层 board/ 在 3.3 收进 hardware/），落地前以工程内实际目录为准。
• 芯片参数、时钟、外设行为一律以官方 datasheet 与 AliOS Things 官方文档 / 源码为准。

1 · 文档概述与系统架构

这一章解决三件事：这份文档覆盖到哪一层、AliOS Things 长什么样、以及它和 Linux / RT-Thread / FreeRTOS 的边界在哪。读完再决定后面该精读哪几章。

1.1 编写目的、适用范围与读者

本指南面向基于 AliOS Things 做系统级开发的工程团队：把一颗裸的 MCU 变成可量产、可升级、可运维的物联网设备。它要回答的不是「某个寄存器怎么写」，而是「一堆驱动和组件如何按正确顺序长成一个系统」。

1.2 版本基线、内核与支持平台

AliOS Things 有两条实际在用的代际：2.x（Rhino 内核 + 顶层 board/ 与 platform/mcu/ + 组件 .mk 描述）与 3.x（3.1 / 3.3，统一 VFS 接入、yaml 构建、内核对象统一管理、轻应用框架）。本指南以 3.x 为主、2.x 兼容，两代差异较大处显式标注。

1.3 术语与缩写

1.4 五层架构总览

AliOS Things 采用分层架构 + 组件架构双视角：分层决定「谁能调用谁」，组件化决定「编译时怎么拼装」。两者叠加的效果是——上层只依赖 API 契约，下层只保证原语正确，中间靠构建系统把需要的组件拼进来。

• ⑤ 应用与解决方案层：示例工程、业务应用、轻应用脚本、云端接入。一个 solution 组件可以依赖多个 board 组件，构建时由 board_name 指定本次用哪块板。
• ④ 通用组件层：OTA、uData、uDisplay、netmgr、ulog、cli 等增值中间件。它们与业务平级，靠组件依赖被拉进固件，靠加载等级或显式 init 挂进系统。
• ③ AOS API 与系统服务层：应用唯一应当直接依赖的一层。VFS 把设备变成文件，KV 提供持久化，Yloop 提供事件循环。
• ② 内核层 Rhino：任务、调度、IPC、内存、定时器、对象管理。3.3 起对任务 / 互斥量 / 信号量做一致性对象管理，可维护性与可扩展性明显提升。
• ① 硬件抽象与板级层：CSI 接口族屏蔽寄存器差异，arch 层屏蔽 CPU 差异，board 层承载引脚、时钟与分区表。

1.5 AOS API 的三层封装

一个容易踩的坑是：同一件事在 AliOS Things 里有三套 API。混用不会报错，但会让代码在换内核或升版本时碎掉。

1.6 与 Linux / RT-Thread / FreeRTOS 的差异

把 AliOS Things 放进坐标系里看，它的独特性主要在三处：无设备树、分级加载、yaml 组件依赖。其余部分与主流 RTOS 大同小异。

1.7 阅读路线图与本系列文档的关系

1. 先看第 1、2 章：确认基线版本、把环境跑通、知道代码该放哪个目录。哪怕只是照抄 helloworld 示例，也要自己编译烧录一遍。
2. 再看第 3、4 章：内核对象与启动 / 加载顺序。这两章决定了后面所有「为什么会卡住」类问题的定位速度。
3. 做移植读第 5、6 章：CSI 接口族与移植四要素；做功能读第 7、9 章：组件依赖与系统组件。
4. 写驱动读第 8 章：VFS 注册、open/ioctl 链路、并发与低功耗约束。专项器件的时序细节回到对应器件设计指南。
5. 联调与上线读第 11、12、13 章：调试手段、资源与功耗、可靠性；交付读第 14、15、16 章：测试、OTA、发布。

2 · 开发环境与工程结构

这一章的目标很具体：把示例工程编译、烧录、跑起来，并且知道每一行代码该放在哪个目录。环境没跑通之前，后面所有章节都只是纸上谈兵。

2.1 宿主机环境与依赖

推荐 Ubuntu 20.04 / 22.04（64 位）。AliOS Things 的构建体系基于 Python 脚本（aos-cube）与构建框架混合，对宿主机版本比较敏感。

# 1) 基础依赖
sudo apt-get update
sudo apt-get install -y build-essential git python3 python3-pip python3-setuptools \
                        libssl-dev libffi-dev curl minicom

# 2) 构建工具 aos-cube（AliOS Things 命令行工具集）
pip3 install aos-cube           # 若系统 Python 版本冲突，可先建 venv
aos --version                   # 验证安装，例如 aos-cube 版本号 Rev 1.4.x

# 3) Cortex-M 工具链（以 ARM 官方 GCC 为例）
sudo apt-get install -y gcc-arm-none-eabi binutils-arm-none-eabi
arm-none-eabi-gcc --version

# 4) 其它架构按需安装
#    C-Sky（平头哥）：csky-abiv2-elf-*     （芯片厂商提供）
#    RISC-V        ：riscv64-unknown-elf-* 或 riscv32-elf-*
#    Xtensa        ：xtensa-lx106-elf / xtensa-esp32-elf（厂商提供）

# 5) linuxhost 目标（PC 上跑仿真，验证业务逻辑很方便）
sudo apt-get install -y g++-multilib       # 64 位机器上编 32 位目标需要

2.2 SDK 获取与分支管理规范

git clone https://github.com/alibaba/AliOS-Things.git
cd AliOS-Things
git checkout rel_3.3.0          # 或项目指定的基线 tag
git submodule update --init --recursive   # 部分版本含子模块

# 团队内建议：基线用 tag，开发用分支
git checkout -b feature/<board>-port rel_3.3.0

• 基线一律用 tag（如 rel_3.3.0），禁止直接把 master 当产品基线——master 上的组件版本号会漂移（常见 master、dev_aos），导致构建不可复现。
• 组件版本号必须与仓库 branch / tag 一致：package.yaml 里的 version 不是随便写的，构建系统依赖它解析依赖；对不上会直接报依赖解析失败。
• 私有组件建议独立仓库 + 版本 tag，通过依赖引入，避免把 SDK 仓库改得无法升级。

2.3 交叉工具链配置

工具链前缀通常在芯片组件的 package.yaml 里通过 toolchain_prefix 指定，构建系统据此拼出编译器名。若编译时报「找不到编译器」，先确认芯片组件里的前缀与实际安装的工具链名一致。

2.4 工具链全景

2.5 SDK 目录结构详解

AliOS Things 的目录按系统架构分层划分：components 放内核之上的所有功能组件，hardware 放板级支持包与 CPU 适配代码，kernel 放内核，solutions 放完整应用工程。2.x 与 3.x 目录名差异较大，落地前以工程实际目录为准。

2.6 编译、清理与单组件编译

# 配置（交互式选择 app / board；首次会自动下载 kconfig 工具）
aos make menuconfig
aos make helloworld_demo@haas100 -c config     # 指定 app@board 并重新配置

# 编译：app@board 是最核心的一条命令
aos make helloworld_demo@haas100
aos make helloworld_demo@haas100 JOBS=8        # 并行加速

# 清理
aos make clean                                 # 清理当前目标产物
aos make distclean                             # 彻底清理（含配置）

# 烧录与串口
aos upload helloworld_demo@haas100             # 交互式选择串口号后烧录
aos monitor helloworld_demo@haas100            # 打开串口终端

# 生成组件模板（把已有源码目录快速变成组件）
aos convert <dir>                              # 在 dir 下生成 package.yaml 模板

关于单组件编译：AliOS 的构建以 app@board 为整体单位，没有独立的「只编一个组件」开关。实践做法是——建一个最小 solution 组件，只依赖要验证的那个组件，用它做编译与链接验证。这比在全量工程里排除依赖快得多，还能顺带验证组件的依赖声明是否自洽。

2.7 编译产物说明

2.8 烧录与串口调试环境

1. 确认串口号与波特率：Linux 下 /dev/ttyUSB0，Windows 下 COMx；波特率以板级 UART 配置为准。
2. 烧录：aos upload，交互式选择端口；特殊芯片依赖厂商工具（如 esptool），配置写在 upload 描述文件里。
3. 打开终端：aos monitor 或串口助手，确认能看到启动日志与 CLI 提示符。
4. 验证：输入 help 看命令列表，再敲内核与内存类命令确认组件已起来。
5. 固化配置：把串口号、波特率、烧录偏移写进项目 README，避免团队内反复问。

3 · Rhino 内核基础

Rhino 是 AliOS Things 自研的实时内核：小体积、硬实时、可裁剪。这一章不追求罗列每个 API，而是把任务、IPC、中断、内存、调度、定时器六类机制的设计意图与约束讲清楚——绝大多数系统级 Bug 都能追溯到这六处之一。

3.1 V2 与 V3 的内核形态差异

3.2 内核对象与统一对象管理

3.3 起，任务、互斥量、信号量等内核资源采用一致的管理方式：统一的创建 / 销毁路径、统一的错误码体系、可被诊断命令统一遍历。这带来两个直接好处：

• 诊断命令能列出全部对象：任务列表、内存信息、CPU 占用等命令依赖的就是这套对象管理；对象不进容器，命令行里就看不到它。
• 静态与动态创建路径对齐：静态对象（自带控制块与缓冲）与动态对象（堆上分配）语义一致，只是内存来源不同，便于后期把动态改静态以抗碎片。

错误码：内核原语返回 kstat_t（如 RHINO_SUCCESS、RHINO_NULL_PTR、RHINO_NO_MEM），而 aos_ 层通常转成 int（0 成功 / 负值失败）。混用两层时不要拿 kstat_t 当 errno 用。

3.3 任务状态机与优先级

任务（task）是 Rhino 的调度实体。理解状态机的价值在于：看到某个任务不动了，能立刻判断它是被阻塞、被挂起，还是压根没被调度。

/* AOS 层创建任务的典型形态 */
static aos_task_t g_sensor_task;
static uint8_t    g_sensor_stack[2048];      /* 静态栈：抗碎片，推荐 */

static void sensor_task_entry(void *arg)
{
    while (1) {
        sample_once();                        /* 采样 */
        aos_msleep(100);                      /* 让出 CPU，不要用忙等 */
    }
}

int sensor_task_start(void)
{
    int ret = aos_task_new_ext(&g_sensor_task, "sensor", sensor_task_entry,
                               NULL, sizeof(g_sensor_stack), SENSOR_PRIO);
    /* 返回值必须检查：栈不足 / 优先级非法 / 内存不足都会失败 */
    return ret;
}

优先级分档方法论（建议）

3.4 IPC 原语与选型

Rhino 提供的内核原语相当丰富：缓冲队列、环形缓冲、定时器、信号量、互斥量、队列、事件等。选择的原则不是「哪个功能多」，而是「哪个语义最贴合」——用信号量保护临界区是经典的优先级反转来源。

3.5 中断模型与中断上下文约束

中断是实时性的来源，也是稳定性事故的高发区。Rhino 的模型与主流 RTOS 一致：上半部极短、下半部延后。

中断上下文禁用清单（红线）

• 任何可能阻塞的调用：带超时的 sem_wait / mutex_lock / queue_recv、延时接口。
• 拿互斥量：中断没有任务上下文，持有者语义不成立。
• 大批量日志打印：串口打印是毫秒级操作，会把中断拖成灾难。
• 动态内存分配：不可重入风险 + 时长不确定。
• 浮点运算（无 FPU 上下文保存时）：会破坏任务侧浮点现场。

3.6 内存管理与碎片

Rhino 为大多数内核对象提供静态与动态两种分配；小内存块分配器既支持定长块也支持变长块，并支持多个内存区域。这套设计的目的是让固件能塞进资源极其有限的设备，代价是碎片与容量必须自己管。

泄漏与踩踏的检测手段

3.7 调度器与抢占

Rhino 是基于优先级的抢占式调度器：任何时刻就绪的最高优先级任务在运行；同优先级任务可按时间片轮转（取决于配置）。调度点包括：任务阻塞 / 退出、信号量与队列操作、中断返回、时间片到期、显式让出。

• 抢占代价：上下文切换要压栈弹栈，优先级级数与任务数越多开销越大。频率极高的任务要考虑合并或降频。
• 临界区：关中断 / 关调度的时间直接决定最坏中断延迟。关中断区间内禁止任何函数链不确定的操作。
• 优先级反转：低优先级任务持锁、中优先级任务抢占、高优先级任务等锁——靠互斥量的优先级继承缓解，但不能靠它根治错误的锁设计。

3.8 定时器与工作队列

4 · 启动流程与分级驱动加载

这一章是 AliOS Things 与其他 RTOS 拉开差距的地方。Linux 靠设备树描述硬件、靠 probe 顺序解决依赖；AliOS Things 靠链接段 + 九个初始化等级解决同样的问题。理解它，就能解释「为什么我的驱动有时好用有时不好用」。

4.1 上电到应用任务的全链路

七个阶段的分工非常明确：arch 层只管 CPU，chip 层只管芯片，board 层只管这块板子，components 只管软件服务。排查启动故障时，先看卡在哪一段，就基本知道该翻哪个目录的代码。

4.2 系统服务初始化内部顺序

内核初始化之后，系统会依次拉起一组核心服务。以 2.x / 3.x 共有的结构为例，典型顺序是：

/* 概念化顺序，具体以工程源码为准 */
vfs_init();          /* 虚拟文件系统：建立 inode 表与互斥保护 */
vfs_device_init();   /* 注册设备节点与操作方法 */
cli_service_init();  /* 命令行服务（未启用 CLI 时走无 CLI 的日志初始化） */
aos_kv_init();       /* 键值存储初始化：配网信息、序列号从这里读 */
sal_device_init();   /* 套接字抽象层（启用网络时） */
aos_loop_init();     /* Yloop 事件循环：主任务默认实例 */
ota_service_init();  /* OTA 服务（启用时） */
sensor_init();       /* 传感器框架（启用时） */
/* 之后进入分级驱动加载，再进入应用入口 */

4.3 九级驱动加载机制

驱动框架把设备驱动分成 9 个级别，每个级别对应一个声明宏与一个链接段。用同一宏声明的函数指针会在链接阶段被放进同一个段，系统启动时按段顺序依次调用。这是 AliOS Things 解决驱动依赖的核心手段。

/* 典型用法：用宏声明驱动初始化函数 */
static void my_spi_driver_entry(void)
{
    /* 1) 初始化控制器（CSI 已提供时直接调用 CSI 接口） */
    csi_spi_init(&g_spi, 0);
    /* 2) 注册到 VFS / 设备框架 */
    register_dev_node("/dev/spi0", &my_spi_ops, &g_spi);
}
BUS_DRIVER_ENTRY(my_spi_driver_entry)            /* 总线控制器：第 2 级 */

static void my_sensor_driver_entry(void)
{
    /* 依赖 SPI 总线，必须晚于 BUS 级 */
    sensor_dev_t *dev = sensor_create(...);
    sensor_register(dev);
}
LEVEL1_DRIVER_ENTRY(my_sensor_driver_entry)      /* 第 6 级 */

分级选择决策（建议）

4.4 同级别内顺序随机（头号陷阱）

规避方法

• 有依赖就分到不同级别：被依赖方放更低的级别号，不要试图在同一级里「碰巧先跑」。
• 同级别驱动之间禁止隐式依赖：A 驱动的初始化函数不得假设 B 已完成。
• 需要严格次序的一组初始化，合并成一个 entry：在一个初始化函数内按固定顺序调用，比分散到多个宏可靠得多。
• 改用显式初始化：对强依赖的模块，宁可在业务启动阶段显式调用 init，也不要赌链接顺序。
• 用后台声明延后：耗时且非关键的初始化用后台声明，避免拖慢启动并降低耦合。

4.5 内核态 / 用户态与多 bin

3.x 在架构上支持应用与系统分离编译（多 bin）与轻应用运行时，目标是三件事：

• 增量升级：应用单独编成小镜像，OTA 时只下应用，省流量、降风险。
• 故障域收敛：应用逻辑出错不至于直接拖死内核（在具备 MPU / TrustZone 的平台上效果更实）。
• 脚本化业务：JS / MicroPython 轻应用让业务改动不必重新编译整个固件。

4.6 启动期故障排查

启动不起来时，先按「卡在哪一段」定位，再谈细节。绝大多数问题能在下表中找到对应项。