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#
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_CRITICAL_FAILED_END_CALL_SEL#
Table - Assert failed end call configuration value description#
RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN#
RTOS Logging Configuration#
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#
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 Allocation Configuration Constants#
Lib String Configuration#
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#
Common Run-Time Configuration#
This section describes the application-specific configurations of the common module. These are specified at run-time.
For more information on how default run-time configuration values can be changed or used, see Initialization of the Common Module .
For more information on how to initialize any Micrium product, see Stacks Initialization Methods .
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* | 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() | .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() | .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() | .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#
Authentication#
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. |