Kconfig Tools API

概述

The Kconfig tools provide Python APIs for managing configuration files, validating Kconfig syntax, and generating C header files.

模块: generate_hal_config

配置 Header Generation

generate_header(config_dict, output_file=None)

生成 C header file from configuration dictionary.

参数:

  • config_dict (dict) -- 配置 key-value pairs

  • output_file (str) -- Output file path (optional)

返回:

生成d header content as 字符串

返回类型:

str

示例:

from generate_hal_config import generate_header

config = {
    'CONFIG_PLATFORM_STM32': 'y',
    'CONFIG_UART1_BAUDRATE': '115200',
    'CONFIG_OSAL_FREERTOS': 'y'
}

header = generate_header(config, 'nexus_config.h')
parse_config_file(config_path)

Parse .config file and return configuration dictionary.

参数:

config_path (str) -- Path to .config file

返回:

配置 dictionary

返回类型:

dict

示例:

from generate_hal_config import parse_config_file

config = parse_config_file('.config')
print(f"Platform: {config.get('CONFIG_PLATFORM_NAME')}")
generate_default_config(platform=None)

生成 default configuration for specified platform.

参数:

platform (str) -- Platform name (native, STM32, GD32, etc.)

返回:

默认配置 dictionary

返回类型:

dict

示例:

from generate_hal_config import generate_default_config

# Generate default for STM32
config = generate_default_config('STM32')

# Generate default for current platform
config = generate_default_config()

模块: validate_kconfig

Kconfig 验证

class KconfigValidator(root_dir='.')

Validator for Kconfig files.

参数:

root_dir (str) -- Root directory for resolving paths

validate_file(kconfig_path, is_included=False)

验证 a single Kconfig file.

参数:

  • kconfig_path (Path) -- Path to Kconfig file

  • is_included (bool) -- Whether file is included via source/rsource

返回:

Tuple of (errors, warnings)

返回类型:

tuple[list[str], list[str]]

示例:

from pathlib import Path
from validate_kconfig import KconfigValidator

validator = KconfigValidator('.')
errors, warnings = validator.validate_file(Path('Kconfig'))

if errors:
    print(f"Errors: {errors}")
if warnings:
    print(f"Warnings: {warnings}")
validate_all(kconfig_file)

验证 Kconfig file and all included files.

参数:

kconfig_file (Path) -- Root Kconfig file path

返回:

True if 验证 passed, False otherwise

返回类型:

bool

示例:

from pathlib import Path
from validate_kconfig import KconfigValidator

validator = KconfigValidator('.')
success = validator.validate_all(Path('Kconfig'))

if not success:
    validator.print_results()
validate_dependencies()

验证 dependencies and selects.

返回:

Tuple of (errors, warnings)

返回类型:

tuple[list[str], list[str]]

validate_ranges()

验证 范围约束 and default values.

返回:

Tuple of (errors, warnings)

返回类型:

tuple[list[str], list[str]]

print_results()

Print 验证 results to stdout.

errors

List of 验证 errors.

类型:

list[str]

warnings

List of 验证 warnings.

类型:

list[str]

symbols

Dictionary of parsed configuration symbols.

类型:

dict[str, dict]

dependencies

Dictionary of symbol dependencies.

类型:

dict[str, set[str]]

模块: kconfig_migrate

配置 Migration

migrate_config(input_file, output_file, target_version=None)

迁移 configuration file to new version.

参数:

  • input_file (str) -- Input configuration file path

  • output_file (str) -- Output configuration file path

  • target_version (str) -- 目标 version (optional)

返回:

True if migration succeeded

返回类型:

bool

示例:

from kconfig_migrate import migrate_config

success = migrate_config(
    'old.config',
    'new.config',
    target_version='2.0'
)

if success:
    print("Migration completed successfully")
detect_version(config_file)

Detect configuration file version.

参数:

config_file (str) -- 配置 file path

返回:

Version 字符串 or None

返回类型:

str or None

get_symbol_mapping(from_version, to_version)

Get symbol mapping 版本之间.

参数:

  • from_version (str) -- Source version

  • to_version (str) -- 目标 version

返回:

符号 mapping dictionary

返回类型:

dict[str, str]

模块: kconfig_diff

配置 Comparison

diff_configs(config1_path, config2_path, format='text')

Compare two configuration files.

参数:

  • config1_path (str) -- First configuration file path

  • config2_path (str) -- Second configuration file path

  • format (str) -- Output format ('text' or 'json')

返回:

Difference report

返回类型:

str or dict

示例:

from kconfig_diff import diff_configs

# Text format
diff_text = diff_configs('.config', 'platforms/native/.config')
print(diff_text)

# JSON format
diff_json = diff_configs(
    '.config',
    'platforms/native/.config',
    format='json'
)
parse_config(config_path)

Parse configuration file.

参数:

config_path (str) -- 配置 file path

返回:

配置 dictionary

返回类型:

dict

format_diff_text(diff_dict)

Format difference dictionary as text.

参数:

diff_dict (dict) -- Difference dictionary

返回:

Formatted text

返回类型:

str

format_diff_json(diff_dict)

Format difference dictionary as JSON.

参数:

diff_dict (dict) -- Difference dictionary

返回:

JSON 字符串

返回类型:

str

模块: generate_config_docs

文档生成

generate_docs(kconfig_file, output_file=None, format='markdown')

生成 documentation from Kconfig files.

参数:

  • kconfig_file (str) -- Root Kconfig file path

  • output_file (str) -- Output file path (optional)

  • format (str) -- Output format ('markdown' or 'rst')

返回:

生成d documentation

返回类型:

str

示例:

from generate_config_docs import generate_docs

# Generate markdown documentation
docs = generate_docs('Kconfig', 'config_reference.md')

# Generate reStructuredText
docs = generate_docs('Kconfig', 'config_reference.rst', format='rst')
extract_config_options(kconfig_file)

Extract all configuration options from Kconfig file.

参数:

kconfig_file (str) -- Kconfig file path

返回:

List of configuration options

返回类型:

list[dict]

format_option_markdown(option)

Format configuration option as markdown.

参数:

option (dict) -- 配置 option dictionary

返回:

Formatted markdown

返回类型:

str

format_option_rst(option)

Format configuration option as reStructuredText.

参数:

option (dict) -- 配置 option dictionary

返回:

Formatted reStructuredText

返回类型:

str

命令行接口

nexus_config.py

Unified configuration management tool.

用法:

python scripts/nexus_config.py <command> [options]

Commands:

  • generate - 生成 configuration header file

  • validate - 验证 Kconfig files

  • migrate - 迁移 configuration to new version

  • diff - 比较配置文件

  • info - 显示配置信息

生成 Command:

python scripts/nexus_config.py generate [options]

Options:
  -c, --config FILE    Input configuration file
  -o, --output FILE    Output header file
  -d, --default        Generate default configuration
  -p, --platform NAME  Platform name for default config

验证 Command:

python scripts/nexus_config.py validate [kconfig_file]

Arguments:
  kconfig_file         Root Kconfig file (default: Kconfig)

迁移 Command:

python scripts/nexus_config.py migrate input_file [options]

Arguments:
  input_file           Input configuration file

Options:
  -o, --output FILE    Output configuration file
  -t, --target-version VERSION  Target version

Diff Command:

python scripts/nexus_config.py diff config1 config2 [options]

Arguments:
  config1              First configuration file
  config2              Second configuration file

Options:
  -f, --format FORMAT  Output format (text or json)
  -o, --output FILE    Output file

数据结构

配置 Dictionary

配置 dictionaries map symbol names to values:

{
    'CONFIG_PLATFORM_STM32': 'y',
    'CONFIG_STM32F407': 'y',
    'CONFIG_UART1_BAUDRATE': '115200',
    'CONFIG_UART1_MODE_DMA': 'y',
    'CONFIG_OSAL_FREERTOS': 'y',
    'CONFIG_OSAL_TICK_RATE_HZ': '1000'
}

符号 Information

Symbol information dictionaries contain metadata:

{
    'name': 'UART1_BAUDRATE',
    'type': 'int',
    'default': '115200',
    'range': (9600, 921600),
    'help': 'Baud rate for UART1',
    'file': 'platforms/STM32/src/uart/Kconfig',
    'line': 42
}

验证 Results

验证 results contain errors and warnings:

{
    'errors': [
        'Kconfig:10: Unclosed if block',
        'platforms/STM32/Kconfig:25: Undefined symbol INVALID_SYMBOL'
    ],
    'warnings': [
        'platforms/native/Kconfig:15: default outside of config block'
    ]
}

Difference Report

Difference reports show configuration changes:

{
    'added': {
        'CONFIG_NEW_FEATURE': 'y'
    },
    'removed': {
        'CONFIG_OLD_FEATURE': 'y'
    },
    'changed': {
        'CONFIG_UART1_BAUDRATE': {
            'old': '9600',
            'new': '115200'
        }
    },
    'unchanged': {
        'CONFIG_PLATFORM_STM32': 'y'
    }
}

错误处理

异常

exception KconfigError

Base exception for Kconfig-related errors.

exception ValidationError

Raised when 验证 fails.

exception ParseError

Raised when parsing fails.

exception GenerationError

Raised when header generation fails.

示例:

from validate_kconfig import KconfigValidator, ValidationError

try:
    validator = KconfigValidator('.')
    success = validator.validate_all(Path('Kconfig'))
    if not success:
        raise ValidationError("Validation failed")
except ValidationError as e:
    print(f"Error: {e}")
    validator.print_results()

最佳实践

验证

Always validate before generating:

from pathlib import Path
from validate_kconfig import KconfigValidator
from generate_hal_config import generate_header, parse_config_file

# Validate first
validator = KconfigValidator('.')
if not validator.validate_all(Path('Kconfig')):
    print("Validation failed!")
    validator.print_results()
    exit(1)

# Then generate
config = parse_config_file('.config')
generate_header(config, 'nexus_config.h')

错误处理

Handle errors gracefully:

try:
    config = parse_config_file('.config')
except FileNotFoundError:
    print("Config file not found, using defaults")
    config = generate_default_config()
except Exception as e:
    print(f"Error parsing config: {e}")
    exit(1)

日志记录

Use logging for debugging:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

validator = KconfigValidator('.')
logger.debug("Starting validation")
success = validator.validate_all(Path('Kconfig'))
logger.info(f"Validation {'passed' if success else 'failed'}")

另请参阅