Kconfig 配置系统¶

概述¶

The Nexus platform uses a Kconfig-based configuration system for managing build-time configuration options. This system provides a hierarchical, type-safe, and maintainable way to configure platforms, chips, peripherals, and RTOS backends.

主要特性：

层次化组织: 平台 → 芯片 → 外设 → 实例
Type Safety: Boolean, integer, string, and hexadecimal types with validation
多平台支持: 本地, STM32, GD32, ESP32, NRF52
OSAL 后端: 裸机, FreeRTOS, RT-Thread, Zephyr
自动生成：从配置生成 C 头文件
Validation Tools: Syntax checking, dependency validation, range constraints
迁移支持：版本之间的配置迁移

架构¶

配置层次结构¶

配置系统遵循四级层次结构：

Kconfig (Root)
├── Platform Selection (Native, STM32, GD32, ESP32, NRF52)
│   ├── Chip Family (STM32F4, STM32H7, STM32L4, ...)
│   │   ├── Chip Variant (STM32F407, STM32F429, ...)
│   │   └── Peripheral Configuration
│   │       ├── UART (UART1, UART2, ...)
│   │       ├── GPIO (GPIO_A, GPIO_B, ...)
│   │       ├── SPI (SPI1, SPI2, ...)
│   │       └── I2C (I2C1, I2C2, ...)
│   └── Platform-Specific Settings
├── OSAL Configuration
│   ├── Backend Selection (Bare-metal, FreeRTOS, RT-Thread, ...)
│   ├── System Parameters (Tick rate, Heap size, Stack size)
│   └── Linker Script Configuration
└── HAL Configuration
    ├── Debug Settings
    ├── Statistics
    └── Timeout Configuration

文件组织¶

nexus/
├── Kconfig                              # Root configuration file
├── .config                              # Generated configuration
│
├── platforms/
│   ├── Kconfig                          # Platform selection
│   ├── native/
│   │   ├── Kconfig                      # Native platform config
│   │   ├── defconfig                    # Default configuration
│   │   └── src/
│   │       ├── uart/Kconfig
│   │       ├── gpio/Kconfig
│   │       └── ...
│   │
│   └── STM32/
│       ├── Kconfig                      # STM32 platform config
│       ├── Kconfig_chip                 # Chip selection
│       ├── Kconfig_peripherals          # Peripheral config
│       ├── defconfig_stm32f4            # STM32F4 defaults
│       └── defconfig_stm32h7            # STM32H7 defaults
│
├── osal/
│   └── Kconfig                          # OSAL configuration
│
├── hal/
│   ├── Kconfig                          # HAL configuration
│   └── include/hal/
│       └── nexus_config.h              # Generated header
│
└── scripts/Kconfig/
    ├── generate_config.py           # Config → C header
    ├── validate_kconfig.py              # Validation tool
    ├── kconfig_migrate.py               # Migration tool
    └── kconfig_diff.py                  # Comparison tool

快速开始¶

基本配置¶

1. 选择平台:

编辑 .config 或使用 menuconfig：

CONFIG_PLATFORM_STM32=y
CONFIG_STM32F4=y
CONFIG_STM32F407=y

2. 配置外设:

CONFIG_STM32_UART_ENABLE=y
CONFIG_INSTANCE_STM32_UART_1=y
CONFIG_UART1_BAUDRATE=115200
CONFIG_UART1_MODE_DMA=y

3. 选择OSAL后端:

CONFIG_OSAL_FREERTOS=y
CONFIG_OSAL_TICK_RATE_HZ=1000
CONFIG_OSAL_HEAP_SIZE=32768

4. 生成配置:

python scripts/Kconfig/generate_config.py --config .config

This generates nexus_config.h:

#define NX_CONFIG_PLATFORM_STM32 1
#define NX_CONFIG_STM32F407 1
#define NX_CONFIG_UART1_BAUDRATE 115200
#define NX_CONFIG_OSAL_FREERTOS 1

使用默认配置¶

本地平台:

cp platforms/native/defconfig .config
python scripts/Kconfig/generate_config.py

STM32F4 平台:

cp platforms/STM32/defconfig_stm32f4 .config
python scripts/Kconfig/generate_config.py

STM32H7 平台:

cp platforms/STM32/defconfig_stm32h7 .config
python scripts/Kconfig/generate_config.py

配置工具¶

生成配置头文件¶

将 .config 文件转换为 C 头文件

# From .config file
python scripts/Kconfig/generate_config.py \
    --config .config \
    --output nexus_config.h

# Generate default configuration
python scripts/Kconfig/generate_config.py --default

验证配置¶

检查 Kconfig 语法和依赖项：

# Validate root Kconfig
python scripts/Kconfig/validate_kconfig.py Kconfig

# Validate specific file
python scripts/Kconfig/validate_kconfig.py platforms/STM32/Kconfig

验证检查

Block structure (if/endif, menu/endmenu, choice/endchoice)
源文件存在性
循环依赖
未定义的符号引用
范围 constraint violations
默认 value consistency

比较配置¶

对比两种配置之间的差异：

# Text format (default)
python scripts/Kconfig/kconfig_diff.py .config platforms/native/.config

# JSON format
python scripts/Kconfig/kconfig_diff.py \
    --format json \
    config1 config2 \
    --output diff.json

迁移配置¶

将配置迁移到新版本：

python scripts/Kconfig/kconfig_migrate.py \
    --input old.config \
    --output new.config \
    --version 2.0

生成文档¶

生成配置参考文档：

python scripts/Kconfig/generate_config_docs.py \
    Kconfig \
    --output docs/config_reference.md

统一配置工具¶

所有操作均使用 nexus_config.py：

# Generate configuration
python scripts/nexus_config.py generate

# Validate configuration
python scripts/nexus_config.py validate Kconfig

# Compare configurations
python scripts/nexus_config.py diff old.config new.config

# Migrate configuration
python scripts/nexus_config.py migrate old.config --target-version 2.0

平台配置¶

请从可用选项中选择一个平台：

choice
    prompt "Target Platform"
    default PLATFORM_NATIVE

config PLATFORM_NATIVE
    bool "Native Platform (PC Simulation)"

config PLATFORM_STM32
    bool "STM32 Platform"

config PLATFORM_GD32
    bool "GD32 Platform"

config PLATFORM_ESP32
    bool "ESP32 Platform"

config PLATFORM_NRF52
    bool "NRF52 Platform"

endchoice

STM32 平台¶

Chip Family Selection:

choice
    prompt "STM32 Chip Family"
    default STM32F4

config STM32F4
    bool "STM32F4 Series"

config STM32H7
    bool "STM32H7 Series"

config STM32L4
    bool "STM32L4 Series"

endchoice

Chip Variant:

if STM32F4

choice
    prompt "STM32F4 Chip Variant"
    default STM32F407

config STM32F407
    bool "STM32F407"

config STM32F429
    bool "STM32F429"

config STM32F446
    bool "STM32F446"

endchoice

endif

Example Configuration:

CONFIG_PLATFORM_STM32=y
CONFIG_STM32F4=y
CONFIG_STM32F407=y
CONFIG_STM32_CHIP_NAME="STM32F407xx"

外设配置¶

UART 配置¶

启用 UART:

menuconfig STM32_UART_ENABLE
    bool "Enable UART support"
    default y

配置 UART 实例:

if STM32_UART_ENABLE

menuconfig INSTANCE_STM32_UART_1
    bool "Enable UART1"
    default y

if INSTANCE_STM32_UART_1

config UART1_BAUDRATE
    int "UART1 baud rate"
    default 115200

config UART1_DATA_BITS
    int "UART1 data bits"
    default 8
    range 7 9

choice
    prompt "UART1 transfer mode"
    default UART1_MODE_DMA

config UART1_MODE_POLLING
    bool "Polling"

config UART1_MODE_INTERRUPT
    bool "Interrupt"

config UART1_MODE_DMA
    bool "DMA"

endchoice

config UART1_TX_BUFFER_SIZE
    int "UART1 TX buffer size"
    default 256
    range 16 4096

config UART1_RX_BUFFER_SIZE
    int "UART1 RX buffer size"
    default 256
    range 16 4096

endif # INSTANCE_STM32_UART_1

endif # STM32_UART_ENABLE

Example Configuration:

CONFIG_STM32_UART_ENABLE=y
CONFIG_INSTANCE_STM32_UART_1=y
CONFIG_UART1_BAUDRATE=115200
CONFIG_UART1_DATA_BITS=8
CONFIG_UART1_MODE_DMA=y
CONFIG_UART1_TX_BUFFER_SIZE=256
CONFIG_UART1_RX_BUFFER_SIZE=256

GPIO 配置¶

menuconfig NATIVE_GPIO_ENABLE
    bool "Enable GPIO support"
    default y

if NATIVE_GPIO_ENABLE

menuconfig INSTANCE_NATIVE_GPIO_A
    bool "Enable GPIO Port A"
    default y

if INSTANCE_NATIVE_GPIO_A

config GPIO_A_PIN_COUNT
    int "Number of pins in Port A"
    default 16
    range 1 32

config GPIO_A_DEFAULT_MODE
    int "Default pin mode"
    default 0
    help
      0 = Input, 1 = Output, 2 = Alternate Function

endif # INSTANCE_NATIVE_GPIO_A

endif # NATIVE_GPIO_ENABLE

OSAL 配置¶

后端选择¶

choice
    prompt "OSAL Backend"
    default OSAL_BAREMETAL

config OSAL_BAREMETAL
    bool "Bare-metal (No OS)"

config OSAL_FREERTOS
    bool "FreeRTOS"

config OSAL_RTTHREAD
    bool "RT-Thread"

config OSAL_ZEPHYR
    bool "Zephyr RTOS"

config OSAL_LINUX
    bool "Linux"

config OSAL_NATIVE
    bool "Native (PC Simulation)"

endchoice

System 参数¶

menu "System Parameters"

config OSAL_TICK_RATE_HZ
    int "System tick rate (Hz)"
    default 1000 if OSAL_FREERTOS
    default 1000 if OSAL_RTTHREAD
    default 100 if OSAL_ZEPHYR
    default 1000
    range 100 10000

config OSAL_HEAP_SIZE
    int "Heap size (bytes)"
    default 32768 if OSAL_FREERTOS
    default 32768 if OSAL_RTTHREAD
    default 16384 if OSAL_BAREMETAL
    default 65536
    range 4096 1048576

config OSAL_MAIN_STACK_SIZE
    int "Main stack size (bytes)"
    default 2048 if OSAL_FREERTOS
    default 2048 if OSAL_RTTHREAD
    default 4096 if OSAL_BAREMETAL
    default 4096
    range 512 65536

endmenu

链接脚本配置¶

menu "Linker Script Configuration"
    depends on !PLATFORM_NATIVE

config LINKER_RAM_START
    hex "RAM start address"
    default 0x20000000 if STM32F4
    default 0x24000000 if STM32H7
    default 0x20000000

config LINKER_RAM_SIZE
    hex "RAM size"
    default 0x00020000 if STM32F407
    default 0x00080000 if STM32H743
    default 0x00020000

config LINKER_FLASH_START
    hex "Flash start address"
    default 0x08000000 if PLATFORM_STM32
    default 0x08000000

config LINKER_FLASH_SIZE
    hex "Flash size"
    default 0x00100000 if STM32F407
    default 0x00200000 if STM32H743
    default 0x00100000

endmenu

HAL 配置¶

Debug 配置¶

menu "Debug Configuration"

config HAL_DEBUG_ENABLE
    bool "Enable HAL debug output"
    default n

config HAL_DEBUG_LEVEL
    int "HAL debug level"
    default 2
    range 0 4
    depends on HAL_DEBUG_ENABLE
    help
      Debug level: 0=None, 1=Error, 2=Warning, 3=Info, 4=Verbose

config HAL_ASSERT_ENABLE
    bool "Enable HAL assertions"
    default y

endmenu

Statistics 配置¶

menu "Statistics Configuration"

config HAL_STATISTICS_ENABLE
    bool "Enable HAL statistics"
    default y

config HAL_STATISTICS_BUFFER_SIZE
    int "Statistics buffer size"
    default 256
    range 64 4096
    depends on HAL_STATISTICS_ENABLE

endmenu

在代码中使用配置¶

Include Generated Header¶

#include "nexus_config.h"

条件编译¶

平台特性代码:

#ifdef NX_CONFIG_PLATFORM_STM32
    /* STM32 specific implementation */
#elif defined(NX_CONFIG_PLATFORM_GD32)
    /* GD32 specific implementation */
#endif

外设使能:

#ifdef NX_CONFIG_INSTANCE_STM32_UART_1
    /* Initialize UART1 */
    uart_init(UART1, NX_CONFIG_UART1_BAUDRATE);
#endif

Using Configuration Values¶

/* Use configuration values */
static uint8_t tx_buffer[NX_CONFIG_UART1_TX_BUFFER_SIZE];
static uint8_t rx_buffer[NX_CONFIG_UART1_RX_BUFFER_SIZE];

/* OSAL backend selection */
#if defined(NX_CONFIG_OSAL_FREERTOS)
    #include "FreeRTOS.h"
    #include "task.h"
#elif defined(NX_CONFIG_OSAL_RTTHREAD)
    #include <rtthread.h>
#elif defined(NX_CONFIG_OSAL_BAREMETAL)
    /* Bare-metal implementation */
#endif

构建系统集成¶

CMake 集成¶

配置系统已集成到 CMake 中：

# CMakeLists.txt
function(nexus_generate_config)
    set(GENERATOR_SCRIPT "${CMAKE_SOURCE_DIR}/scripts/Kconfig/generate_config.py")
    set(CONFIG_FILE "${CMAKE_SOURCE_DIR}/.config")
    set(OUTPUT_FILE "${CMAKE_SOURCE_DIR}/nexus_config.h")

    # Generate configuration header
    execute_process(
        COMMAND ${Python3_EXECUTABLE} ${GENERATOR_SCRIPT}
                --config ${CONFIG_FILE}
                --output ${OUTPUT_FILE}
        RESULT_VARIABLE RESULT
    )

    if(NOT RESULT EQUAL 0)
        message(FATAL_ERROR "Failed to generate HAL config")
    endif()
endfunction()

# Call during configuration
nexus_generate_config()

Automatic Regeneration¶

在以下情况下，配置头文件会自动重新生成：

.config 文件更改
任何 Kconfig 文件更改
CMake 配置运行

最佳实践¶

命名约定¶

平台符号：

PLATFORM_<NAME>                 # Platform selection
<PLATFORM>_<COMPONENT>_<PARAM>  # Platform-specific config

外设 instances:

INSTANCE_<PLATFORM>_<PERIPHERAL>_<N>  # Instance enable
<PERIPHERAL><N>_<PARAMETER>           # Instance parameter

示例:

PLATFORM_STM32
STM32_UART_ENABLE
INSTANCE_STM32_UART_1
UART1_BAUDRATE
UART1_MODE_DMA

配置组织¶

使用选择功能来表示互斥选项
使用 menuconfig 进行分组设置
提供合理的默认值
为所有选项添加帮助文本
对整数使用范围约束
使用依赖于条件选项

验证¶

构建之前务必验证配置

# Validate syntax
python scripts/Kconfig/validate_kconfig.py Kconfig

# Check for errors
if [ $? -ne 0 ]; then
    echo "Configuration validation failed"
    exit 1
fi

# Generate header
python scripts/Kconfig/generate_config.py

文档¶

记录所有配置选项：

config UART1_BAUDRATE
    int "UART1 baud rate"
    default 115200
    help
      Baud rate for UART1 in bits per second.
      Common values: 9600, 19200, 38400, 57600, 115200

      Note: Higher baud rates may require more accurate
      clock configuration.

故障排除¶

常见问题¶

Issue: 配置未应用*

# Regenerate configuration header
python scripts/Kconfig/generate_config.py --config .config

# Clean and rebuild
rm -rf build
CMake -B build
CMake --build build

Issue: 验证错误

# Check validation output
python scripts/Kconfig/validate_kconfig.py Kconfig

# Fix reported errors in Kconfig files

Issue: 缺失符号

# Check if symbol is defined
grep -r "config SYMBOL_NAME" .

# Verify .config has the symbol
grep "SYMBOL_NAME" .config

Issue: 默认值不起作用

# Use platform-specific defconfig
cp platforms/STM32/defconfig_stm32f4 .config

# Or generate default configuration
python scripts/Kconfig/generate_config.py --default

参见¶

贡献指南 - Contributing guidelines
移植指南 - 平台移植指南
配置指南: docs/configuration_guide.md
Kconfig 编写指南
配置参考: docs/config_reference.md

Kconfig 配置系统¶

概述¶

架构¶

配置层次结构¶

文件组织¶

快速开始¶

基本配置¶

使用默认配置¶

配置工具¶

生成配置头文件¶

验证配置¶

比较配置¶

迁移配置¶

生成文档¶

统一配置工具¶

平台 配置¶

平台配置¶

STM32 平台¶

外设配置¶

UART 配置¶

GPIO 配置¶

OSAL 配置¶

后端选择¶

System 参数¶

链接脚本配置¶

HAL 配置¶

Debug 配置¶

Statistics 配置¶

在代码中使用配置¶

Include Generated Header¶

条件编译¶

Using Configuration Values¶

构建系统集成¶

CMake 集成¶

Automatic Regeneration¶

最佳实践¶

命名约定¶

配置组织¶

验证¶

文档¶

故障排除¶

常见问题¶

参见¶

平台配置¶