FreeRTOS for Infineon MCUs

Overview

FreeRTOS is supplied as standard C source files built along with the other C files in your project. This repository contains a port of the FreeRTOS kernel for Infineon MCUs based on Arm® Cortex®-M0 (CM0), Cortex®-M0+ (CM0P), Cortex®-M4 (CM4), Cortex®-M33 (CM33), Cortex®-R4 (CR4) and Cortex®-M7 (CM7) cores.

Note: Cortex®-R4 (CR4) is currently supported only on GCC_ARM

See the FreeRTOS API documentation at FreeRTOS web page.

Features

• Simple, small, and easy to use – a typical RTOS kernel binary image is in the region of 6K–12K bytes
• Flexible scheduler configuration – preemptive, cooperative, and hybrid options with optional time-slicing
• RTOS objects (tasks, queues, semaphores, software timers, mutexes, and event groups) can be created using either dynamically or statically allocated RAM
• Tickless mode for low-power applications
• Mutexes with priority inheritance
• Supports both real-time tasks and co-routines
• Efficient software timers
• Stack overflow detection options
• Royalty-free

Quick start

The quick start guide provides steps to create a simple blinking LED project with a single task using FreeRTOS.

FreeRTOS can be used in various development environments such as ModusToolbox™. See FreeRTOS for Infineon MCUs Release.md for details.

The quickest way to get started is to use code examples available at the Cypress Semiconductor website and Infineon GitHub repository.

This quick start guide assumes that the environment is configured to use the board support package (BSP) for your kit and it is included in the project.

Do the following to create a simple FreeRTOS application:

1. Add FreeRTOS to the project. For ModusToolbox™ software, enable FreeRTOS using the library manager.

2. Add the RTOS support libraries to the project:

   • clib-support
   • abstraction-rtos

   Note: ModusToolbox™ library manager automatically pulls the dependent libraries once the FreeRTOS library is selected.

3. Add FREERTOS to the COMPONENTS variable defined in the ModusToolbox™ application Makefile:

   COMPONENTS+=FREERTOS
   

4. Copy the FreeRTOSConfig.h file from the freertos/Source/portable/COMPONENT_$(CORE) folder to your project, where $(CORE) is the target Arm® Cortex®-M CPU core (CM0, CM0P, CM4, CM33, CR4 or CM7).

5. Open the copied FreeRTOSConfig.h file and remove the #warning This is a template. line.

6. Do the following in the main.c file:

   1. Include the required header files:

      #include "cyhal.h"
      #include "cybsp.h"
      #include "FreeRTOS.h"
      #include "task.h"

   2. Specify the GPIO port and pin for the LED:

      #define LED_GPIO (CYBSP_USER_LED)

   3. Add the function to toggle the LED:

      void blinky(void * arg)
      {
          (void)arg;
      
          /* Initialize the LED GPIO pin */
          cyhal_gpio_init(LED_GPIO, CYHAL_GPIO_DIR_OUTPUT,
                          CYHAL_GPIO_DRIVE_STRONG, CYBSP_LED_STATE_OFF);
      
          for(;;)
          {
              /* Toggle the LED periodically */
              cyhal_gpio_toggle(LED_GPIO);
              vTaskDelay(500);
          }
      }

   4. Create a task using the previously added LED toggle function and start the task scheduler:

      int main(void)
      {
          BaseType_t retval;
          cy_rslt_t result;
      
          /* Initialize the device and board peripherals */
          result = cybsp_init() ;
          if (result != CY_RSLT_SUCCESS)
          {
              CY_ASSERT(0);
          }
      
          __enable_irq();
      
          retval = xTaskCreate(blinky, "blinky", configMINIMAL_STACK_SIZE, NULL, 5, NULL);
      
          if (pdPASS == retval)
          {
              vTaskStartScheduler();
          }
      
          for (;;)
          {
              /* vTaskStartScheduler never returns */
          }
      }

7. Build the project and program it into the target kit.

8. Observe the LED blinking on the kit.

Configuration considerations

To configure FreeRTOS, copy the pre-configured FreeRTOSConfig.h file from the freertos/Source/portable folder to your project and modify the copied configuration file as needed.

See the Customization documentation for configuration options available in the FreeRTOSConfig.h file.

The following configuration values are especially important to CM0, CM0P, CM4, CM33, CR4 and CM7 FreeRTOS ports:

• configCPU_CLOCK_HZ
• configMAX_SYSCALL_INTERRUPT_PRIORITY
• configHEAP_ALLOCATION_SCHEME
• configTOTAL_HEAP_SIZE
• configMINIMAL_STACK_SIZE
• configUSE_TICKLESS_IDLE
• configUSE_NEWLIB_REENTRANT
• configMAX_PRIORITIES

configCPU_CLOCK_HZ

This parameter passes the frequency of the MCU core required for the FreeRTOS system timer configuration to FreeRTOS. The pre-configured FreeRTOSConfig.h file provided with this FreeRTOS package sets the configCPU_CLOCK_HZ value as SystemCoreClock calculated by the MCU system startup code.

configMAX_SYSCALL_INTERRUPT_PRIORITY

This parameter sets the highest interrupt priority to call interrupt-safe FreeRTOS functions from. Calling the FreeRTOS functions from an interrupt with a priority higher than configMAX_SYSCALL_INTERRUPT_PRIORITYcauses FreeRTOS to generate an exception.

Do the following to avoid this problem:

1. Reduce all interrupt priorities to configMAX_SYSCALL_INTERRUPT_PRIORITY or lower.

2. Trigger an interrupt with a priority less than or equal to configMAX_SYSCALL_INTERRUPT_PRIORITY and call the FreeRTOS functions from this interrupt handler.

3. Call the FreeRTOS functions from the traceTASKSWITCHEDOUT() macro. See FreeRTOS support.

Note: If your system pipe (IPC) interrupt priority is less than or equal to configMAX_SYSCALL_INTERRUPT_PRIORITY, be careful with code that writes to the flash (including the flash/Bluetooth® LE/Emulated EEPROM/DFU). The duration of critical sections must be kept short. For details, see the psoc6pdl flash driver documentation.

The interrupt priority parameters are ignored by the Cortex® M0/M0P ports because these CPUs use a simpler nested vectored interrupt controller (NVIC):

• configKERNEL_INTERRUPT_PRIORITY
• configMAX_SYSCALL_INTERRUPT_PRIORITY
• configMAX_API_CALL_INTERRUPT_PRIORITY

See https://www.freertos.org/RTOS-Cortex-M3-M4.html for more information on interrupt priority.

configHEAP_ALLOCATION_SCHEME

This parameter specifies the memory management scheme.

Each scheme is documented in the FreeRTOS memory management topic. The memory management implementation files are in the freertos/Source/portable/MemMang directory.

The following memory management schemes are available:

Function	Description
HEAP_ALLOCATION_TYPE1 (heap_1)	The simplest; does not permit memory to be freed. Active by default
HEAP_ALLOCATION_TYPE2 (heap_2)	Permits memory to be freed, but does not coalesce adjacent free blocks
HEAP_ALLOCATION_TYPE3 (heap_3)	Simply wraps a standard malloc() and free() for thread safety
HEAP_ALLOCATION_TYPE4 (heap_4)	Coalesces adjacent free blocks to avoid fragmentation. Includes the absolute address-placement option
HEAP_ALLOCATION_TYPE5 (heap_5)	As per heap_4, with the ability to span the heap across multiple non-adjacent memory areas
NO_HEAP_ALLOCATION	Disables memory management; used for applications with static memory allocation

In the heap_3 memory scheme, your linker file must specify a sufficient size of the heap and stack, and your firmware must implement and use malloc() and free() to allocate and release memory.

In the other memory schemes, the RTOS itself allocates a stack and heap. For these schemes, the stack defined in the BSP linker file is used only by the main() function and the functions it calls.

HEAP_ALLOCATION_TYPE3 is the default memory management scheme enabled in FreeRTOSConfig.h. It is suggested for use with the applications that rely on malloc() and free() implementations provided by the standard C library (for example, GCC + newlib).

To avoid a possible corruption of the heap storage pool due to simultaneous calls to malloc from multiple threads, it is strongly recommended to enable the configUSE_NEWLIB_REENTRANT configuration parameter, and include the CLib FreeRTOS support library in the application.

Note: In ModusToolbox™ software, clib-support has been added as a dependency to this FreeRTOS library so that you do not need to import it separately.

For more details on memory management schemes, see the FreeRTOS documentation.

configTOTAL_HEAP_SIZE

This parameter specifies the total amount of RAM available for the FreRTOS heap. This parameter ignored when the heap_3 memory scheme is used.

configMINIMAL_STACK_SIZE

This parameter specifies the size of the stack used by the idle task. It is not recommended to reduce the default parameter value. Please note that when DS-RAM feature is enabled, the minimum value of this parameter should be 256.

configUSE_TICKLESS_IDLE

This parameter configures the tickless idle functionality required for low-power mode support.

The tickless mode is enabled automatically if the ModusToolbox™ device configurator power personality parameter "System idle power mode" is set to either "CPU Sleep" or "System Deep Sleep". The correct operation of the tickless mode depends on the vApplicationSleep hook provided by the application. See the RTOS abstraction library for the compatible implementation of the vApplicationSleep hook. The low power assistant library provides additional portable configuration layer for low-power features supported by PSoC™ 6 MCU devices.

See the following resources for more details on low-power support:

• Tickless idle mode
• Low-power RTOS for Arm® Cortex®-M MCUs
• LPA middleware API reference guide

configUSE_NEWLIB_REENTRANT

This parameter enables the allocation of newlib reentrancy structures for each RTOS task. The system behavior is toolchain-specific.

• GCC toolchain: The application must provide the implementation for the required newlib hook functions: __malloc_lock, __malloc_unlock, __env_lock, and __env_unlock. FreeRTOS-compatible implementation is provided by the clib-support library.

• Arm®/IAR toolchains: The application must provide the reent.h header file to adapt FreeRTOS's configUSE_NEWLIB_REENTRANT to work with the toolchain-specific C library. The compatible implementations are provided by the clib-support library.

See the following resources for more details on newlib reentrancy support:

• FreeRTOS customization
• newlib reentrancy
• CLib FreeRTOS support library
• newlib and FreeRTOS configuration hints

configMAX_PRIORITIES

This parameter specifies the maximum number of discrete priorities for RTOS tasks, which are numbered 0 to configMAX_PRIORITIES-1.

1. If timer functionality is enabled, configTIMER_TASK_PRIORITY parameter in FreeRTOSConfig.h should have value in the range of 0 to configMAX_PRIORITIES-1.

2. Any user created RTOS-tasks should have priority value from 0 to configMAX_PRIORITIES-1.

Note: If the task priority is defined equal to or greater than configMAX_PRIORITIES then in case of Release mode the priority will be adjusted to configMAX_PRIORITIES - 1, in case of Debug mode the application will assert.

More information

• FreeRTOS RELEASE.md
• FreeRTOS API documentation
• FreeRTOS homepage
• ModusToolbox™ software environment, quick start guide, documentation, and videos
• PSoC™ 6 technical reference manuals
• PSoC™ 6 datasheets
• PSoC™ 4 technical reference manuals
• PSoC™ 4 datasheets
• Cypress Semiconductor website

---

© Cypress Semiconductor Corporation (an Infineon Technologies company), 2019-2021.