2.2 Kconfig 配置系统

学习阁2026/7/19大约 5 分钟项目结构构建系统Kconfig配置

2.2 Kconfig 配置系统

📚 本节导读

学习时长：约 25 分钟
难度级别：⭐⭐☆☆☆
前置知识：第 2.1 节项目目录结构

🎯 学习目标

理解 Kconfig 配置系统的作用和设计理念
掌握 OneOS-Lite 的 Kconfig 配置层级结构
学会阅读和修改 Kconfig 配置文件
了解典型配置项及含义

一、Kconfig 概述

Kconfig 是 Linux 内核引入的配置系统，OneOS-Lite 采用相同的机制来管理项目的可配置选项。通过 Kconfig，开发者可以：

按需裁剪：只编译需要的功能，减小固件体积
图形化配置：使用 menuconfig 工具进行可视化配置
依赖管理：自动处理配置项之间的依赖关系
条件编译：根据配置宏决定编译哪些代码

二、配置层级结构

2.1 顶层配置入口

OneOS-Lite 的配置从根目录 Kconfig 文件开始，逐层引用各模块的配置：

Kconfig (根目录)
├── source "arch/Kconfig"         # 架构配置
├── source "kernel/Kconfig"       # 内核配置
├── source "libc/Kconfig"         # C 库配置
├── source "osal/Kconfig"         # OSAL 抽象层配置
├── source "drivers/Kconfig"      # 驱动配置
├── source "components/Kconfig"   # 组件配置
└── source "demos/Kconfig"        # 示例配置

2.2 顶层 Kconfig 源码

# Kconfig (项目根目录)
source "$OS_ROOT/arch/Kconfig"
source "$OS_ROOT/kernel/Kconfig"
source "$OS_ROOT/libc/Kconfig"
source "$OS_ROOT/osal/Kconfig"
source "$OS_ROOT/drivers/Kconfig"
source "$OS_ROOT/components/Kconfig"
source "$OS_ROOT/demos/Kconfig"

menu "Debug"
    config OS_DEBUG
        bool "Enable debug"
        select OS_USING_CONSOLE
        default y
        help
            dlog, assert and kernel log depends on this config option

    config OS_USING_SIMPLE_EXCEPTION
        bool "Enable Simple Exception"
        default n
        help
            There is only a while(1) for exception handling,
            which reduces the code for exception handling.
endmenu

三、Kconfig 配置语法

3.1 基本配置类型

类型	语法	说明
`bool`	`config XX\n bool "描述"`	布尔开关（y/n）
`tristate`	`config XX\n tristate "描述"`	三态（y/n/m，模块编译）
`int`	`config XX\n int "描述"`	整数值
`hex`	`config XX\n hex "描述"`	十六进制值
`string`	`config XX\n string "描述"`	字符串
`choice`	`choice ... endchoice`	多选一

3.2 依赖关系

# depends on - 前置依赖
config OS_USING_SEM
    bool "Enable semaphore"
    depends on OS_USING_IPC
    default y
    help
        Using semaphore for task synchronization.

# select - 自动选中
config OS_USING_CONSOLE
    bool "Enable console"
    select OS_USING_SERIAL
    default y

3.3 菜单和注释

menu "Task Management"
    config OS_TASK_PRIORITY_MAX
        int "Maximum task priority"
        range 8 256
        default 32
        help
            Define the maximum task priority in system.

    config OS_TASK_NAME_MAX
        int "Maximum task name length"
        range 8 32
        default 16
endmenu

comment "Memory Management Options"

四、各模块配置详解

4.1 内核配置 (`kernel/Kconfig`)

内核配置是最大的配置模块，包含任务、内存、IPC、定时器等子菜单。

配置项	类型	默认值	说明
`OS_TASK_PRIORITY_MAX`	int	32	最大任务优先级数
`OS_TASK_NAME_MAX`	int	16	任务名最大长度
`OS_USING_HEAP`	bool	y	启用动态堆内存
`OS_HEAP_SIZE`	int	8192	堆内存大小（字节）
`OS_USING_SEM`	bool	y	启用信号量
`OS_USING_MUTEX`	bool	y	启用互斥锁
`OS_USING_EVENT`	bool	y	启用事件
`OS_USING_MQ`	bool	y	启用消息队列
`OS_USING_MB`	bool	y	启用邮箱
`OS_USING_TIMER`	bool	y	启用软件定时器
`OS_USING_SPINLOCK`	bool	n	启用自旋锁（多核）

4.2 架构配置 (`arch/Kconfig`)

choice
    prompt "CPU Architecture"
    default ARCH_ARM

    config ARCH_ARM
        bool "ARM"
    config ARCH_RISCV
        bool "RISC-V"
    config ARCH_MIPS
        bool "MIPS"
    config ARCH_CSKY
        bool "C-SKY"
    config ARCH_LOONGARCH
        bool "LoongArch"
    config ARCH_SIM
        bool "Simulator"
endchoice

4.3 组件配置 (`components/Kconfig`)

source "components/fs/Kconfig"
source "components/net/Kconfig"
source "components/security/Kconfig"
source "components/shell/Kconfig"
source "components/dlog/Kconfig"
source "components/atest/Kconfig"
source "components/DBoT/Kconfig"
source "components/ota/Kconfig"
source "components/position/Kconfig"

4.4 驱动配置 (`drivers/Kconfig`)

配置项	类型	说明
`OS_USING_PIN`	bool	启用 GPIO 引脚驱动
`OS_USING_SERIAL`	bool	启用串口驱动
`OS_USING_I2C`	bool	启用 I2C 总线
`OS_USING_SPI`	bool	启用 SPI 总线
`OS_USING_TIMER_DRV`	bool	启用硬件定时器
`OS_USING_WATCHDOG`	bool	启用看门狗
`OS_USING_RTC`	bool	启用实时时钟
`OS_USING_CAN`	bool	启用 CAN 总线
`OS_USING_SENSOR`	bool	启用传感器框架
`OS_USING_DMA`	bool	启用 DMA 控制器

五、使用 menuconfig 进行配置

5.1 图形化配置

# 进入项目目录，启动 menuconfig
cd projects/stm32f103zet6-atk-elite
make menuconfig

menuconfig 界面提供：

菜单导航：使用方向键浏览配置项
空格键切换：切换 bool 类型配置项
回车键进入：进入子菜单
? 键查看帮助：查看当前配置项说明
保存退出：生成的 .config 文件

5.2 生成的配置文件

经过 menuconfig 配置后，会生成 .config 文件，并最终转换为 os_cfg.h 头文件：

Kconfig 文件
    ↓ (menuconfig 工具)
.config 文件
    ↓ (转换为 C 宏)
os_cfg.h 头文件
    ↓ (编译时使用)
条件编译 (#ifdef OS_USING_SEM)

5.3 典型配置示例

// os_cfg.h - 自动生成的配置头文件
#define OS_TASK_PRIORITY_MAX    32
#define OS_TASK_NAME_MAX        16
#define OS_USING_HEAP
#define OS_USING_SEM
#define OS_USING_MUTEX
#define OS_USING_EVENT
#define OS_USING_MQ
#define OS_USING_TIMER
#define OS_USING_CONSOLE
#define OS_USING_SERIAL
#define OS_USING_PIN
#define OS_USING_I2C
#define OS_USING_SPI

六、典型场景配置

6.1 最小系统配置（资源受限）

配置项	建议值	说明
`OS_TASK_PRIORITY_MAX`	8	减少优先级位图大小
`OS_TASK_NAME_MAX`	8	缩短任务名
`OS_USING_HEAP`	n	不使用动态内存
`OS_USING_TIMER`	n	不使用软件定时器
`OS_USING_CONSOLE`	n	不启用控制台

6.2 标准 IoT 设备配置

配置项	建议值	说明
`OS_TASK_PRIORITY_MAX`	32	标准优先级
`OS_USING_HEAP`	y	启用动态内存
`OS_USING_SEM`	y	启用信号量
`OS_USING_MUTEX`	y	启用互斥锁
`OS_USING_MQ`	y	启用消息队列
`OS_USING_CONSOLE`	y	启用控制台调试
`OS_USING_SERIAL`	y	启用串口

📝 本节小结

本节介绍了 OneOS-Lite 的 Kconfig 配置系统：

分层配置：顶层 Kconfig 逐层引用各模块配置
配置类型：支持 bool/int/string/choice 等多种类型
依赖关系：depends on 和 select 实现配置联动
menuconfig 工具：图形化界面简化配置操作
配置生成：.config → os_cfg.h → 条件编译