1# RTOS Abstraction
2
3## Overview
4
5The RTOS abstraction layer provides simple RTOS services like threads, semaphores, mutexes, queues, and timers. It is not intended to be a full features RTOS interface, but the provide just enough support to allow for RTOS independent drivers and middleware. This allows middleware applications to be as portable as possible within ModusToolbox™. This library provides a unified API around the actual RTOS. This allows middleware libraries to be written once independent of the RTOS actually selected for the application. The abstraction layer provides access to all the standard RTOS resources listed in the feature section below.
6
7While the primary purpose of the library is for middleware, the abstraction layer can be used by the application code. However, since this API does not provide all RTOS features and the application generally knows what RTOS is being used, this is typically an unnecessary overhead.
8
9All the RTOS abstraction layer functions generally all work the same way. The basic process is:
101. Include the cyabs_rtos.h header file so that you have access to the RTOS functions.
112. Declare a variable of the right type (e.g. cy_mutex_t)
123. Call the appropriate create or initialize function (e.g. cy_rtos_init_mutex()). Provide it with a reference to the variable that was created in step 2.
134. Access the RTOS object using one of the access functions. e.g. cy_rtos_set_mutex().
145. If you don't need it anymore, free up the pointer with the appropriate de-init function (e.g. cy_rtos_deinit_mutex()).
15
16NOTE: All these functions need a pointer, so it is generally best to declare these "shared" resources as static global variables within the file that they are used.
17
18## Getting Started
19
20To use the RTOS Abstraction, simply include a reference to `cyabs_rtos.h` and update the application's makefile to include the appropriate component. e.g. one of:
21* COMPONENTS+=RTX
22* COMPONENTS+=FREERTOS
23* COMPONENTS+=THREADX
24
25## Features
26
27* APIs for interacting with common RTOS Features including:
28    * Threads
29    * Mutexes
30    * Semaphores
31    * Timers
32    * Queues
33    * Events
34* Implementations are provided for
35    * FreeRTOS
36    * RTX (CMSIS RTOS)
37    * ThreadX
38
39## RTOS Configuration Requirements
40### FreeRTOS
41To enable all functionality when using with FreeRTOS, the following configuration options must be enabled in FreeRTOSConfig.h:
42* configSUPPORT_DYNAMIC_ALLOCATION
43* configSUPPORT_STATIC_ALLOCATION
44* configUSE_COUNTING_SEMAPHORES
45* configUSE_MUTEXES
46* configUSE_NEWLIB_REENTRANT
47* configUSE_RECURSIVE_MUTEXES
48* configUSE_TASK_NOTIFICATIONS
49* configUSE_TICKLESS_IDLE
50* configUSE_TIMERS
51* configUSE_TRACE_FACILITY
52
53* INCLUDE_vTaskDelay
54* INCLUDE_vTaskDelete
55* INCLUDE_vTaskPrioritySet
56* INCLUDE_uxTaskPriorityGet
57* INCLUDE_xTimerPendFunctionCall
58* INCLUDE_vTaskSuspend
59
60Enabling configSUPPORT_STATIC_ALLOCATION requires the application to provide implementations for `vApplicationGetIdleTaskMemory` and
61`vApplicationGetTimerTaskMemory`functions. Weak implementations for these functions are provided as a part of this library. These can
62be overridden by the application if custom implementations of these functions are desired.<br>
63
64This library provides an API `vApplicationSleep` which can be used to enable tickless support in FreeRTOS. In order to enable tickless mode with this API, the following changes need to be made in `FreeRTOSConfig.h`:
65* Enables tickless mode with user specified `portSUPPRESS_TICKS_AND_SLEEP` implementation.<br>
66\c \#define `configUSE_TICKLESS_IDLE                       2`
67* Hook `portSUPPRESS_TICKS_AND_SLEEP` macro to `vApplicationSleep` implementation.<br>
68\c \#define `portSUPPRESS_TICKS_AND_SLEEP( xIdleTime )    vApplicationSleep( xIdleTime )`
69
70For further details on Low power support in FreeRTOS please refer to documentation [here](https://www.freertos.org/low-power-tickless-rtos.html)
71
72### RTX / ThreadX
73No specific requirements exist
74
75## Porting Notes
76In order to port to a new environment, the file cyabs_rtos_impl.h must be provided with definitions of some basic types for the abstraction layer.  The types expected to be defined are:
77
78- `cy_thread_t` : typedef from underlying RTOS thread type
79- `cy_thread_arg_t` : typedef from the RTOS type that is passed to the entry function of a thread.
80- `cy_mutex_t` : typedef from the underlying RTOS mutex type
81- `cy_semaphore_t`: typedef from the underlying RTOS semaphore type
82- `cy_event_t` : typedef from the underlying RTOS event type
83- `cy_queue_t` : typedef from the underlying RTOS queue type
84- `cy_timer_callback_arg_t` : typedef from the RTOS type that is passed to the timer callback function
85- `cy_timer_t` : typedef from the underlying RTOS timer type
86- `cy_time_t` : count of time in milliseconds
87- `cy_rtos_error_t` : typedef from the underlying RTOS error type
88
89The enum `cy_thread_priority_t` needs to have the following priority values defined and mapped to RTOS specific values:
90- `CY_RTOS_PRIORITY_MIN`
91- `CY_RTOS_PRIORITY_LOW`
92- `CY_RTOS_PRIORITY_BELOWNORMAL`
93- `CY_RTOS_PRIORITY_NORMAL`
94- `CY_RTOS_PRIORITY_ABOVENORMAL`
95- `CY_RTOS_PRIORITY_HIGH`
96- `CY_RTOS_PRIORITY_REALTIME`
97- `CY_RTOS_PRIORITY_MAX`
98
99Finally, the following macros need to be defined for memory allocations:
100- `CY_RTOS_MIN_STACK_SIZE`
101- `CY_RTOS_ALIGNMENT`
102- `CY_RTOS_ALIGNMENT_MASK`
103
104## More information
105* [API Reference Guide](https://infineon.github.io/abstraction-rtos/html/modules.html)
106* [Cypress Semiconductor, an Infineon Technologies Company](http://www.cypress.com)
107* [Infineon GitHub](https://github.com/infineon)
108* [ModusToolbox™](https://www.cypress.com/products/modustoolbox-software-environment)
109
110---
111© Cypress Semiconductor Corporation (an Infineon company) or an affiliate of Cypress Semiconductor Corporation, 2019-2021.
112