Skip to end of metadata
Go to start of metadata

RTOS Configuration

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

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_MASK

DescriptionPossible values

RTOS_CFG_ASSERT_DBG_ARG_CHK_EXT_MASK defines 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.

This configuration can be set as a bitmap of several module defines to allow more flexibility. For example, it could be defined as RTOS_CFG_MODULE_ALL or RTOS_CFG_MODULE_NONE to enable or disable argument checking for every module. It could also be set as a combination of particular modules such as:

(RTOS_CFG_MODULE_CPU | RTOS_CFG_MODULE_KERNEL)
This keeps the debug asserts only in the CPU and Kernel modules, but not in any other.

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

(RTOS_CFG_MODULE_ALL)

Or a combination (separated with |) of the following bitmaps:

RTOS_CFG_MODULE_NONE
RTOS_CFG_MODULE_ALL

RTOS_CFG_MODULE_APP
RTOS_CFG_MODULE_BSP
RTOS_CFG_MODULE_ALL_APP

RTOS_CFG_MODULE_CAN
RTOS_CFG_MODULE_COMMON
RTOS_CFG_MODULE_CPU
RTOS_CFG_MODULE_FS
RTOS_CFG_MODULE_KERNEL
RTOS_CFG_MODULE_NET
RTOS_CFG_MODULE_NET_APP
RTOS_CFG_MODULE_USBD
RTOS_CFG_MODULE_USBH
RTOS_CFG_MODULE_IO
RTOS_CFG_MODULE_PROBE
RTOS_CFG_MODULE_ALL_PRODUCTS

Which are all defined in rtos/common/include/rtos_opt_def.h.

RTOS_CFG_RTOS_ASSERT_DBG_FAILED_END_CALL(ret_val)

DescriptionPossible values

RTOS_CFG_RTOS_ASSERT_DBG_FAILED_END_CALL configures what operation will happen in cases where a debug assert has failed. A debug "asserts fail" reflects an invalid argument passed by the programmer to a stack function or an operation that cannot be handled in a particular context (such as an ISR).

The program should not continue running after a debug assert has failed. However, it is possible to configure it to return (by defining it to: return ret_val (without parentheses or ';')), if the code is being executed in a test context.

Typical operations can include breaking the CPU, looping indefinitely, calling a function or macro, etc. The default behavior is to loop indefinitely.

Undefined, will loop indefinitely.

Any other calls to macro(s) or function(s).

RTOS_CFG_RTOS_ASSERT_CRITICAL_FAILED_END_CALL(ret_val)

DescriptionPossible values

RTOS_CFG_RTOS_ASSERT_CRITICAL_FAILED_END_CALL configures what operation occurs in cases where a critical assert is failed. A failed critical assert reflects unrecoverable situations in the system such as corruption or other cases that are unexpected.

The program must not continue to execute in those cases.

The program must not return from this call, since the software is in an unknown and/or invalid state.

Typical operations can include outputting logs or traces, dumping memory, halting and/or restarting the system. The default behavior is to call the CPU_SW_EXCEPTION macro.

Undefined, will call CPU_SW_EXCEPTION macro.

Any other calls to macro(s) or function(s).

RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN

DescriptionPossible values

RTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN determines whether the configurations can be provided via optional <Module>_Configure...() calls to the stacks or if these configurations are assumed extern by the stacks and must be provided by the application.

If set to DEF_DISABLED, default configurations will be present in stacks and they can optionally be overridden with <Module>_Configure...() calls. This is the easier and preferred option to use when starting the development of an application.

The default values used by the stacks are available for the application to copy, but you should only modify parts of it and set them as the new configuration (see each stack's user's manual for more information). If set to DEF_ENABLED, no default configuration will be present in the stacks and every configuration that could be set via <Module_Configure...() calls are now assumed extern by the stacks. These calls must then be defined by the application. This option is useful to reduce the amount of memory and code space used.

See Stacks Initialization Methods for more details.

DEF_ENABLED or  DEF_DISABLED

RTOS Logging Configuration

ConstantDescriptionPossible values
RTOS_CFG_LOG_EN

RTOS_CFG_LOG_EN is used to enable or disable the logging module as a whole.

If enabled, RTOS_CFG_LOG_ALL MUST be defined. All logging channels will inherit this configuration if not overridden by a more specific configuration as shown below.

DEF_ENABLED or  DEF_DISABLED
RTOS_CFG_LOG_ALL

See Logging Channel Configuration section.

VRB, ASYNC, FUNC_DIS, TS_DIS, putchar

or any valid combinations of flags.

RTOS_CFG_LOG_[...]
See Logging Channel Configuration section. 
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:

OptionDescriptionPossible values
Lowest level to log

Sets the minimal level entries must be to be logged.

For example:

  • If it is set to VRB, every entry will be logged
  • If it is set to ERR, only error-level messages will be logged

VRB : Log error-, debug- and verbose-level messages.

DBG: Log error- and debug-level messages.

ERR: Log error-level messages only.

OFF: Do not log any level.

DFLT: Use the inherited setting.

Timing of output of entries

Specifies when to output entries, either:

  • Synchronously: at the moment the entry is made
  • Asynchronously: it will then store it in a ring buffer and outputting it only when Log_Output() is called.

SYNC: Output logs synchronously, during code execution. May disrupt timing.

ASYNC : Save logs in buffer, always keeping the most recent ones. Output will only be done when Log_Output() is called (see rtos/common/include/logging.h for more details).

DFLT: Use the inherited setting.

Function name

Includes or omits the function name where the log was made for every logging entry.

FUNC_EN: Function name where logging was made will be included in entry.

FUNC_DIS : Function name where logging was made will NOT be included in entry.

DFLT: Use the inherited setting.

Time-stamp

Includes or omits the timestamp for every logged entry.

TS_EN: Timestamp of when entry was made will be included in entry.

TS_DIS : Timestamp of when entry was made will NOT be included in entry.

DFLT: Use the inherited setting.

Log output functionOutputs any logging entries.

Any function of type int foo(int character), as putchar, for example.

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 channelDescription
COMMON RTOS_CFG_LOG_COMMONCommon's root logging channel
COMMON, CLK RTOS_CFG_LOG_COMMON_CLKCommon's Clock module logging channel
COMMON, LIB RTOS_CFG_LOG_COMMON_LIBCommon's LIB module logging channel
COMMON, SHELL RTOS_CFG_LOG_COMMON_SHELLCommon's Shell module logging channel
FS RTOS_CFG_LOG_FSFile System's root logging channel
FS, BLK_DEV RTOS_CFG_LOG_FS_BLK_DEVFile System's Block Device layer logging channel
FS, CORE RTOS_CFG_LOG_FS_COREFile System's Core layer logging channel
FS, DRV RTOS_CFG_LOG_FS_DRVFile System's Driver layer logging channel
FS, FAT RTOS_CFG_LOG_FS_FATFile System's FAT layer logging channel
FS, MEDIA RTOS_CFG_LOG_FS_MEDIAFile System's Media layer logging channel
FS, STORAGE RTOS_CFG_LOG_FS_STORAGEFile System's Storage layer logging channel
KERNEL RTOS_CFG_LOG_KERNELKernel's logging channel
NET RTOS_CFG_LOG_NETNetwork's root logging channel

NET, DNS

RTOS_CFG_LOG_NET_DNS

Network's DNS Application logging channel
NET, DHCP RTOS_CFG_LOG_NET_DHCPNetwork's DHCP Application logging channel
NET, FTP RTOS_CFG_LOG_NET_FTPNetwork's FTP Application logging channel
NET, HTTP RTOS_CFG_LOG_NET_HTTPNetwork's HTTP Application logging channel
NET, IPERF RTOS_CFG_LOG_NET_IPERFNetwork's IPerf Application logging channel
NET, MQTT RTOS_CFG_LOG_NET_MQTTNetwork's MQTT Application logging channel 
NET, SMTP RTOS_CFG_LOG_NET_SMTPNetwork's SMTP Application logging channel
NET, SNTP RTOS_CFG_LOG_NET_SNTPNetwork's SNTP Application logging channel 
NET, SSL RTOS_CFG_LOG_NET_SSLNetwork's SSL layer logging channel
USBD RTOS_CFG_LOG_USBDUSB Device's root logging channel
USBD, CLASS RTOS_CFG_LOG_ USBD_CLASS USB Device's Classes logging channel
USBD, CLASS, AUDIO RTOS_CFG_LOG_USBD_CLASS_AUDIOUSB Device's Audio Class logging channel
USBD, CLASS, CDC, ACM RTOS_CFG_LOG_USBD_CLASS_CDC_ACMUSB Device's CDC-ACM logging channel
USBD, CLASS, CDC, EEM RTOS_CFG_LOG_USBD_CLASS_CDC_EEMUSB Device's CDC-EEM logging channel
USBD, CLASS, HID RTOS_CFG_LOG_USBD_CLASS_HIDUSB Device's HID Class logging channel
USBD, CLASS, MSD RTOS_CFG_LOG_USBD_CLASS_MSCUSB Device's MSC Class logging channel
USBD, CLASS, VENDOR RTOS_CFG_LOG_USBD_CLASS_VENDORUSB Device's Vendor Class logging channel
USBD, DRV RTOS_CFG_LOG_USBD_DRVUSB Device's Driver layer logging channel
USBH RTOS_CFG_LOG_USBHUSB Host's root logging channel
USBH, CLASS RTOS_CFG_LOG_USBH_CLASSUSB 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_CDCUSB Host's CDC Class logging channel
USBH, CLASS, HID RTOS_CFG_LOG_USBH_CLASS_HIDUSB Host's HID Class logging channel
USBH, CLASS, MSD RTOS_CFG_LOG_USBH_CLASS_MSCUSB Host's MSC Class logging channel
USBH, CLASS, USB2SER RTOS_CFG_LOG_USBH_CLASS_USB2SERUSB 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_HCDUSB Host's Host Controller Driver layer logging channel
USBH, PBHCD RTOS_CFG_LOG_USBH_PBHCDUSB Host's Pipe-Based Host Controller Driver layer logging channel
  • No labels