Project menuconfig and Creating

Introduction

This chapter is an introduction about SDK configuration.

The first section illustrates how to configure a project in Realtek’s SDK.

The second section introduces the configure system, including Kconfig and conf files.

The third section illustrates how to create an external project, by which you can develop independently in a directory outside the Realtek SDK.

Configuring Project (menuconfig)

This section illustrates how to change project configurations with menuconfig.py.

Configuration Steps

  1. Enter the {SDK}/amebaxxx_gcc_project directory.

  2. Run the menuconfig.py command in the Windows Command Prompt or Linux Terminal.

    After successful execution of the command, the terminal will display the following UI. Users can configure settings by:

    • Using arrow keys to select the configuration options.

    • Pressing Space or Enter to toggle selection/unselection.

    • Pressing ESC to return to the previous level.

    • Pressing Q to exit.

    --------MENUCONFIG FOR General---------
CONFIG BOOT OPTION  --->
CONFIG TrustZone  --->
CONFIG Mass Production  --->
CONFIG Linux  --->
CONFIG AT CMD  --->
CONFIG RTK Assert Level  --->
CONFIG VFS  --->
CONFIG OS  --->
CONFIG OTA OPTION  --->
CONFIG USB  --->
CONFIG APPLICATION  --->
-----Connectivity Config-----
CONFIG WHC INTF  --->
CONFIG WIFI  --->
CONFIG BT  --->
CONFIG LWIP  --->
CONFIG SSL  --->
CONFIG WPAN  --->
CONFIG COEX  --->
---------Test Config---------
Verification and Test  --->
--------Build Config---------
Build Option  --->
-----end of MENUCONFIG FOR General-----
MENUCONFIG FOR KM0 CONFIG  --->
MENUCONFIG FOR KM4 CONFIG  --->
MENUCONFIG FOR CA32 CONFIG  --->
----- DO NOT ENTER IN THIS BUTTON ------
MENUCONFIG FOR Private  --->

  3. After exiting the menuconfig menu, the UI will prompt the user to save the configuration. If saved, the configuration will be stored in the menuconfig folder in the current directory.

    The folder typically contains the following items:

    • .config file: Stores the selected configuration options by the user.

    • .config_{MCU} file: Final configuration files allocated to each MCU, such as .config_km4, .config_km0, which are derived from processing the .config file.

    • project_{MCU}/platform_autoconf.h: Header files generated based on the final configuration files for C/C++ source files.

    Note

    • Each configuration result is saved to the menuconfig/.config file, which will be loaded in next UI menuconfig session.

    • When opening menuconfig UI for configuration, the records of last configurations will be display, meaning that configuring through UI is persistent.

Initial Configuration

Project configurations are parsed from menuconfig/.config. However, when the project does not contain a menuconfig/.config file, indicating an empty configuration, initial configuration will be loaded automatically.

Configuration flow is shown as below:

../../_images/kconfig_flow.png

The related configuration files:

  • amebaxxx_gcc_project/default.conf records the default configuration options required for this SOC model and serves as the initial configuration value for the SOC project.

  • prj.conf has a higher priority than amebaxxx_gcc_project/default.conf :

    • When running the command build.py -a with an example, the prj.conf file (if any) in the example directory will take effect as a part of the initial configuration.

    • When building an external project, the prj.conf file in the external directory will take effect。

  • Kconfig : for the undefined items in default.conf and prj.conf, the default values defined in Kconfig will be used as the initial values.

  • user.conf is the user defined configuration file, which can be used for saving a combination of items. It will replace the prj.conf file (if any) as a part of the initial configuration when the command menuconfig.py -f is run. For more information about the conf files, please refer to Introduction to conf Files.

Note

When the Kconfig file or default.conf file is updated (e.g., pulled from a remote repository), but the files in the menuconfig folder are still based on the previous Kconfig, running build.py directly can lead to unexpected behavior. To prevent this, a check for Kconfig updates is performed before each compilation.

A menuconfig/.config_default file will be generated based on the latest initial configuration files. If the newly generated menuconfig/.config_default differs from the existing one, the console will display the differences and prompt the user to decide:

  • If user determines that the Kconfig update can be ignored, press Enter to continue using the current .config configuration.

  • If user believes ignoring the Kconfig update may affect the compilation results, press Ctrl+C to exit. After exiting, the user can reconfigure using the visualization interface or via menuconfig.py -f, or clean the menuconfig folder using menuconfig.py -c or build.py -p, and then compile using the default configuration.

Configuration Commands

The usage of the menuconfig.py script are shown in the following table.

Function

command

Description

Help

menuconfig.py -h

List supported commands

Manual Configuration

menuconfig.py

Open menuconfig visualization interface

Save as a .conf file

menuconfig.py -s <name>.conf

Save current configuration as a .conf file

Import .conf files

menuconfig.py -f <name>.conf

Configuring using conf files

Cleanup

menuconfig.py -c

Clean configure and build products (if any)

Note

  • Before executing -f, the menuconfig folder will be automatically deleted. Therefore, the configuration results after -f execution will not be influenced by the previous .config file, meaning this -f configuration method is non-persistent.

  • Executing -f will automatically load default.conf as the first input file. The prj.conf will not work if it is not specified with -f .

  • Multiple .conf files can be imported via -f. If there are identical configuration items among them, the latter will overwrite the former, that is, the configuration items in the last file will take effect.

  • -c will simultaneously clean up the current configuration (the ‘menuconfig’ folder) and the build product (if any, by default in the ‘build’ folder).

Configure System

Kconfig Overview

This section will introduce the organizational structure of Kconfig, and how a configuration item is defined in Kconfig.

Organization Structure

The configuration system uses Kconfig to organize. Top Kconfig file under amebaxxx_gcc_project references sub-Kconfig under each component, as the following figure shows. For more detailed information about Kconfig, please refer to: https://docs.kernel.org/kbuild/kconfig-language.html

../../_images/kconfig_tree.svg

When the user runs menuconfig.py , a .config file will be generated, where the configuration items are saved. After processed by scripts, the files named .config_xxx used by CMake and the header files platform_autoconf.h used by C code are generated.

Defining Kconfig Symbols

Defining a Kconfig symbol follows the below format:

config FOO
   bool "choose FOO"
   default n

The above Kconfig structure defines a bool type config symbol named FOO with a default value n , which appears in the menuconfig visualization interface as:

[ ]  choose FOO

  • "choose FOO" is the prompt text, which will be displayed in the visualization configuration interface. If "choose FOO" is removed, the configuration item will not appear in the visualization interface. Besides bool type, other types such as string, hex, int, etc., can also be defined.

  • default n indicates “no”, meaning this item will not be selected by default. default n can be omitted. Note that the default value defined by default only takes effect if the user has never touched this config item.

  • If multiple default values are defined within the same config, then the first valid default value encountered will be used.

  • The above config symbol will be parsed as CONFIG_FOO in the .config file.

Introduction to conf Files

This section introduces the format of conf files and the related several conf files.

Conf files replace the UI-based menuconfig approach by writing user-defined configuration items into them. Similar to UI menuconfig, this direct configuration method essentially selects/deselects some items defined in Kconfig files, replacing interactive input with parameter input.

conf File Format

Conf files consist of multiple configuration items, each following this format:

CONFIG_<name1>=<value>

CONFIG_<name2>=<value>

...

There should be no spaces around the = sign.

default.conf

  • In {SDK}/amebaxxx_gcc_project directory, there is a configuration file named default.conf, defining the initial configuration for building this SOC project.

  • Specifically, menuconfig.py -f implicitly includes the rule of menuconfig.py -f default.conf, so when users write conf files, they can omit config items already configured in the default.conf file, meaning they only need to write incremental configurations compared to default.conf. If certain options in default.conf need to be disabled, set the corresponding config items to n.

  • Default values in Kconfig only take effect if a specific config item is not touched, while default.conf files act as a series of default inputs, thus having higher priority than default values in Kconfig.

prj.conf

  • prj.conf is located under example or the user-created external project, recording the configuration items needed for this example or external project. Users can configure the project using menuconfig.py -f /.../prj.conf. Additionally, when users have not configured through the UI or specified other conf files, prj.conf will be used as the initial configuration.

  • The priority of prj.conf is higher than that of default.conf.

user.conf

  • user.conf is created by user.

  • You can manually edit it, or run menuconfig.py to configure manually then menuconfig.py -s to save the result as a <name>.conf file.

    menuconfig.py -s <name>.conf

  • One or more .conf files can be imported by menuconfig.py -f . If there are identical configuration items in multiple conf files, as shown following, the priority of <name2>.conf will be higher than <name1>.conf. For example, if <name1>.conf defines CONFIG_BT_MENU=y and <name2>.conf defines CONFIG_BT_MENU=n, then CONFIG_BT_MENU=n will ultimately take effect.

    menuconfig.py -f <name1>.conf <name2>.conf ...

Note

Users can save the current configuration as a conf file using menuconfig.py -s , then import it using menuconfig.py -f .

Creating External Project

You can develop and configure in the default project directory provided by Realtek. You can also create a separate external project based on a certain example, then develop and configure in the external project directory.

The previous section introduced how to configure and build under amebaxxx_gcc_project directory, where users develop their projects within the Realtek-provided SDK. However, in some scenarios, users wish to create independent project directories separate from the Realtek SDK, making it easier to maintenance, updates, or co-develop their project. The following section introduces the development mode based on external projects.

1. Creating Command

Navigate to the corresponding GCC project path of the SOC and run:

cd {SDK}/amebaxxx_gcc_project

build.py --new <project_dir> [-a <APP_NAME>]

This will create a new project in the project_dir path using APP_NAME as a template from the examples. For example:

build.py --new ~/my_project -a http_client

The created project directory includes:

  • ameba.bat, ameba.sh: Users can use these scripts to set environment variables.

  • menuconfig.py, build.py: Used for configuring and compiling the project.

  • CMakeLists.txt: The entry file for compiling this new project.

  • Kconfig: Users can add their own configuration options here.

  • <APP_NAME> folder: Files specified by the template will be copied into this folder.

  • prj.conf: Used to record the default configuration of the project.

  • manifest.json5: Used to configure firmware security features.

2. Setting Up Environment in the Created Project Directory

The ameba.bat and ameba.sh scripts in the project directory reference the scripts in the root directory of Realtek SDK. Users can set up the environment using any script.

3. Configuring in the Created Project Directory

The usage is the same as the commands described in Configuring Project. The generated menuconfig folder will be created in this project directory.

4. Compiling in the Created Project Directory

The usage is the same as the commands described in Build Commands. The generated build folder will be created in this project directory.