Common Configuration#

You can configure the Common module to define how the module will behave, what resources it requires, and so on. The configuration options take effect at compile-time.

You can also change run-time configurations that will tailor the Common module to the needs of the application, while using a minimum of resources when it not needed. The following pages describe both types of configurations.

RTOS Compile-Time Description#

RTOS Description#

The following configuration constants can be added to the rtos_description.h file.

CPU & Toolchain - Mandatory Constant Description#

CPU & Toolchain - Mandatory Constant Description

Modules Present Description#

The following is a list of #define to be added to rtos_description.h to activate the modules and its sub-modules.

#define

RTOS_MODULE_KERNEL_AVAIL

RTOS_MODULE_COMMON_SHELL_AVAIL

RTOS_MODULE_USB_HOST_AVAIL

RTOS_MODULE_USB_HOST_CDC_AVAIL

RTOS_MODULE_USB_HOST_ACM_AVAIL

RTOS_MODULE_USB_HOST_AOAP_AVAIL

RTOS_MODULE_USB_HOST_USB2SER_AVAIL

RTOS_MODULE_USB_HOST_USB2SER_FTDI_AVAIL

RTOS_MODULE_USB_HOST_USB2SER_SILABS_AVAIL

RTOS_MODULE_USB_HOST_USB2SER_PROLIFIC_AVAIL

RTOS_MODULE_USB_HOST_MSC_AVAIL

RTOS_MODULE_USB_HOST_HID_AVAIL

RTOS_MODULE_USB_DEV_AVAIL

RTOS_MODULE_USB_DEV_AUDIO_AVAIL

RTOS_MODULE_USB_DEV_CDC_AVAIL

RTOS_MODULE_USB_DEV_ACM_AVAIL

RTOS_MODULE_USB_DEV_EEM_AVAIL

RTOS_MODULE_USB_DEV_HID_AVAIL

RTOS_MODULE_USB_DEV_MSC_AVAIL

RTOS_MODULE_USB_DEV_VENDOR_AVAIL

RTOS_MODULE_FS_AVAIL

RTOS_MODULE_FS_STORAGE_NAND_AVAIL

RTOS_MODULE_FS_STORAGE_NOR_AVAIL

RTOS_MODULE_FS_STORAGE_RAM_DISK_AVAIL

RTOS_MODULE_FS_STORAGE_SCSI_AVAIL

RTOS_MODULE_FS_STORAGE_SD_CARD_AVAIL

RTOS_MODULE_FS_STORAGE_SD_SPI_AVAIL

RTOS_MODULE_IO_SERIAL_AVAIL

RTOS_MODULE_IO_SERIAL_SPI_AVAIL

RTOS_MODULE_NET_AVAIL

RTOS_MODULE_NET_IF_ETHER_AVAIL

RTOS_MODULE_NET_IF_WIFI_AVAIL

RTOS_MODULE_NET_SSL_TLS_AVAIL

RTOS_MODULE_NET_SSL_TLS_MOCANA_NANOSSL_AVAIL

RTOS_MODULE_NET_SSL_TLS_MBEDTLS_AVAIL

RTOS_MODULE_NET_HTTP_CLIENT_AVAIL

RTOS_MODULE_NET_HTTP_SERVER_AVAIL

RTOS_MODULE_NET_TELNET_SERVER_AVAIL

RTOS_MODULE_NET_MQTT_CLIENT_AVAIL

RTOS_MODULE_NET_SMTP_CLIENT_AVAIL

RTOS_MODULE_NET_SNTP_CLIENT_AVAIL

RTOS_MODULE_NET_IPERF_AVAIL

RTOS_MODULE_NET_FTP_CLIENT_AVAIL

RTOS_MODULE_NET_TFTP_CLIENT_AVAIL

RTOS_MODULE_NET_TFTP_SERVER_AVAIL

RTOS Compile-Time Configuration#

RTOS Configuration#

The following configuration constants are located in the rtos_cfg.h file.

Asserts configurations#

RTOSCFG_ASSERT_DBG_ARG_CHK_EXT<module>_EN configurations define if asserts that are used in argument checking are enabled or not. These asserts check the validity of the arguments passed to any stack function. This can include checking whether a pointer is non-NULL, or if a given value is within a certain range, or if a configuration is valid, etc.

These configurations ca be set to 1 (enable asserts) or 0 (disable asserts).

There is one configuration per module. The following table lists the different configurations.

Recommendation: disable this feature as much as possible in 'release' code. This will improve performance and reduce the amount of code space required.

Configuration

Description

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_APP_EN

Controls asserts located in sample applications.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_BSP_EN

Controls asserts located in BSPs.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_CAN_EN

Controls asserts located in CAN module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_COMMON_EN

Controls asserts located in common module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_CPU_EN

Controls asserts located in CPU module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_FS_EN

Controls asserts located in File System module

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_KERNEL_EN

Controls asserts located in the real-time kernel.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_NET_EN

Controls asserts located in network module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_NET_APP_EN

Controls asserts located in network application modules.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_USBD_EN

Controls asserts located in USB device module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_USBH_EN

Controls asserts located in USB host module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_IO_EN

Controls asserts located in IO module.

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_PROBE_EN

Controls asserts located in uc/Probe drivers.

RTOS_CFG_RTOS_ASSERT_DBG_FAILED_END_CALL_SEL#

RTOS_CFG_RTOS_ASSERT_DBG_FAILED_END_CALL_SEL

RTOS_CFG_RTOS_ASSERT_CRITICAL_FAILED_END_CALL_SEL#

RTOS_CFG_RTOS_ASSERT_CRITICAL_FAILED_END_CALL_SEL

Table - Assert failed end call configuration value description#

Table - Assert failed end call configuration value description

RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN#

RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN

RTOS Logging Configuration#

Table - RTOS Logging Configuration Constants#

Table - RTOS Logging Configuration Constants

Logging Channel Configuration#

The logging mechanism allows every logging channel to inherit from the parent channel, with the root ancestor being the RTOS_CFG_LOG_ALL channel. This allows any channel option to have the DFLT setting, which means it uses the inherited channel option.

The "parent-child" relationship is defined by finding the channel to where a particular module is logging. For example, the kernel logs in the KERNEL channel and the USB-Device Audio class would log to the USBD, CLASS, AUDIO channel. This would mean that the kernel channel inherits only from the root parent ALL and that the USB-Device Audio class would inherit from (in order):

  • The USBD_CLASS channel if defined

  • The USBD channel if defined and the root parent ALL

For the USB-Device Audio class channel, this means that if a #define named RTOS_CFG_LOG_USBD_CLASS does exist, it will take the options set via that configuration as default. If not, it could take its options from a RTOS_CFG_LOG_USBD #define. If it is also not present, it will set the options in the RTOS_CFG_LOG_ALL #define.

This allows a very fine granularity while allowing to configure several channels in a single step.

The available options for each channel #define must respect the order and be separated by commas. The order should be as follows: <lowest_level>, <timing>, <function_name_en>, <time_stamp_en>, <log_output_funct>. The possible values for each option are as follows:

Table - RTOS Logging Channel Options#

Table - RTOS Logging Channel Options

Major Logging Channels#

The table below presents the major logging channels that can be referenced when configuring the logging module. Several other channels exist, for example for each FS or USB driver (FS, DRV, SD; USBD, DRV, SYNOPSYS_OTG_HS or USBH, HCD, EHCI).

Comma notation (as seen in source code files)

#define used to configure the channel

Description

COMMON

RTOS_CFG_LOG_COMMON

Common's root logging channel

COMMON, LIB

RTOS_CFG_LOG_COMMON_LIB

Common's LIB module logging channel

COMMON, SHELL

RTOS_CFG_LOG_COMMON_SHELL

Common's Shell module logging channel

FS

RTOS_CFG_LOG_FS

File System's root logging channel

FS, BLK_DEV

RTOS_CFG_LOG_FS_BLK_DEV

File System's Block Device layer logging channel

FS, CORE

RTOS_CFG_LOG_FS_CORE

File System's Core layer logging channel

FS, DRV

RTOS_CFG_LOG_FS_DRV

File System's Driver layer logging channel

FS, FAT

RTOS_CFG_LOG_FS_FAT

File System's FAT layer logging channel

FS, MEDIA

RTOS_CFG_LOG_FS_MEDIA

File System's Media layer logging channel

FS, STORAGE

RTOS_CFG_LOG_FS_STORAGE

File System's Storage layer logging channel

KERNEL

RTOS_CFG_LOG_KERNEL

Kernel's logging channel

NET

RTOS_CFG_LOG_NET

Network's root logging channel

NET, DNS

RTOS_CFG_LOG_NET_DNS

Network's DNS Application logging channel

NET, DHCP

RTOS_CFG_LOG_NET_DHCP

Network's DHCP Application logging channel

NET, FTP

RTOS_CFG_LOG_NET_FTP

Network's FTP Application logging channel

NET, HTTP

RTOS_CFG_LOG_NET_HTTP

Network's HTTP Application logging channel

NET, IPERF

RTOS_CFG_LOG_NET_IPERF

Network's IPerf Application logging channel

NET, MQTT

RTOS_CFG_LOG_NET_MQTT

Network's MQTT Application logging channel

NET, SMTP

RTOS_CFG_LOG_NET_SMTP

Network's SMTP Application logging channel

NET, SNTP

RTOS_CFG_LOG_NET_SNTP

Network's SNTP Application logging channel

NET, SSL

RTOS_CFG_LOG_NET_SSL

Network's SSL layer logging channel

USBD

RTOS_CFG_LOG_USBD

USB Device's root logging channel

USBD, CLASS

RTOSCFG_LOG USBD_CLASS

USB Device's Classes logging channel

USBD, CLASS, AUDIO

RTOS_CFG_LOG_USBD_CLASS_AUDIO

USB Device's Audio Class logging channel

USBD, CLASS, CDC, ACM

RTOS_CFG_LOG_USBD_CLASS_CDC_ACM

USB Device's CDC-ACM logging channel

USBD, CLASS, CDC, EEM

RTOS_CFG_LOG_USBD_CLASS_CDC_EEM

USB Device's CDC-EEM logging channel

USBD, CLASS, HID

RTOS_CFG_LOG_USBD_CLASS_HID

USB Device's HID Class logging channel

USBD, CLASS, MSD

RTOS_CFG_LOG_USBD_CLASS_MSC

USB Device's MSC Class logging channel

USBD, CLASS, VENDOR

RTOS_CFG_LOG_USBD_CLASS_VENDOR

USB Device's Vendor Class logging channel

USBD, DRV

RTOS_CFG_LOG_USBD_DRV

USB Device's Driver layer logging channel

USBH

RTOS_CFG_LOG_USBH

USB Host's root logging channel

USBH, CLASS

RTOS_CFG_LOG_USBH_CLASS

USB Host's Classes logging channel

USBH, CLASS, AOAP

RTOS_CFG_LOG_USBH_CLASS_AOAP

USB Host's AOAP Class logging channel

USBH, CLASS, CDC

RTOS_CFG_LOG_USBH_CLASS_CDC

USB Host's CDC Class logging channel

USBH, CLASS, HID

RTOS_CFG_LOG_USBH_CLASS_HID

USB Host's HID Class logging channel

USBH, CLASS, MSD

RTOS_CFG_LOG_USBH_CLASS_MSC

USB Host's MSC Class logging channel

USBH, CLASS, USB2SER

RTOS_CFG_LOG_USBH_CLASS_USB2SER

USB Host's USB2Ser Class logging channel

USBH, DEV

RTOS_CFG_LOG_USBH_DEV

USB Host's Device management layer logging channel

USBH, HCD

RTOS_CFG_LOG_USBH_HCD

USB Host's Host Controller Driver layer logging channel

USBH, PBHCD

RTOS_CFG_LOG_USBH_PBHCD

USB Host's Pipe-Based Host Controller Driver layer logging channel

Common Compile-Time Configuration#

The following configuration constants are located in the common_cfg.h configuration file.

Lib Module#

Lib Memory Configuration#

Table - Lib Mem Optimization Configuration Constants#

Table - Lib Mem Optimization Configuration Constants

Table - Lib Mem Allocation Configuration Constants#

Table - Lib Mem Allocation Configuration Constants

Lib String Configuration#

Table - Lib Str Configuration Constants#

Table - Lib Str Configuration Constants

RTOS_ERR Type Configuration#

The following configuration constants are located in the rtos_err_cfg.h file.

Table - RTOS_ERR Type Configuration Constants#

Table - RTOS_ERR Type Configuration Constants

Common Run-Time Configuration#

This section describes the application-specific configurations of the common module. These are specified at run-time.

The following sections describe the configurations that are optional. If you do not set them in your application, the default configurations will apply.

General Configuration#

Default values can be retrieved via the Common_InitCfgDflt structure.

Note that these configurations must be set before you call the function Common_Init().

The following tables describe the configuration structure's fields, their default values and the functions used to change them. For the advanced method, it is assumed that a COMMON_INIT_CFG structure global variable called Common_InitCfg is defined by the application.

Memory Segment#

Pointer to the memory segment from which the Common module's data will be allocated.

Type

Function to Call

Default

Default Configuration Structure Field

MEM_SEG*

Common_ConfigureMemSeg()

See the General-purpose heap .

.CommonMemSegPtr

Logging Configuration Structure#

Only present if the Logging module is enabled, by setting RTOS_CFG_LOG_EN to DEF_ENABLED, in rtos_cfg.h. For more details about logging configuration, see Logging Usage .

Configuration structure for the Logging module.

Type

Function to Call

Default

Default Configuration Structure Field

COMMON_CFG_LOGGING

Common_ConfigureLogging()

See structure's description.

.LoggingCfg

Logging Memory Segment#

Only present if the Logging module is enabled, by setting RTOS_CFG_LOG_EN to DEF_ENABLED in rtos_cfg.h . For more details about logging configuration, see Logging Usage .

Pointer to memory segment from which the Logging module's data will be allocated, including the ring buffer, if the size is not 0.

Type

Function to Call

Default

Default Configuration Structure Field

MEM_SEG*

Common_ConfigureMemSegLogging()

The General-purpose heap .

.LoggingMemSegPtr

Authentication#

The default values can be retrieved via the structure Auth_InitCfgDflt.

Note that these configurations must be set before you call the function Auth_Init().

The following tables describe the configuration structure's fields, their default values and the functions used to change them. When using the advanced method, the application defines the AUTH_INIT_CFG structure global variable called Auth_InitCfg.

Root User Configuration Structure#

Configuration structure for the Root User.

Type

Function to Call

Default

Default Configuration Structure Field

AUTH_CFG_ROOT_USER

Auth_ConfigureRootUser()

See structure's description.

.RootUserCfg

Resource Usage Configuration Structure#

Configuration structure for the Resource usage.

Type

Function to Call

Default

Default Configuration Structure Field

AUTH_CFG_RESOURCE

Auth_ConfigureResource()

See structure's description.

.ResourceCfg

Memory Segment#

Pointer to memory segment from which Authentication module's data will be allocated.

Type

Function to Call

Default

Default Configuration Structure Field

MEM_SEG*

Auth_ConfigureMemSeg()

The General-purpose heap .

.MemSegPtr

Shell#

The following configurations will only be present if the Shell module is available.

The default values can be retrieved via the structure Shell_InitCfgDflt.

Note that these configurations must be set before you call the function Shell_Init().

The following tables describe the configuration structure's fields, their default values, and the functions that modify them. If the advanced method is used and Shell_Init() is called by the application, the application defines a SHELL_INIT_CFG structure global variable called Shell_InitCfg.

Command Usage#

Configuration structure for the commands that will be registered in the Shell sub-module

Type

Function to Call

Default

Default Configuration Structure Field

SHELL_CFG_CMD_USAGE

Shell_ConfigureCmdUsage()

See the structure's description.

.CfgCmdUsage

Memory Segment#

Pointer to the memory segment from which the Shell module's data will be allocated.

Type

Function to Call

Default

Default Configuration Structure Field

MEM_SEG*

Shell_ConfigureMemSeg()

See the General-purpose heap .

.MemSegPtr

Configuration Summary#

The table below provides a summary of the configurations functions for the core and every sub-module.

Common#

Common

Authentication#

Authentication

Shell#

Shell

Authentication Run-Time Application-Specific Configurations#

The following structures contain values that configure the authentication sub-module, which is part of the Common module. This module is optional.

AUTH_CFG_ROOT_USER#

AUTH_CFG_ROOT_USER is a structure that can be used to configure the root user's properties.

Table - AUTH_CFG_ROOT_USER configuration structure in the Authentication Run-Time Application-Specific Configurations page describes each configuration field available for this configuration structure.

Table - AUTH_CFG_ROOT_USER configuration structure#

Field

Description

Possible values

.RootUserName

Name of the root user. Must be null-terminated.

Any valid string, "admin" by default.

.RootUserPwd

Password for the root user. Must be null-terminated.

Any valid string, "admin" by default.

AUTH_CFG_RESOURCE#

AUTH_CFG_RESOURCE is a structure that can be used to configure the various resources used by the authentication sub-module.

Table - AUTH_CFG_RESOURCE configuration structure in the Authentication Run-Time Application-Specific Configurations page describes each configuration field available for this configuration structure.

Table - AUTH_CFG_RESOURCE configuration structure#

Field

Description

Possible values

.NbUserMax

Maximum number of users.

Any valid 8-bit integer, 4 u by default.

.NameLenMax

Maximum length of user names.

Any valid 8-bit integer, 10u by default.

.PwdLenMax

Maximum length of user passwords.

Any valid 8-bit integer, 10u by default.

Logging Run-Time Application-Specific Configuration#

COMMON_CFG_LOGGING is a structure that can be used to configure the buffer sizes for the logging sub-module.

Table - COMMON_CFG_LOGGING structure in the Logging Run-Time Application-Specific Configuration page describes each field available in this configuration structure.

Table - COMMON_CFG_LOGGING structure#

Field

Description

Possible values

.AsyncBufSize

Size of the ring buffer, in bytes, used for asynchronous logging. Setting this value to 0 u will disable support for asynchronous logging, as no ring buffer will be available.

Any 16-bit integer, 512 u by default.

Shell Run-Time Application-Specific Configurations#

SHELL_CFG_CMD_USAGE is a structure that can be used to configure the various quantity and buffer sizes used by the Shell sub-module.

Table - SHELL_CFG_CMD_USAGE configuration structure in the Shell Run-Time Application-Specific Configurations page describes each field available for this configuration structure.

Table - SHELL_CFG_CMD_USAGE configuration structure#

Field

Description

Possible values

.CmdTblItemNbrInit

Initial number of command items allocated for the command table.

Any 16-bit integer, 10 u by default.

.CmdTblItemNbrMax

Maximum number of command items allocated for the command table.

Any 16-bit integer, 10 u by default.

.CmdArgNbrMax

Maximum number of arguments for shell commands.

Any 16-bit integer, 10 u by default.

.CmdNameLenMax

Maximum length of a shell command, including terminating NULL character.

Any 16-bit integer, 10 u by default.