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:

Add FreeRTOS to the project. For ModusToolbox™ software, enable FreeRTOS using the library manager.
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.
Add FREERTOS to the COMPONENTS variable defined in the ModusToolbox™ application Makefile:
```
COMPONENTS+=FREERTOS
```
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).
Open the copied FreeRTOSConfig.h file and remove the #warning This is a template. line.

Do the following in the main.c file:

Include the required header files:

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

Specify the GPIO port and pin for the LED:
```
#define LED_GPIO (CYBSP_USER_LED)
```

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);
    }
}

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 */
    }
}

Build the project and program it into the target kit.
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:

Reduce all interrupt priorities to configMAX_SYSCALL_INTERRUPT_PRIORITY or lower.
Trigger an interrupt with a priority less than or equal to configMAX_SYSCALL_INTERRUPT_PRIORITY and call the FreeRTOS functions from this interrupt handler.
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:

`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:

`configMAX_PRIORITIES`

This parameter specifies the maximum number of discrete priorities for RTOS tasks, which are numbered 0 to configMAX_PRIORITIES-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.
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.

Infineon/freertos