AM261x MCU+ SDK: FreeRTOS

| AM261x MCU+ SDK 26.00.00 |

FreeRTOS

# Introduction

FreeRTOS is a market-leading real-time operating system (RTOS) for microcontrollers and small microprocessors. Distributed freely under the MIT open source license, FreeRTOS includes a kernel and a growing set of libraries suitable for use across all industry sectors. FreeRTOS is built with an emphasis on reliability and ease of use.

MCU+ SDK supports FreeRTOS on below CPUS

- ARM M4F
- ARM R5F

MCU+ SDK supports FreeRTOS MPU on below CPUs

- ARM R5F

# Features Supported

- FreeRTOS Kernel 11.1.0
  - Tasks, semaphores, mutex, queues, timers, list, heap, event groups
  - preemptive priority based scheduler
  - static and/or dynamic memory allocation mode
- FreeRTOS MPU (only on R5F)
  - Create user mode and privileged mode tasks
  - User mode tasks with up-to 7 configurable task specific MPU regions
- FreeRTOS+POSIX
  - Limited POSIX API wrappers on top of FreeRTOS APIs
  - Clock, message queue, pthread, pthread cond, pthread mutex, semaphore, timer
- In order to keep the device drivers agnostic of FreeRTOS or NORTOS, additionally below Driver Porting Layer (DPL) APIs are implemented to call FreeRTOS APIs underneath,
  - Clock, task, semaphore, heap, cache, MPU, debug logs, HW interrupts, HW timers
- Floating point save/restore with tasks (make sure to call portTASK_USES_FLOATING_POINT() before using floating point operations )
- R5F ISRs,
  - IRQ mode,
    - FPU save/restore is supported.
    - Priority based interrupt masking in critical section is supported using configMAX_SYSCALL_INTERRUPT_PRIORITY, uncomment macro EN_MAX_SYSCALL_INTR_PRI_CRIT_SECTION in source/kernel/freertos/portable/TI_ARM_CLANG/ARM_CR5F/portmacro.h to enable.(Disabled by default)
    - nested interrupts are supported.
- M4F ISRs,
  - nested interrupts supported

# Features Not Supported

- Co-routines, stream buffer are not enabled and are not compiled by default. Users can add these to the FreeRTOS config and makefile if they want to use these features.
- Tickless IDLE mode
- `portSWITCH_TO_USER_MODE` is not supported
  - i.e, a task created in privileged mode cannot set its privilege level to user mode
- `vTaskAllocateMPURegions` is not tested and should not be used
  - i.e, a task created with task specific MPU regions cannot modify/re-define the MPU regions at run time
- R5F ISRs,
  - IRQ mode,
  - FIQ mode,
    - nested interrupts not supported
    - FPU save/restore not supported.
- M4F ISRs,
  - FPU save/restore not supported.

# SysConfig Features

Note
  It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

SysConfig can be used to configure below modules with FreeRTOS

- Clock module, to setup system tick timer including the tick duration
- Debug Log module, to select the console to use for logging as well as enable/disable logging zones
- MPU ARMv7, to setup different MPU regions for R5F and M4F CPUs
- Address Translate module, to setup address translation regions, needed for M4F
- Address Translate module, to setup address translation regions, needed for M4F
- HW Timer module, to setup HW timer available on the SOC, including enabling timer interrupt and ISR registration

# Important files and directory structure

FreeRTOS source is distributed along with MCU+ SDK and given below are some important files and folders related to FreeRTOS.

Folder/Files | Description
--- | ---
${SDK_INSTALL_PATH}/source/kernel/
dpl/ | APIs to access FreeRTOS features in a OS agnostic way
${SDK_INSTALL_PATH}/source/kernel/freertos
lib/ | FreeRTOS library to link against. Linking to the library in this path enables the application to operate in FreeRTOS mode
config/ | FreeRTOS and FreeRTOS POSIX configuration header files for different CPUs within a SOC.
FreeRTOS-Kernel/ | FreeRTOS Kernel source code. MCU+ SDK simply clones the code from FreeRTOS github and does not modify anything in this folder
FreeRTOS-POSIX/ | FreeRTOS POSIX wrapper source code. MCU+ SDK simply clones the code from FreeRTOS POSIX github and does not modify anything in this folder
portable/ | MCU+ SDK FreeRTOS porting related files for different CPUs
${SDK_INSTALL_PATH}/source/kernel/freertos/dpl
common/ | FreeRTOS DPL APIs that are common across all CPUs
m4/ | FreeRTOS DPL APIs that are specific to M4F CPUs
r5/ | FreeRTOS APIs that are specific to R5F CPUs

In addition to above files, to enable features like HW interrupts, cache, MPU, the FreeRTOS library in MCU+ SDK also shares some code with NORTOS, see to makefile in the folder `source\kernel\freertos` to see the exact list of files that are included to build a freertos library.

# FreeRTOS usage guidelines

See FreeRTOS usage guidelines for FreeRTOS usage guidelines and comparison to SysBIOS.

See FreeRTOS MPU usage guidelines for FreeRTOS MPU usage guidelines.

# Additional references

Given below are some references to learn more about FreeRTOS.

Document Description | Web link
--- | ---
Easy to read FreeRTOS book | https://www.freertos.org/Documentation/RTOS_book.html
FreeRTOS user docs | https://www.freertos.org/features.html
User API reference | https://www.freertos.org/a00106.html
FreeRTOS core kernel source code | https://github.com/FreeRTOS/FreeRTOS-Kernel
FreeRTOS core kernel example source code | https://github.com/FreeRTOS/FreeRTOS/tree/master/FreeRTOS
Additional FreeRTOS.org maintained libraries (POSIX, TCP, Filesystem, …) | https://www.freertos.org/FreeRTOS-Labs/index.html https://www.freertos.org/FreeRTOS-Plus/index.html https://github.com/FreeRTOS

# See also

Driver Porting Layer (DPL), NO RTOS