2.1 项目目录结构全景

学习阁2026/7/19大约 6 分钟项目结构项目结构目录结构架构

2.1 项目目录结构全景

📚 本节导读

学习时长：约 25 分钟
难度级别：⭐⭐☆☆☆
前置知识：第 1 章 OneOS-Lite 入门

🎯 学习目标

理解 OneOS-Lite 的分层架构设计思想
掌握各目录的职责和核心内容
能够在项目中快速定位代码位置
了解模块间的依赖关系

一、分层架构总览

OneOS-Lite 采用分层模块化架构设计，整体分为以下层次：

┌─────────────────────────────────────────────────────────┐
│                    应用层 (Application)                   │
│                   demos/  projects/  user/               │
├─────────────────────────────────────────────────────────┤
│                    组件层 (Components)                    │
│  ┌────────┬────────┬────────┬────────┬────────┐         │
│  │ 文件系统 │ 网络协议 │ 安全框架 │ 日志系统 │ OTA升级 │         │
│  │  fs/   │  net/  │security│  dlog  │  ota/  │         │
│  ├────────┼────────┼────────┼────────┼────────┤         │
│  │  DBoT  │ Shell │ 定位服务 │ 测试框架 │   ...  │         │
│  │ DBoT/  │shell/ │position│ atest/  │        │         │
│  └────────┴────────┴────────┴────────┴────────┘         │
├─────────────────────────────────────────────────────────┤
│             操作系统抽象层 (OSAL)                          │
│  cmsis/  freertos/  posix/  rtthread/  cpp11/           │
├─────────────────────────────────────────────────────────┤
│                    内核层 (Kernel)                        │
│  ┌────────┬────────┬────────┬────────┬────────┐         │
│  │ 任务管理 │ 内存管理 │ IPC机制 │ 定时器  │ 调度器  │         │
│  └────────┴────────┴────────┴────────┴────────┘         │
├─────────────────────────────────────────────────────────┤
│                    驱动层 (Drivers)                       │
│  ┌────────┬────────┬────────┬────────┬────────┐         │
│  │ 总线驱动 │ 设备驱动 │ HAL层  │ 网络驱动 │ 外设驱动 │         │
│  └────────┴────────┴────────┴────────┴────────┘         │
├─────────────────────────────────────────────────────────┤
│               C 库抽象层 (libc)                           │
├─────────────────────────────────────────────────────────┤
│               架构支持层 (Architecture)                    │
│  ARM / ARM64 / RISC-V / MIPS / C-SKY / LoongArch / SIM  │
├─────────────────────────────────────────────────────────┤
│                    硬件平台                               │
└─────────────────────────────────────────────────────────┘

二、顶层目录结构

OneOS-Lite v3.3.1 根目录包含以下内容：

目录/文件	类型	职责描述
`arch/`	目录	多架构支持代码（ARM、RISC-V 等）
`kernel/`	目录	内核核心代码（调度、内存、IPC）
`drivers/`	目录	设备驱动框架（30+ 种驱动）
`components/`	目录	可裁剪组件（文件系统、网络、安全等）
`osal/`	目录	操作系统抽象层（兼容多 OS API）
`libc/`	目录	C 标准库抽象层
`common/`	目录	通用工具和宏定义
`demos/`	目录	示例代码
`projects/`	目录	具体芯片项目工程
`templates/`	目录	项目模板
`scripts/`	目录	构建脚本
`docs/`	目录	开发文档
`user/`	目录	用户代码占位
`Kconfig`	文件	顶层配置入口
`CMakeLists.txt`	文件	顶层构建入口

三、各目录详解

3.1 内核层 (`kernel/`)

内核是 OneOS-Lite 的核心，提供实时操作系统的基础能力。

kernel/
├── include/                  # 内核头文件
│   ├── os_kernel.h           # 内核通用接口
│   ├── os_task.h             # 任务管理
│   ├── os_sched.h            # 调度器
│   ├── os_memory.h           # 内存管理
│   ├── os_sem.h              # 信号量
│   ├── os_mutex.h            # 互斥锁
│   ├── os_event.h            # 事件
│   ├── os_mq.h               # 消息队列
│   ├── os_mb.h               # 邮箱
│   ├── os_timer.h            # 定时器
│   └── os_spinlock.h         # 自旋锁
├── source/                   # 内核实现
│   ├── os_startup.c          # 启动初始化
│   ├── os_sched.c            # 调度器实现
│   ├── os_task.c             # 任务管理
│   ├── os_memory.c           # 内存管理
│   ├── os_sem.c              # 信号量实现
│   ├── os_mutex.c            # 互斥锁实现
│   ├── os_event.c            # 事件实现
│   ├── os_mq.c               # 消息队列实现
│   ├── os_mb.c               # 邮箱实现
│   ├── os_timer.c            # 定时器实现
│   └── os_workqueue.c        # 工作队列
├── Kconfig                   # 内核配置选项
└── weave.yaml

3.2 架构支持层 (`arch/`)

提供多 CPU 架构的底层适配，包括上下文切换、中断管理、启动代码等。

arch/
├── arm/                      # ARM 架构
│   ├── armv5te/              # ARMv5TE
│   ├── armv6m/               # ARMv6-M (Cortex-M0)
│   ├── armv7/                # ARMv7-A/R
│   ├── armv7m/               # ARMv7-M (Cortex-M3/M4/M7)
│   ├── armv7r/               # ARMv7-R
│   ├── armv8m/               # ARMv8-M (Cortex-M23/M33)
│   └── arm64/                # ARMv8-A (AArch64)
├── arm64/                    # ARM64 架构
├── csky/                     # 平头哥 C-SKY 架构
├── loongarch/                # 龙芯 LoongArch 架构
├── mips/                     # MIPS 架构
├── risc-v/                   # RISC-V 架构
└── sim/                      # 模拟器（POSIX 环境）

支持的架构一览：

架构	目录	典型芯片
ARM Cortex-M0/M0+	`arm/armv6m`	STM32F0, NXP LPC800
ARM Cortex-M3	`arm/armv7m`	STM32F1, GD32F1
ARM Cortex-M4	`arm/armv7m`	STM32F4, NXP Kinetis
ARM Cortex-M7	`arm/armv7m`	STM32F7, i.MX RT
ARM Cortex-M23/M33	`arm/armv8m`	新兴安全 MCU
ARM Cortex-A	`arm/armv7`, `arm64`	应用处理器
RISC-V 32/64	`risc-v`	GD32VF103, K210
MIPS32	`mips`	PIC32, 龙芯
C-SKY	`csky`	平头哥 E902/E906
LoongArch	`loongarch`	龙芯 2K 系列
POSIX 模拟	`sim`	Linux/Windows 开发机

3.3 驱动层 (`drivers/`)

驱动框架采用设备-总线-驱动三层模型，支持 30+ 种驱动类型。

drivers/
├── device.c / device.h       # 设备基类框架
├── driver.c / driver.h       # 驱动管理
├── drv_cfg.h / drv_log.h     # 驱动配置和日志
├── bus/                      # 总线驱动
├── pin/                      # GPIO 引脚控制
├── serial/                   # 串口驱动
├── i2c/                      # I2C 总线
├── spi/                      # SPI 总线
├── touch/                    # 触摸屏
├── audio/                    # 音频
├── camera/                   # 摄像头
├── can/                      # CAN 总线
├── sensors/                  # 传感器框架
├── timer/                    # 硬件定时器
├── rtc/                      # 实时时钟
├── watchdog/                 # 看门狗
├── dma/                      # DMA 控制器
├── usb/                      # USB 设备
├── tinyusb/                  # TinyUSB 协议栈
├── sdio/                     # SDIO 接口
├── graphic/                  # 图形显示
├── net/                      # 网络设备
├── hwcrypto/                 # 硬件加密
├── fal/                      # Flash 抽象层
├── mtd/ / nand/ / sflash/    # 存储设备
├── hal/                      # 芯片 HAL 层
├── misc/ / console/ / ...    # 其他驱动
├── Kconfig
└── weave.yaml

3.4 组件层 (`components/`)

可裁剪的功能组件，通过 Kconfig 按需启用。

组件	目录	功能
文件系统	`fs/`	VFS + LittleFS/FatFs/JFFS2/NFS
网络协议栈	`net/`	LWIP + Socket + MQTT/CoAP/HTTP
安全框架	`security/`	mbedtls + OneTLS + libSSH
Shell 命令行	`shell/`	交互式调试命令
日志系统	`dlog/`	分级日志输出
测试框架	`atest/`	自动化单元测试
DBoT	`DBoT/`	分布式物联总线
OTA 升级	`ota/`	远程差分固件升级
位置服务	`position/`	定位能力适配

3.5 OSAL 抽象层 (`osal/`)

操作系统抽象层，使 OneOS 组件可以兼容多种 OS API。

适配层	目录	用途
CMSIS-RTOS	`cmsis/`	ARM CMSIS-RTOS API 兼容
FreeRTOS	`freertos/`	FreeRTOS API 兼容
POSIX	`posix/`	POSIX 标准 API 兼容
RT-Thread	`rtthread/`	RT-Thread API 兼容
C++11	`cpp11/`	C++11 线程库支持

3.6 其他目录

目录	说明
`libc/`	C 标准库抽象，提供统一的 C 库接口
`common/`	通用工具宏、链表、哈希等基础数据结构
`demos/`	各类外设和组件的使用示例
`projects/`	具体芯片的项目工程（如 STM32F103）
`templates/`	项目模板，用于快速创建新项目
`scripts/`	构建辅助脚本（generate.py, target.py）
`user/`	用户应用代码入口

四、关键文件说明

4.1 顶层配置文件

文件	说明
`Kconfig`	顶层配置入口，引用各模块的 Kconfig
`CMakeLists.txt`	顶层构建入口，管理编译依赖
`weave.yaml`	项目管理元数据
`.gitignore`	Git 版本控制忽略规则

4.2 内核关键文件

// kernel/include/os_kernel.h - 内核主接口
os_err_t os_kernel_init(void);       // 内核初始化
void os_kernel_start(void);          // 启动内核调度

4.3 驱动关键文件

// drivers/device.h - 设备基类
struct os_device {
    os_list_node_t list;           // 设备链表节点
    os_uint16_t type;              // 设备类型
    os_uint16_t flag;              // 设备标志
    char name[OS_NAME_MAX];        // 设备名称
    const struct os_device_ops *ops;  // 操作接口
    void *user_data;               // 私有数据
};

五、模块依赖关系

应用层 (demos/projects/user)
    │
    ├── 组件层 (components/*)
    │       ├── 依赖 OSAL 抽象层
    │       └── 依赖 驱动层
    │
    ├── OSAL 抽象层 (osal/*)
    │       └── 依赖 内核层
    │
    ├── 驱动层 (drivers/*)
    │       ├── 依赖 内核层
    │       └── 依赖 架构层
    │
    ├── 内核层 (kernel/*)
    │       ├── 依赖 libc
    │       └── 依赖 架构层
    │
    ├── libc
    │       └── 依赖 架构层
    │
    └── 架构层 (arch/*)
            └── 硬件平台

📝 本节小结

本节介绍了 OneOS-Lite v3.3.1 的完整目录结构和分层架构设计：

分层架构：从硬件到应用分为 6 层（架构 → libc → 内核 → 驱动 → 组件 → 应用）
多架构支持：覆盖 ARM、RISC-V、MIPS、C-SKY、LoongArch 等主流嵌入式架构
驱动框架：设备-总线-驱动三层模型，支持 30+ 种驱动类型
组件化设计：可裁剪组件，按需启用，降低资源占用
OSAL 抽象层：兼容 CMSIS/FreeRTOS/POSIX 等多种 OS API