9.1. FreeRTOS Usage and Migration Guidelines¶
This section has additional useful information related to FreeRTOS and its integration within PDK. It also compares some key points & config in FreeRTOS vs TI SysBIOS RTOS and the guidelines for migrating to FreeRTOS from TI SysBIOS.
- FreeRTOS configuration
- Summary Comparison with SysBIOS
- FreeRTOS Usage Guidelines
- FreeRTOS Migration Guidelines
- API Comparison
- FAQ / Important Notes
9.1.1. FreeRTOS configuration¶
In FreeRTOS, all applications need to provide a FreeRTOSConfig.h file which specifies the FreeRTOS kernel configuration, see https://www.freertos.org/a00110.html
All source code using FreeRTOS APIs, including FreeRTOS kernel itself MUST include “FreeRTOSConfig.h” before any other FreeRTOS .h files.
This is because FreeRTOSConfig.h tailors the RTOS kernel to the application being built. It is therefore specific to the application, not the RTOS.
For example,
#include <FreeRTOSConfig.h> #include <FreeRTOS.h> #include <task.h> #include <semphr.h> #include <event_groups.h>
Configuration includes things like below
- Task scheduling options, Timer tick resolution, Number of priorities, Debug and trace hooks
- Enable / Disable RTOS features, mainly:- task, mutex, recursive mutex, semaphore, etc
- Default sizes for task stack, timer task, idle task, etc
To allow support of pre-built libraries, PDK has a default predefined FreeRTOSConfig.h per SOC and per CPU type
- The predefined config file per SOC and per CPU can be found at below path
- ${PDK_INSTALL_PATH}/packages/ti/kernel/freertos/config/j7200/{cpu}/FreeRTOSConfig.h
In general extreme fine-tuning of FreeRTOS config is not needed and a predefined config per SOC and CPU type would meet almost all use-cases and applications.
Also many config options are related to the inclusion/exclusion of RTOS modules to save code/data size. However, we can rely on the compiler to optimize out functions that are not called by applications.
However, the user can modify this config if needed. When default predefined FreeRTOSConfig.h is changed, all pre-built libraries have to be recompiled for the changes to take effect.
To recompile all pre-built PDK libraries:-
cd PDK_INSTALL_DIR/packages/ti/build make -s pdk_libs_allcores_clean BOARD=j7200_evm make -s pdk_libs_allcores BOARD=j7200_evm
9.1.2. Summary Comparison with SysBIOS¶
This section has a quick summary of the comparison between SysBIOS and FreeRTOS features. Refer rest of the sections on this page for more details
9.1.2.1. Key similarities between modules¶
The following table compares various modules in SysBIOS vs FreeRTOS and the OSAL modules that are implemented. OSAL modules which calls OS API’s underneath are provided to keep drivers/examples OS agnostic and also to support various functionalities which are not present as part of FreeRTOS Kernel. For example, Cache, HW Interrupts, HW Timers, etc.
SysBIOS Module | FreeRTOS Module | OSAL Module | Additional Remarks |
---|---|---|---|
XDC based config (r5_mpu.xs) | FreeRTOSConfig.h | -NA- | #define based config, most code in C files for FreeRTOS |
Static alloc | Static alloc | -NA- | “construct” APIs in SysBIOS, “CreateStatic” APIs in FreeRTOS |
Task | Task | TaskP | Same scheduling policy as SysBIOS |
Semaphore | Semaphore | SemaphoreP | Same as SysBIOS. Binary, counting semaphore’s |
GateMutex | Mutex | MutexP | Same as SysBIOS. Recursive, priority inheritance mutex’s |
Clock | Timer | ClockP | Similar features, see details below |
Event | Event Groups | EventP | Similar features, see details below |
Idle | Idle | -NA- | Only one idle hook function is supported in FreeRTOS. SysBIOS supported multiple idle functions. |
Queue | List | QueueP | Similar features, see details below |
Mailbox | Queue | MailboxP | Similar features, see details below |
Hwi | -NA- | HwiP | Similar features, see details below |
Cache | -NA- | CacheP | Similar features, see details below |
HeapMem | -NA- | HeapP | Similar features, see details below |
MPU/MMU | -NA- | MPU/MMU in CSL | Similar features, see details below |
Swi | “Pend” function call | -NA- | Similar features, see details below |
Load | Run-time stats APIs | LoadP | Similar features, see details below |
9.1.2.2. Key differences between modules¶
FreeRTOS difference vs SysBIOS | Alternative in FreeRTOS |
---|---|
When configUSE_TIME_SLICING is 1, FreeRTOS will time slice between tasks at the same priority (This was no supported in SysBIOS) | Keep this at 0 (PDK default config), if this is not desired |
Timer callbacks are called in task context in FreeRTOS vs ISR context in SysBIOS | Keep the timer task to highest priority so that timer callback get called immediately after all ISRs are done (PDK default config) |
No SWI support in FreeRTOS | Use “pend” function call, where functions are executed in timer task context. Again keep timer task as the highest priority (PDK default config). see xTimerPendFunctionCall() and xTimerPendFunctionCallFromISR() |
No ability to create arbitrary heaps in FreeRTOS | OSAL provides APIs in HeapP module to create arbitrary heaps to match SysBIOS |
Only FreeRTOS APIs ending with “FromISR()” can be called from within ISRs | Porting Layer provides a function xPortInIsrContext() to detect if code is in ISR. This can be used to keep the application functions generic. OSAL takes care of this by default. |
Number of task priorities in FreeRTOS is configurable (up to max 32) vs SysBIOS default of 16 | PDK default config keeps number of task priorities to 16 in FreeRTOS |
No Reset Hook Function support in FreeRTOS. | CSL Startup API _system_post_cinit can be redefined in the application to achieve similar functionality. See Reset Hook Function Alternative for FreeRTOS for more details |
9.1.3. FreeRTOS Usage Guidelines¶
9.1.3.1. FreeRTOS Tasks¶
9.1.3.1.1. Overview¶
- FreeRTOS has the ability to create tasks with the below parameters:
- Entry function
- One void * entry function argument
- Stack memory (when NULL, FreeRTOS uses the default heap to allocate the stack memory)
- Stack size in units of “stack words”, i.e 32b or 4 bytes in case of R5F and C66x.
- Priority (0 is lowest, configMAX_PRIORITY-1 is the highest)
- PDK default config is 16 priorities to match SysBIOS priorities
- Static task object memory allocation is supported
- PDK examples and OSAL by default use static alloc APIs
- Scheduler policy is configurable
- configUSE_PREEMPTION, PDK default is 1 to match SysBIOS scheduler policy
- This enables pre-emptive priority-based scheduling
- configUSE_TIME_SLICING, PDK default is 0, i.e. disabled, to match SysBIOS scheduler policy
- If enabled, when two tasks are of the same priority, FreeRTOS will time-slice between the tasks at units of the timer tick
- NOTE, this is unlike SysBIOS where unless `Task_yeild` is called scheduler will not switch to another task at the same priority
- configUSE_PREEMPTION, PDK default is 1 to match SysBIOS scheduler policy
9.1.3.1.2. Initial Tasks¶
Two tasks are created inside FreeRTOS on startup, idle task and timer task
Idle task is similar to any other task, only it runs at lowest priority.
User can configure a “hook” function to call inside of IDLE, e.g, WFI can be called here.
PDK default config is shown below, vApplicationIdleHook calls a periodic load update API
/* in FreeRTOSConfig.h file */ #define configUSE_IDLE_HOOK (1) /* in port.c file for R5F and C66x */ void vApplicationIdleHook( void ) { #if (configLOAD_UPDATE_IN_IDLE==1) void vApplicationLoadHook(); vApplicationLoadHook(); #endif }
NOTE, unlike SysBIOS, only one idle hook function (`vApplicationIdleHook`) is supported in FreeRTOS
- SysBIOS supported multiple functions to be called when no other Tasks are running.
Timer task (PDK default config enables timer task to match SysBIOS),
Timer callbacks and “deferred” interrupt handler functions are called in the context of the timer task
NOTE, unlike SysBIOS, SW timer callbacks are not called in ISR context
“deferred” handler functions, can be used as an equivalent of SW interrupt of SysBIOS
NOTE, unlike SysBIOS, there is no SWI module in FreeRTOS
PDK config keeps the priority of this task to the highest so that the timer function will run immediately after an ISR
All of above can be controlled via FreeRTOS Config, PDK defaults are listed below
#define configUSE_TIMERS (1) /* enable timer task and SW timers */ #define configTIMER_TASK_PRIORITY (configMAX_PRIORITIES - 1) /* highest priority */ #define configTIMER_TASK_STACK_DEPTH (256) /* 1KB */
9.1.3.1.3. Task load¶
- To measure task and CPU load, in FreeRTOS config, we need to set configGENERATE_RUN_TIME_STATS to 1 (PDK default is 1 when configOPTIMIZE_FOR_LATENCY is 0)
- When load measurement is enabled, portGET_RUN_TIME_COUNTER_VALUE() is called to get a high resolution timer counter value.
- In PDK FreeRTOS porting layer, we implement portGET_RUN_TIME_COUNTER_VALUE() using PMU Counter for R5F and Time Stamp Counter for C66x to return time stamp in units of usecs
- In FreeRTOS Kernel, the load measurement counter will overflow after 32b, i.e around 1 hr with usec resolution timer.
- To avoid this, in FreeRTOS OSAL, a periodic load update API is called in IDLE task to accumulate the measured task load and take care of overflow condition.
- To get task load with overflow condition taken care of, it is recommended to create the task using OSAL TaskP APIs
- Total CPU load is calculated by measuring the time spent in IDLE task and then subtracting it from 100%, i.e CPU load = 100 - CPU idle load
9.1.3.1.4. Task FPU context¶
- When configFLOATING_POINT_CONTEXT is enabled, save/restore of R5F FPU Registers will be performed during each task switch.
- In this case all tasks are created with floating point context and usage of portTASK_USES_FLOATING_POINT/vPortTaskUsesFPU() doesn’t have any effect.
- PDK default is configFLOATING_POINT_CONTEXT enabled (when configOPTIMIZE_FOR_LATENCY is 0).
- This matches the SYSBIOS implementation.
- FreeRTOS C66x port as well save/restore the FPU registers by default.
- C7x doesn’t have separate set of FPU registers.
- For optimized performance the config can be disabled.
- In this case all task will start without a floating point context.
- A task that uses the floating point hardware must call portTASK_USES_FLOATING_POINT/vPortTaskUsesFPU() before executing any floating point instructions.
9.1.3.1.5. Important tips¶
Task function should not return in FreeRTOS, instead, it should call vTaskDelete(NULL) to destroy itself, e.g
void myTaskMain(void *args) { /* ... do something ... */ vTaskDelete(NULL); /* do not call “return” */ }
On task delete, FreeRTOS will free any memory allocated internally, if dynamically memory allocation mode was used. This memory free is done in the “IDLE” task, so “IDLE” needs to get the opportunity to run at some point.
vTaskStartScheduler() starts FreeRTOS and the highest priority task is executed first.
- Tasks, semaphores and OS objects can be created before vTaskStartScheduler() is called.
- Recommend to create one task and call vTaskStartScheduler(). Then do everything from within that task including creating other tasks.
- `vTaskStartScheduler()` is similar to `BIOS_start()`, i.e it never returns and switches to the created tasks or idle task
- .stack is the stack used by code before FreeRTOS scheduler is started, i.e from _c_int00 to vTaskStartSchedular()
9.1.3.2. FreeRTOS Interrupts¶
9.1.3.2.1. Overview¶
- Interrupt handler is not directly invoked by FreeRTOS Kernel, porting layer handles this
- In theory, FreeRTOS can work without interrupts. To switch tasks, interrupts are not needed. However, that’s not very useful.
- Porting layer does below
- Setup (any) one timer to be configured at configTICK_RATE_HZ, typically 1ms
- For R5F, we use one of the SOC level general-purpose DM timers.
- Timer ISR is outside FreeRTOS kernel
- When the timer ISR happens the porting layer calls xTaskIncrementTick() FreeRTOS API to maintain the FreeRTOS timer tick state
- Porting layer also implements the common interrupt entry and exit logic
- Esp before interrupt exit, porting layer needs to invoke a task switch if during ISR handling a semaphore was posted that needed a task switch on ISR exit
- Interrupt nesting is also taken care of by this common interrupt handler
- Porting layer also implements functions to protect the critical sections of FreeRTOS via the below APIs
- portENTER_CRITICAL, disable interrupt, track nesting of calls
- portEXIT_CRITICAL, re-enable interrupt, if nesting call depth is 0
- portSET_INTERRUPT_MASK_FROM_ISR, interrupt disable and return old interrupt state
- portCLEAR_INTERRUPT_MASK_FROM_ISR, restore interrupt state
9.1.3.2.2. Nested interrupts and ISR stack¶
On R5F,
- When an interrupt is triggered, the CPU switches to IRQ mode and uses the IRQ stack.
- IRQ interrupts are disabled by HW at this point.
- In the ISR handler, some CPU state is saved to IRQ stack and mode is switched to SVC mode and therefore SVC stack
- IRQs are then enabled, i.e nested interrupts are enabled
- The user ISR code is executed
- At this point, more IRQs can occur to interrupt the user ISR code
- After all IRQs are handled, IRQ is disabled
- Now mode is switched back to IRQ mode
- If a task switch was requested by any of the ISRs, tasks are switched, and control returns from IRQ to the highest priority pending task
- If a task switch was NOT requested, control returns from IRQ to the interrupted task
On R5F,
Thus the user ISR code gets called with SVC stack, so the size of the SVC stack MUST be kept large enough to handle worst-case ISR requirement.
The IRQ stack size itself can be kept small since it only saves few bytes (8 bytes) of state for every nested IRQ invocation.
This stack size is specified in the linker command file, a sample snippet is shown below,
__IRQ_STACK_SIZE = 256; /* This is the size of stack when R5 is in IRQ mode */ __FIQ_STACK_SIZE = 256; __SVC_STACK_SIZE = 4096; /* This is the size of stack when R5 is in SVC mode */ __ABORT_STACK_SIZE = 256; /* This is the size of stack when R5 is in ABORT mode */ __UNDEFINED_STACK_SIZE = 256; /* This is the size of stack when R5 is in UNDEF mode */
9.1.3.2.3. Interrupts outside of FreeRTOS¶
- On R5F,
- When FreeRTOS enter its critical section, it only disables IRQ but not FIQ
- Hence, FreeRTOS API calls MUST NOT be done inside FIQ.
- FIQs can be used for extremely low latency interrupt bypassing the OS completely.
- NOTE: this is same as the case with SysBIOS
9.1.3.2.4. Additional important tips¶
Only FreeRTOS APIs that end with FromISR can be called from the ISR context
BaseType_t xHigherPriorityTaskWoken = 0; xSemaphoreGiveFromISR(pSemaphore->semHndl, &xHigherPriorityTaskWoken); portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
The FromISR API returns a flag xHigherPriorityTaskWoken to indicate task switch should be requested, portYIELD_FROM_ISR requests the task switch. The actual task switch happens after all nested ISRs have been executed.
This is different from SysBIOS, where the same APIs can be used inside ISR and outside ISR.
The OSAL APIs will take care of this internally as below, e.g,
SemaphoreP_post(...) { .... if( xPortInIsrContext() ) { BaseType_t xHigherPriorityTaskWoken = 0; xSemaphoreGiveFromISR(pSemaphore->semHndl, &xHigherPriorityTaskWoken); portYIELD_FROM_ISR(xHigherPriorityTaskWoken); } else { xSemaphoreGive(pSemaphore->semHndl); } ... }
9.1.3.3. FreeRTOS Semaphores and Mutex¶
9.1.3.3.1. Overview¶
- FreeRTOS has a textbook implementation of binary semaphore, counting semaphore, mutex with priority inheritance, and recursive mutex
- Timeouts can be specified when waiting on a semaphore/mutex, with timeout error code if semaphore/mutex is not available
- Timeout is specified in units of OS ticks. Use pdMS_TO_TICKS() to convert from msec to OS ticks
9.1.3.3.2. Important tips¶
- Binary and counting semaphores should be used to signal from ISR to task and task to task
- PDK default config enables binary and counting semaphores
- Mutex should be used for mutual exclusion of critical sections.
- PDK default config enables mutex and recursive mutexes
- Once again, only APIs that end with FromISR can be used from within ISR. These are non-blocking APIs.
9.1.3.4. FreeRTOS Task Notification¶
9.1.3.4.1. Overview¶
- Task notification is low overhead API to signal a task from ISR or another task
- We see about a 25% reduction in cycles needed for task switch using task notification vs using semaphores in ideal standalone conditions.
- This is a very freertos specific API and PDK drivers and OSAL will NOT use this.
9.1.3.4.2. Important tips¶
- In practical use-cases, typically cache effects due to cache miss on the larger application code/data, will have a higher effect than overheads of task switch in the smaller OS code.
- So we recommend to NOT use this feature unless really the savings is critical to the end application.
- Here one needs to know the task handle to signal, so it’s difficult to use this API from within a driver library since driver ISR for example does not know the task in which the driver API is called
- Thus use these APIs in applications after thorough analysis and profiling on benefit for the use-case.
9.1.3.5. FreeRTOS Event Groups¶
9.1.3.5.1. Overview¶
- An event group is a set of event bits. Event bits are used to indicate if an event has occurred or not. Event bits are often referred to as event flags.
- The number of bits (or flags) stored within an event group is 24 bits
9.1.3.5.2. Important tips for application writers¶
- Unlike “Event” in SysBIOS where one could give a “AND” mask and “OR” mask to wait on, in FreeRTOS one can only give one “event mask” and then tell if one should use “AND” wait or “OR” wait on the single event mask
- When “set bits” is called from ISR, actual action of setting bits is done within the “Timer task” as a “deferred” function call.
9.1.3.6. FreeRTOS Timers¶
9.1.3.6.1. Overview¶
- Allows users to create one-shot or periodic callbacks at timer resolution of one OS tick, typically 1ms.
- Similar to “Clock” module in SysBIOS
- A timer task executes the callbacks. This timer task is like any other task, nothing special about it.
- PDK default is to set highest priority for this task so that after all ISRs this task will execute
- A SW queue is used to post callbacks or functions to execute on timer expiry, the queue depth is the config option. PDK default is 16
9.1.3.6.2. Important tips¶
- Since a single task executes all the multiple callbacks, the callbacks are recommended to not block and spend too much time, even though in theory blocking calls are allowed.
- Use xTimerPendFunctionCall() to do “deferred ISR” handling, i.e do the most critical work in ISR and do the rest of the work in another function call which gets called right after all ISRs are done. This feature can be used as alternative to SWI in SysBIOS
- Note, do not use FromISR APIs in callbacks, use regular FreeRTOS APIs
9.1.3.7. FreeRTOS Heaps¶
9.1.3.7.1. Default heap¶
- FreeRTOS kernel has multiple heap implementations as defined in portable/MemMang
- A port should compile one of the below heap_{n}.c files to pick the required heap implementation
- heap_1.c
- linear heap allocation, free() not allowed. Typically used when true dynamic alloc is prohibited.
- Obsolete now and not used anymore, since FreeRTOS natively support static alloc mode
- heap_2.c
- Linked list based heap but adjacent free blocks not merged
- Obsolete now and not used anymore, heap_4.c is a better implementation
- heap_3.c
- Uses compiler provided, malloc() and free(), FreeRTOS only makes the calls thread-safe
- Heap size specified via –heap compiler option and placed in .heap section in the linker command file.
- heap_4.c PDK default
- Linked list based heap with adjacent free block merging
- More or less similar to malloc() from compiler and SysBIOS heap implementation
- Memory needs to be provided as a global static array, and placed appropriately in the linker command file.
- heap_5.c
- Same as heap_4.c, + it allows memory to be specified as multiple memory blocks When memory in one block is full, it will alloc from the next block and so on.
- heap_1.c
9.1.3.7.2. User defined heaps¶
- Unlike SysBIOS, FreeRTOS does not support user defined heaps at arbitrary user defined memory locations
- On TI SOCs with multiple levels of memory like L2, L3, DDR, it is very convenient to have ability to create multiple application specified heaps.
- heap_4.c almost does this, but it uses a global variable for heap memory base and size
- Therefore, PDK OSAL implements heap APIs to match SysBIOS as below
- PDK has adapted heap_4.c to take memory base and size as input parameters during heap create. This allows creation of arbitrary number of application heaps to match SysBIOS features
- HeapP.h is the user API
- HeapP_freertos.c, HeapP_freertos_internal.c is the implementation (Note, FreeRTOS kernel code is not modified)
9.1.3.7.3. Important tips¶
- Use –heap in linker command file to specify heap size and place .heap section appropriate memory in the linker command file. This is used by FreeRTOS(heap_4.c) when it needs dynamic memory allocation.
- In general recommend to use FreeRTOS static alloc APIs for tasks, semaphores to keep the application deterministic.
- PDK OSAL uses FreeRTOS static alloc APIs
- Use PDK provided HeapP.h to create arbitrary application heaps as needed.
9.1.3.8. FreeRTOS Additional Modules¶
9.1.3.8.1. Queues¶
- Highly efficient SW queue implementation
- Lowest level primitive in FreeRTOS used internally by almost all modules like tasks, semaphores, mutex
- Thread/ISR safe
- Blocking/non-blocking with timeouts
- Fixed queue depth and fixed queue element size at queue create
- Can be used by application users
9.1.3.8.2. Queue Sets, Event Groups, Stream Buffers, Co-routines¶
- Croutines, used when tasks are deemed too expensive to use, almost unlikely we will ever use these
- Queue Sets, more higher level than queues, built using queues, semaphores. FreeRTOS recommends to use these very carefully. https://www.freertos.org/Pend-on-multiple-rtos-objects.html
- Stream buffers, built using queues, semaphores
- PDK default config keeps these disabled
9.1.3.9. FreeRTOS Hook Functions¶
9.1.3.9.1. Debug Hook Functions¶
- FreeRTOS provides “hook” function callbacks specified in FreeRTOS config.
- These callbacks are invoked by FreeRTOS at specific points or when certain conditions are met
- Stack overflow check, configCHECK_FOR_STACK_OVERFLOW PDK default enabled
- Enables stack overflow checks, two options to detect overflows,
- Option 1: Check if the stack pointer has gone beyond the limit
- Option 2: Put a pattern at top of the stack and if the pattern is overwritten then call out stack overflow PDK default
- NOTE: Depending on the nature of stack overflow, this logic may or may not catch all stack overflows
- Enables stack overflow checks, two options to detect overflows,
- Malloc failed hook, configUSE_MALLOC_FAILED_HOOK PDK default disabled
- Called when pvPortMalloc fails inside FreeRTOS, not very useful, since all APIs return error on memory alloc failure.
- Assert, configASSERT PDK default enabled
- Called when unrecoverable assert condition happens inside FreeRTOS or porting layer
- PDK defines a new config flag configOPTIMIZE_FOR_LATENCY, this can be used to disable all debug hooks and some other configs in FreeRTOS config to minimize FreeRTOS overheads due to debug hooks,
- Recommend to enable all hooks in debug mode and disable all hooks in release mode after applications are reasonably sure assert and overflows will not happen.
- By default configOPTIMIZE_FOR_LATENCY is set to 0, i.e disabled
9.1.3.9.2. Statistics Hook Functions¶
- FreeRTOS provides APIs to query and return time spent in each task and output the results in a nice formatted table
- The hook functions for this feature are enabled in PDK default config when configOPTIMIZE_FOR_LATENCY is 0.
- It uses the same timer as the tick timer to measure task load.
- See also https://www.freertos.org/rtos-run-time-stats.html
9.1.3.9.3. Trace Hooks Functions¶
- FreeRTOS provides more than 70+ hook macros at key points in the kernel to log trace info
- Example,
- traceTASK_SWITCHED_IN, called when a task is being switched into
- traceTASK_SWITCHED_OUT, called when a task is being switched to another task
- This is used by tools like Tracealyzer to log and then visualize task execution and a lot more in a GUI tool, see https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_Trace/FreeRTOS_Plus_Trace.html
- Not enabled in PDK default config
9.1.4. FreeRTOS Migration Guidelines¶
9.1.4.1. Porting of source files¶
Replace all SysBIOS API’s with OSAL API’s / FreeRTOS API’s
Remove SysBIOS Header files and include the OSAL /FreeRTOS headers
Recommend to add OS_init() before any other OS calls (like Task creation, Schedular Start, etc. )
Update “Task Function” to take input params of type void * (or pointer to a specific data type) instead of UArg
Replace Void with void
With usage of FreeRTOS Static API / OSAL API for Task Creation, application should pass the stack memory. For example,
#define APP_TSK_STACK_MAIN (16U * 1024U) static uint8_t gAppTskStackMain[APP_TSK_STACK_MAIN] __attribute__((aligned(32))); TaskP_Params_init(&taskParams); taskParams.stack = gAppTskStackMain; taskParams.stacksize = sizeof (gAppTskStackMain); taskHndl = TaskP_create(mainTask, &taskParams);
With usage of FreeRTOS Static API / OSAL API for Mailbox Creation, application should pass the mailbox buffer memory. For example,
typedef struct App_MailboxObj_s { /* Mailbox Object */ } App_MailboxObj; #define APP_MBOX_MSG_CNT (10U) static uint8_t gAppMbxBuf[sizeof(App_MailboxObj) * APP_MBOX_MSG_CNT] __attribute__ ((aligned(32))); MailboxP_Params_init(&mboxParams); mboxParams.size = sizeof(App_MailboxObj); mboxParams.count = APP_MBOX_MSG_CNT; mboxParams.buf = gAppMbxBuf; mboxParams.bufsize = sizeof(gAppMbxBuf); mboxHndl = MailboxP_create(&mboxParams);
See API Comparison for detailed comparison of commonly used SysBIOS API’s vs equivalent FreeRTOS and OSAL APIs.
9.1.4.2. Building with FreeRTOS¶
- To include PDK OSAL Library for FreeRTOS, use osal_freertos library. This is in contrast to osal_tirtos - PDK OSAL Library for SysBIOS.
- Include the following additional libraries
- freertos <= Library including FreeRTOS Kernel and the Portable layer
- csl_init <= CSL Library for C Startup, MPU/MMU Initialization, etc.
Warning
The above order is important. Library listing should always be from top of SW stack to bottom.For example, including csl_init before freertos may cause issues like application never reaches main.
For FreeRTOS Build, include freertos as external components/interfaces, in place of bios and xdc used with SysBIOS For example,
# List all the external components/interfaces, whose interface header files # need to be included for this component INCLUDE_EXTERNAL_INTERFACES = pdk ifeq ($(BUILD_OS_TYPE), freertos) INCLUDE_EXTERNAL_INTERFACES += freertos endif ifeq ($(BUILD_OS_TYPE), tirtos) INCLUDE_EXTERNAL_INTERFACES += xdc bios endif
9.1.4.3. Linker file for FreeRTOS¶
- The default linker file for FreeRTOS Build (linker_${ISA}_freertos.lds) is preset at ${PDK_INSTALL_DIR}/packages/ti/build/j7200
9.1.4.3.1. Important tips¶
On R5F, Following are major updates required for creating a custom linker files for FreeRTOS Build compared to that for SysBIOS
Include the following Linker Settings
--retain="*(.bootCode)" --retain="*(.startupCode)" --retain="*(.startupData)" --retain="*(.irqStack)" --retain="*(.fiqStack)" --retain="*(.abortStack)" --retain="*(.undStack)" --retain="*(.svcStack)" --fill_value=0 --stack_size=0x4000 --heap_size=0x8000 --entry_point=_freertosresetvectors -stack 0x4000 /* SOFTWARE STACK SIZE */ -heap 0x8000 /* HEAP AREA SIZE */ /*-------------------------------------------*/ /* Stack Sizes for various modes */ /*-------------------------------------------*/ __IRQ_STACK_SIZE = 0x1000; __FIQ_STACK_SIZE = 0x0100; __ABORT_STACK_SIZE = 0x0100; __UND_STACK_SIZE = 0x0100; __SVC_STACK_SIZE = 0x0100;
Note
The following linker settings used in case for SysBIOS is not required.
-e __VECS_ENTRY_POINT --retain="*(.utilsCopyVecsToAtcm)"
- The FreeRTOS default linker file places the reset vectors directly at 0x0(ATCM).
- In case of placing the reset vectors at some different address, configCOPY_RESET_VECTORS in FreeROTSConfig.h should be enabled.
Tip
- When configCOPY_RESET_VECTORS is enabled, the reset vectors are copied to 0x0 during the schedular start.
- This is handled by the FreeRTOS portable layer.
- With SysBIOS, PDK utilsCopyVecsToAtcm was used for a similar scenario.
- In case of SySBIOS, utilsCopyVecsToAtcm was used as XDC reset hook function. So the reset vectors will already by copied to 0x0(ATCM) by the time it reaches main().
- On contrast with FreeRTOS, the portable layer handles the copy of reset vectors to 0x0(ATCM) and this happens during the FreeRTOS schedular start from main().
9.1.4.4. MPU/Cache Settings in FreeRTOS¶
- In FreeRTOS MPU/Cache Settings for various memory regions are configured via CSL API’s during the C/C++ startup routine (_c_int00())
- The default settings (gCslR5MpuCfg) are defined in PDK_INSTALL_DIR/packages/ti/csl/arch/r5/src/startup/startup.c
- This is unlike SysBIOS, in which the MPU/Cache settings were done using the XDC cfg file.
9.1.4.4.1. Important tips for creating Custom MPU/Cache Settings¶
- The default settings gCslR5MpuCfg defined in PDK_INSTALL_DIR/packages/ti/csl/arch/r5/src/startup/startup.c is a weak definition and applications can override the defaults by simply redefining the same.
- Typical use-cases may include adding a new section and/or modifying the default attributes of a memory region.
- Applications may include a new source file which redefines the gCslR5MpuCfg as per the required configuration.
9.1.4.4.1.1. Example¶
The method described above is implemented for IPC example, to modify the Ring Buffer as non-cacheable.
- MPU Config File (r5f_mpu_${soc}_default.c at PDK_INSTALL_DIR/packages/ti/drv/ipc/examples/common/src)
- Re-defines CSL_ArmR5MpuRegionCfg gCslR5MpuCfg[CSL_ARM_R5F_MPU_REGIONS_MAX]
- This structure specifies the entries for mpu configuration to override the default MPU configuration which is part of the CSL init.
9.1.4.5. Exception handling in FreeRTOS¶
For R5F, FreeRTOS in PDK currently only supports Data Abort Exception Callback.
- For other exceptions like Undefined Instruction, Pre-fetch Abort, it ends up in the default exception handler’s infinite while loop.
To register Data Abort Exception Callback for FreeRTOS, use csl/arch/r5/interrupt.h - Intc_RegisterExptnHandlers API
For example,
#include <ti/csl/arch/csl_arch.h> void appDAbtExptnClbkFxn() { /* Define callback function to be executed on * data abort exception */ } /* Register exception handler */ CSL_R5ExptnHandlers appR5ExptnHandlers; Intc_InitExptnHandlers(&appR5ExptnHandlers); appR5ExptnHandlers.dabtExptnHandler = &appDAbtExptnClbkFxn; Intc_RegisterExptnHandlers(&appR5ExptnHandlers);
9.1.4.5.1. Important tips¶
- In case of SysBIOS, this was setup via XDC cfg and it directly plug in the passed hook function to the reset vectors.
- On contrast with FreeRTOS, the data abort exception ends up in a default exception handler and will in-turn redirect to callback function(if registered)
- As a result the callback function can be a normal function, i.e. it shouldn’t take care of returning from an interrupt, etc.
9.1.4.6. Reset Hook Function Alternative for FreeRTOS¶
SysBIOS supported reset hook functions (functions to call at reset), since the startup code was also part of XDC(BIOS).
- In case fo FreeRTOS, the startup code is not part of FreeRTOS Kernel and hence reset hooks functions are not supported.
- Here startup code is part of CSL Init.
- As an alternative to reset hook functions, applications can redefine the CSL Startup API _system_post_cinit to achieve similar functionality.
- _system_post_cinit() is a hook function called in the C/C++ auto-initialization function after cinit() and before pinit().
- FreeRTOS portable layer have a default weak definition for _system_post_cinit at ${PDK_INSTALL_PATH}/packages/ti/kernel/freertos/portable/TI_CGT/${ISA}/port.c
- Application can redefine this in the source file to add the code to be executed on reset. For example,
#include <ti/csl/arch/csl_arch.h> void _system_post_cinit(void) { /* Following is the default implementation in portable layer */ osalArch_Config_t cfg; cfg.disableIrqOnInit = true; osalArch_Init(&cfg); /* --------------------------------------------------------*/ /* Add here application specific code, to be done on reset */ /* --------------------------------------------------------*/ }
9.1.5. API Comparison¶
The following section compares commonly used SysBIOS API’s vs equivalent FreeRTOS and OSAL APIs. For more detailed info on the same refer the individual API Guides.
9.1.5.1. Scheduler / General¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
-NA- | -NA- | OS_init() | Recommend to add OS_init() before any other OS calls (like Task creation, Schedular Start, etc. ) |
BIOS_start | vTaskStartScheduler() | OS_start() | Starts the Scheduler |
BIOS_exit(0) | vTaskEndScheduler() | OS_stop() | Stops the Scheduler |
BIOS_WAIT_FOREVER | portMAX_DELAY | osal_WAIT_FOREVER | Macro for timeout wait forever |
9.1.5.2. Tasks¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
Task_Params_init | -NA- | TaskP_Params_init | |
Task_construct | xTaskCreateStatic | TaskP_create |
|
Task_destruct | vTaskDelete | TaskP_delete | |
Task_sleep | vTaskDelay | TaskP_sleep | |
Task_setPri | vTaskPrioritySet | TaskP_setPrio | |
Task_self | xTaskGetCurrentTaskHandle | TaskP_self | |
Task_yield | taskYIELD | Task_yield | |
Task_getMode | eTaskGetState | TaskP_isTerminated |
|
Task_Handle | TaskHandle_t | TaskP_Handle | |
Task_Params | Arguments to create function | TaskP_Params |
9.1.5.3. Semaphores¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
Semaphore_Params_init | -NA- | SemaphoreP_Params_init | |
Semaphore_construct | xSemaphoreCreateBinaryStatic / xSemaphoreCreateCountingStatic | SemaphoreP_create |
|
Semaphore_destruct | vSemaphoreDelete | SemaphoreP_delete | |
Semaphore_pend | xSemaphoreTake / xSemaphoreTakeFromISR | SemaphoreP_pend |
|
Semaphore_post | xSemaphoreGive / xSemaphoreGiveFromISR | SemaphoreP_post |
|
Semaphore_getCount | uxSemaphoreGetCount | SemaphoreP_getCount | |
Semaphore_reset | -NA- | SemaphoreP_reset |
|
Semaphore_Handle | SemaphoreHandle_t | SemaphoreP_Handle | |
Semaphore_Params | Arguments to create function | SemaphoreP_Params |
9.1.5.4. Mutex¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
GateMutexPri_construct | xSemaphoreCreateRecursiveMutexStatic | MutexP_create | |
GateMutexPri_destruct | vSemaphoreDelete | MutexP_delete | |
GateMutexPri_enter | xSemaphoreTakeRecursive | MutexP_lock |
|
GateMutexPri_leave | xSemaphoreGiveRecursive | MutexP_unlock |
|
GateMutexPri_Handle | SemaphoreHandle_t | MutexP_Handle |
9.1.5.5. Software Timers¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
Clock_Params_init | -NA- | ClockP_Params_init | |
Clock_construct | xTimerCreateStatic | ClockP_create |
|
Clock_destruct | xTimerDelete | ClockP_delete | |
Clock_start | xTimerStart / xTimerStartFromISR | ClockP_start |
|
Clock_stop | xTimerStop / xTimerStopFromISR | ClockP_stop |
|
Clock_Handle | TimerHandle_t | ClockP_Handle | |
Clock_Params | Arguments to create function | ClockP_Params |
|
9.1.5.6. Events¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
Event_construct | xEventGroupCreateStatic | EventP_create |
|
Event_destruct | vEventGroupDelete | EventP_delete | |
Event_pend | xEventGroupWaitBits | EventP_wait |
|
Event_post | xEventGroupSetBits / xEventGroupSetBitsFromISR | EventP_post |
|
Event_getPostedEvents | xEventGroupGetBits / xEventGroupGetBitsFromISR | EventP_getPostedEvents | |
Event_Handle | EventGroupHandle_t | EventP_Handle |
9.1.5.7. Mailbox¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
Mailbox_Params_init | -NA- | MailboxP_Params_init | |
Mailbox_construct | xQueueCreateStatic | MailboxP_create |
|
Mailbox_destruct | vQueueDelete | MailboxP_delete | |
Mailbox_post | xQueueSendToBack / xQueueSendToBackFromISR | MailboxP_post | |
Mailbox_pend | xQueueReceive / xQueueReceiveFromISR | MailboxP_pend | |
Mailbox_getNumPendingMsgs | uxQueueMessagesWaiting / uxQueueMessagesWaitingFromISR | MailboxP_getNumPendingMsgs | |
Mailbox_Handle | QueueHandle_t | MailboxP_Handle | |
Mailbox_Params | Arguments to create function | MailboxP_Params |
|
9.1.5.8. Queue¶
SysBIOS | FreeRTOS | OSAL | Comments |
---|---|---|---|
Queue_construct | vListInitialise | QueueP_create | |
Queue_destruct | -NA- | QueueP_delete | |
Queue_get | listGET_HEAD_ENTRY | QueueP_get | |
Queue_put | vListInsertEnd | QueueP_put | |
Queue_empty | listLIST_IS_EMPTY | QueueP_isEmpty | |
Queue_Handle | pxList | QueueP_Handle |
9.1.5.9. Arbitrary Heaps¶
FreeRTOS doesn’t support creating arbitrary heaps. The following table compares the SysBIOS HeapMem with the OSAL HeapP implementation.
SysBIOS | OSAL | Comments |
---|---|---|
HeapMem_Params_init | HeapP_Params_init | |
HeapMem_construct | HeapP_create | Takes only HeapP_Params as i/p param |
HeapMem_destruct | HeapP_delete | |
HeapMem_alloc | HeapP_alloc |
|
HeapMem_free | HeapP_free | |
HeapMem_getStats | HeapP_getHeapStats | |
HeapMem_Struct | -NA- | Not required to pass the structure from application. OSAL internally handles this |
HeapMem_Params | HeapP_Params |
|
HeapMem_Handle | HeapP_Handle |
|
9.1.5.10. Task / CPU Load¶
Refer FreeRTOS native Run-time stats APIs Documentation at https://www.freertos.org/rtos-run-time-stats.html
Following table compares the SysBIOS Load module with the OSAL LoadP implementation for FreeRTOS.
SysBIOS | OSAL for FreeRTOS | Comments |
---|---|---|
Load_Stat | LoadP_Stats | Structure with Load statistics info
|
Load_reset | LoadP_reset | Function to Reset load statistics Until load statistics is reset the load statistics keep getting accumulated. |
Load_getTaskLoad | LoadP_getTaskLoad | |
Load_getCPULoad | LoadP_getCPULoad |
9.1.5.11. Cache Operations¶
Cache operations are not supported as part of FreeRTOS Kernel.
Following table compares the SysBIOS and OSAL Cache APIs.
SysBIOS | OSAL | Comments |
---|---|---|
Cache_wb | CacheP_wb |
|
Cache_inv | CacheP_Inv | |
Cache_wbInv | CacheP_wbInv |
9.1.5.12. HW Interrupts¶
HW Interrupts are not supported as part of FreeRTOS Kernel.
Following table compares the SysBIOS and OSAL HW Interrupt APIs.
SysBIOS | OSAL |
---|---|
Hwi_Params_init | HwiP_Params_init |
Hwi_construct | HwiP_create |
Hwi_destruct | HwiP_delete |
Hwi_disable | HwiP_disable |
Hwi_restore | HwiP_restore |
Hwi_disableInterrupt | HwiP_disableInterrupt |
Hwi_enableInterrupt | HwiP_enableInterrupt |
Hwi_clearInterrupt | HwiP_clearInterrupt |
Hwi_post | HwiP_post |
9.1.5.13. HW Timers¶
HW Timers are not supported as part of FreeRTOS Kernel.
Following table compares the SysBIOS and OSAL HW Timer APIs.
SysBIOS | OSAL |
---|---|
Timer_Params_init | TimerP_Params_init |
Timer_construct | TimerP_create |
Timer_destruct | TimerP_delete |
Timer_start | TimerP_start |
Timer_stop | TimerP_stop |
Timer_setPeriodMicroSecs | TimerP_setPeriodMicroSecs |
9.1.6. FAQ / Important Notes¶
9.1.6.1. App performance with FreeRTOS is very low compared to SysBIOS¶
Check the MPU/Cache Settings. Unlike SysBIOS, this is now done with CSL init.
SysBIOS used XDC based config to set MPU/Cache for various memory regions.
Refer MPU/Cache Settings in FreeRTOS for more details.
In case of adding new source file to redefine the default mpu/cache settings, make sure that this new source file is included in the build / added in makefile.
9.1.6.2. Application never reaches main() and .startUpCode, .startUpData, .bootCode is not found in the map file¶
Check the order of inclusion of various libraries. Library listing should always be from top of SW stack to bottom.
Do not include csl_init lib before freertos lib.
See Building with FreeRTOS for more details.