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.

Configuring Project (menuconfig)

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

Configuration Steps

Set up the environment: source path/to/your/sdk/env.sh (on Windows, execute env.bat)

Run the ameba.py menuconfig 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 SHELL  --->
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  --->

After exiting the menuconfig menu, the UI will prompt the user to save the configuration. If saved, the configuration will be stored in the build_RTLxxx/menuconfig folder in the current directory, where RTLxxx represents the current SoC model.

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:

The related configuration files:

component/soc/amebaxxx/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 component/soc/amebaxxx/project/default.conf :
- When running the command ameba.py build -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 ameba.py menuconfig -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 ameba.py build 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 ameba.py menuconfig -f, or clean the menuconfig folder using ameba.py menuconfig -c or ameba.py build -p, and then compile using the default configuration.

Configuration Commands

ameba.py menuconfig command wraps the underlying script tools/scripts/menuconfig.py.

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

Function	Command	Description
Help	`ameba.py menuconfig -h`	List supported commands
Manual Configuration	`ameba.py menuconfig`	Open menuconfig visualization interface
Save as a .conf file	`ameba.py menuconfig -s <name>.conf`	Save current configuration as a .conf file
Import .conf files	`ameba.py menuconfig -f <name>.conf`	Configuring using conf files
Cleanup	`ameba.py menuconfig -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 component/soc/amebaxxx/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

When the user runs ameba.py menuconfig , 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}/component/soc/amebaxxx/project directory, there is a configuration file named default.conf, defining the initial configuration for building this SOC project.

Specifically, ameba.py menuconfig -f implicitly includes the rule of ameba.py menuconfig -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 ameba.py menuconfig -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 ameba.py menuconfig to configure manually then ameba.py menuconfig -s to save the result as a <name>.conf file.
ameba.py menuconfig -s <name>.conf
One or more .conf files can be imported by ameba.py menuconfig -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.
ameba.py menuconfig -f <name1>.conf <name2>.conf ...

Note

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