WS63 SDK 软件架构介绍

概述

WS63 是一款面向物联网和短距无线通信的 SoC 芯片，其 SDK 采用分层架构设计，自底向上分为三层：内核&驱动层 → OS 与中间件层 → 应用层，同时配套完整的构建工具与配置体系。

---

内核&驱动层 — 对接硬件的底座

内核与驱动层是 SDK 的最底层，直接为上层屏蔽硬件差异。

驱动负责操控 WS63 芯片的各类外设：

• 无线通信：星闪、蓝牙、Wi-Fi
• 通用外设：GPIO、UART、SPI、I2C、PWM、ADC、DMA
• 存储与安全：SFC、安全模块

内核提供操作系统的基础运行能力：

• LiteOS / FreeRTOS / RT-Thread：三种可选的轻量级 RTOS，提供任务调度、内存管理、中断管理、时钟管理
• OSAL（Operating System Abstraction Layer，操作系统抽象层）：让上层代码不依赖具体内核实现，一套代码可无缝运行于任一内核之上
• 裸机模式：适用于无 RTOS 的极简场景，不依赖任何操作系统内核
• C 基础库、高性能数学库

对外的接口：HAL（Hardware Abstraction Layer，硬件抽象层）API，包括 UAPI / OSAL / POSIX（Portable Operating System Interface，可移植操作系统接口）等，中间件层通过这套 API 调用驱动能力。

---

OS 与中间件层 — 核心能力封装

OS 与中间件层是 SDK 的核心层，它将驱动和内核的能力封装成可直接使用的功能模块。

功能子系统（按业务领域划分）：

子系统	做什么
星闪子系统	星闪（NearLink）短距无线通信
蓝牙子系统	经典蓝牙 + BLE（Bluetooth Low Energy，低功耗蓝牙）
Wi-Fi 子系统	Wi-Fi 连接与网络管理
雷达子系统	雷达探测协议栈与驱动
Matter 子系统	Matter 智能家居互联协议
AI 子系统	AI 推理引擎及模型管理

集成的开源组件：lwIP（轻量级 TCP/IP 协议栈）、mbedTLS（安全传输层）、cJSON（JSON 解析）、MQTT（物联网消息协议）、LVGL（嵌入式图形库）、LittleFS（轻量级文件系统）等。

对外的接口：Middleware / OSAL API，应用层通过这套 C 语言 API 使用中间件能力。

---

应用层 — 开发者工作的入口

应用层是开发者直接打交道的一层，日常工作主要在这里编写业务代码，调用中间件提供的 API。

应用层包含两类内容：

• 主应用工程：实际产品的业务逻辑和初始化流程
• Samples 示例：星闪样例、蓝牙样例、Wi-Fi 样例、雷达样例、外设样例，帮助快速上手

---

开发约束 — API 调用规则

SDK 各层之间有严格的调用约束，违反将导致不可预期的行为。

graph TD
    APP[应用层] -->|允许| MW[中间件层]
    APP -->|允许| OSAL[OSAL 接口]
    APP -->|禁止 ❌| HAL[HAL / 驱动层]
    MW -->|允许| HAL
    MW -->|允许| OSAL
    HAL -->|允许| HW[硬件寄存器]
    OSAL -->|允许| KERNEL[内核]

调用方向	是否允许	说明
应用层 → 中间件 API	允许	推荐的开发方式
应用层 → OSAL API	允许	任务、信号量、队列等系统调用
应用层 → HAL / 驱动 API	禁止	应通过中间件间接访问，直接调用破坏可移植性
中间件 → HAL / 驱动 API	允许	中间件对驱动的合法调用
中断服务函数 → OSAL API	部分允许	仅允许 FromISR 后缀的 API

建议开发时优先使用公开 API，不直接调用驱动层接口。API 使用方法请参考 fbb_ws63/docs/ 下的 API 使用指南及开发文档。

---

中断处理模型

从中断触发到用户代码的完整路径：

sequenceDiagram
    participant HW as 硬件外设
    participant NVIC as NVIC 中断控制器
    participant ISR as 驱动 ISR
    participant HAL as HAL 回调
    participant MW as 中间件回调
    participant APP as 用户回调

    HW->>NVIC: 触发中断信号
    NVIC->>ISR: 跳转中断向量表
    ISR->>ISR: 读取状态寄存器 / 清中断标志
    ISR->>HAL: 调用 HAL 层回调
    HAL->>MW: 数据打包 / 事件通知
    MW->>APP: 触发用户注册的回调函数
    Note over ISR,APP: ISR 中仅做最小处理，耗时操作通过任务/工作队列下放

关键原则：

• ISR 中禁止阻塞：中断上下文中不能调用可能阻塞的 API（如获取信号量、延时）
• ISR 中不能打印：避免在 ISR 中使用 printf / printk
• 使用工作队列：耗时处理应通过 workqueue / delaywork 下放到任务上下文
• FromISR 系列 API：在 ISR 中释放信号量、发送消息时使用带 FromISR 后缀的接口

---

最小应用骨架

以下是一个 WS63 最小应用的代码骨架，展示基本的初始化流程：

#include "sdk_common.h"

// 主任务
static void *app_main_task(void *arg)
{
    // 1. 初始化外设
    peripheral_init();

    // 2. 初始化网络（按需）
    wifi_init();
    ble_init();

    // 3. 业务事件循环
    while (1) {
        app_process_events();
        LOS_Msleep(10);
    }
    return NULL;
}

// SDK 入口
int app_main(void)
{
    // 创建设备管理任务
    uapi_task_create(app_main_task, "AppTask",
                     CONFIG_APP_TASK_STACK_SIZE,
                     NULL,
                     CONFIG_APP_TASK_PRIORITY);

    return 0;
}

所有示例代码位于 application/samples/ 目录，可基于示例工程开始开发。

---

引导加载 — Bootloader

Bootloader 是系统上电后运行的第一段代码，负责硬件初始化和固件加载，包含通用引导、Flash 引导、产线烧录与安全配置等阶段。

详见 启动流程。

---

构建与配置

构建系统

SDK 使用 CMake（最低版本 3.14.1）作为构建系统，通过 -DCHIP=<name> 指定目标芯片。根目录 build.py 提供了 Python 封装的构建入口，可配合 fbb CLI 工具完成一键编译与固件打包。

详见 构建产物。

配置体系

SDK 采用 Kconfig 配置体系（入口文件 config.in），支持 menuconfig 图形化界面按需裁剪功能模块。各子目录均有各自的 Kconfig 文件，逐级组织配置项。

---

目录说明

所属层级	目录	子目录	说明
内核&驱动层	drivers/	chips/	芯片级驱动（WS63）
		driver/ + hal/	外设驱动与 HAL 抽象
		boards/	板级配置
		adapter/	驱动适配层
	kernel/	liteos/ / FreeRTOS / RT-Thread	可选 RTOS 内核
		osal/	OS 抽象层（OSAL）
		osal_adapt/	内核适配层
		non_os/	裸机模式
OS 与中间件层	include/	driver/	驱动相关头文件
		middleware/	中间件相关头文件
	middleware/	chips/	芯片适配
		services/	Wi-Fi 服务、Matter 等能力封装（含 OTA、AT 命令、文件系统）
		utils/	通用工具（算法、应用初始化、DFX、安全、分区管理等）
	protocol/	bt/	蓝牙协议栈
		wifi/	Wi-Fi 协议栈
		radar/	雷达协议栈
	open_source/	—	lwIP / mbedTLS / cJSON / MQTT / LVGL / LittleFS 等
应用层	application/	ws63/	主应用工程
		samples/	示例代码（bt / wifi / peripheral / radar）
引导与工具	bootloader/	commonboot/ / flashboot_ws63/ / provision_ws63/	引导加载
	tools/	—	构建与打包工具

重点目录：application/（写业务）、include/（查 API）、middleware/（用中间件）、fbb_ws63/docs/（查阅开发文档）。