begriffs open source - cmsis-freertos/blob - Documentation/Doxygen/src/technical_data.md

   1 # Technical Data and Limitations {#page_technical_data}
   2
   3 This lists the technical data of CMSIS-FreeRTOS.
   4
   5 ## Limitations
   6
   7 The following list briefly describes the limitations and unsupported features of the CMSIS-RTOS2 wrapper for FreeRTOS:
   8
   9 - Static memory allocation will only work if *all* memory (from attributes structure) is provided statically. In order to allocate object memory statically, you need to:
  10   - provide the memory for control blocks and stack in the `osThreadAttr_t` structure for threads.
  11   - provide the memory for control blocks and message data in the `osMessageQueueAttr_t` structure for memory queues.
  12   - provide the memory for control blocks for other objects in the object's attributes structure.
  13 - Each timer object requires additional 8 bytes of memory:
  14   - to allocate all memory statically, provide the memory for control block of size (sizeof(StaticTimer_t) + 8 bytes)
  15   - otherwise, additional 8 bytes of dynamic memory will be used
  16 - `osKernelSuspend` and `osKernelResume` are not supported.
  17 - `osThreadDetach`, `osThreadJoin()` and attribute `osThreadJoinable` are not supported (`osThreadNew` returns NULL when `osThreadJoinable` attribute is specified).
  18 - `osThreadGetStackSize` is not implemented.
  19 - Event flags are limited to 24 bits.
  20 - `osEventFlagsGetName` is not implemented.
  21 - `osEventFlagsWait` cannot be called from an ISR.
  22 - Priority inherit protocol is used as default mutex behavior (`osMutexNew` creates priority inherit mutex object by default and ignores `osMutexPrioInherit` attribute when specified).
  23 - Robust mutex objects are not supported (`osMutexNew` returns NULL when `osMutexRobust` attribute is specified).
  24 - `osMutexGetName` is not implemented and always returns NULL.
  25 - `osSemaphoreGetName` is not implemented and always returns NULL.
  26 - `osMessageQueueGetName` is not implemented and always returns NULL.
  27 - `osMessageQueuePut` and `osMessageQueueGet` always ignore message priority.
  28 - *Process Isolation (Functional Safety)* functions are not implemented.
  29
  30 ## Validation Suite Results
  31
  32 CMSIS provides a [CMSIS-RTOS2 validation suite](https://arm-software.github.io/CMSIS_6/latest/RTOS2/rtosValidation.html) that can be used to test a real-time operating system for compliance to the standard. The test suite has been executed successfully on the CMSIS-FreeRTOS implementation ([see results](cmsis_rtos2_validation.txt)).
  33
  34 The following table explains the exceptions:
  35
  36 | Test Case                  | Result         | Reason               | Summary                                                                 |
  37 |----------------------------|----------------|----------------------|-------------------------------------------------------------------------|
  38 | TC_osKernelGetState_2      | not executed   | unsupported feature  | Test attempts to call `osKernelGetState` after a `osKernelSuspend` call. `osKernelSuspend` is not implemented. |
  39 | TC_osKernelLock_2          | not executed   | unsupported feature  | Test attempts to call `osKernelLock` after a `osKernelSuspend` call. `osKernelSuspend` is not implemented. |
  40 | TC_osKernelUnlock_2        | not executed   | unsupported feature  | Test attempts to call `osKernelUnlock` after a `osKernelSuspend` call. `osKernelSuspend` is not implemented. |
  41 | TC_osKernelSuspend_1       | not executed   | unsupported feature  | Test validates `osKernelSuspend` which is not implemented. |
  42 | TC_osKernelResume_1        | not executed   | unsupported feature  | Test validates `osKernelResume` which is not implemented. |
  43 | TC_osThreadNew_3           | not executed   | unsupported feature  | Test attempts to create joinable thread using `osThreadJoinable` attribute. FreeRTOS does not support joinable threads. |
  44 | TC_osThreadGetName_1       | failed         | deviation            | Test attempt to retrieve a name on an unnamed thread. An empty string is returned instead of NULL pointer. |
  45 | TC_osThreadGetState_3      | not executed   | unsupported feature  | Test attempts to retrieve a state of a terminated joinable thread. FreeRTOS does not support joinable threads. |
  46 | TC_osThreadDetach_1        | not executed   | unsupported feature  | Test validates `osThreadDetach` which is not implemented. |
  47 | TC_osThreadDetach_2        | not executed   | unsupported feature  | Test validates `osThreadDetach` which is not implemented. |
  48 | TC_osThreadJoin_1          | not executed   | unsupported feature  | Test validates `osThreadJoin` which is not implemented. |
  49 | TC_osThreadJoin_2          | not executed   | unsupported feature  | Test validates `osThreadJoin` which is not implemented. |
  50 | TC_osThreadJoin_3          | not executed   | unsupported feature  | Test validates `osThreadJoin` which is not implemented. |
  51 | TC_osThreadGetStackSize_1  | not executed   | unsupported feature  | Test validates `osThreadGetStackSize` which is not implemented. |
  52 | TC_ThreadReturn            | not executed   | unsupported feature  | Test attempts to terminate a thread by just returning from a thread. FreeRTOS threads may not return. |
  53 | TC_osEventFlagsSet_1       | failed         | deviation            | Test attempts to set event flags by calling `osEventFlagsSet` multiple times without leaving ISR handler. To process ISR requests, FreeRTOS uses timer deamon which wakes-up after ISR execution. |
  54 | TC_osEventFlagsClear_1     | failed         | deviation            | Test attempts to clear event flags by calling `osEventFlagsClear` multiple times without leaving ISR handler. To process ISR requests, FreeRTOS uses timer deamon which wakes-up after ISR execution. |
  55 | TC_osEventFlagsWait_1      | failed         | unsupported feature  | Test attempts to wait for flags from ISR with zero timeout (try-semantic). FreeRTOS does not support such operation. |
  56 | TC_osEventFlagsGetName_1   | not executed   | unsupported feature  | Test validates `osEventFlagsGetName` which is not implemented. |
  57 | TC_osMutexNew_4            | not executed   | unsupported feature  | Test attempts to create a robust mutex. FreeRTOS implementation does not support robust mutexes. |
  58 | TC_osMutexGetName_1        | not executed   | unsupported feature  | Test validates `osMutexGetName` which is not implemented. |
  59 | TC_MutexRobust             | not executed   | unsupported feature  | Test attempts to validate robust mutex behavior. FreeRTOS implementation does not support robust mutexes. |
  60 | TC_MutexOwnership          | not executed   | unsupported feature  | Test attempts to release a mutex from a thread which is not the mutex owner. FreeRTOS implementation does not verify ownership on mutex release. |
  61 | TC_osSemaphoreGetName_1    | not executed   | unsupported feature  | Test validates `osSemaphoreGetName` which is not implemented. |
  62 | TC_osMessageQueueGetName_1 | not executed   | unsupported feature  | Test validates `osMessageQueueGetName` which is not implemented. |
  63
  64 ## Troubleshooting
  65
  66 Users looking for help shall check [subsection of the full FreeRTOS FAQ](https://www.freertos.org/Why-FreeRTOS/FAQs). It contains many useful information that also apply when using FreeRTOS in context of CMSIS-FreeRTOS.
  67
  68 Additionally, please take a look at the following:
  69
  70 1. **Interrupts are disabled when main is called or before the kernel is started**
  71
  72     Before the FreeRTOS kernel is started, threads (i.e. tasks) may be created together with other objects like mutexes, semaphores, message queues etc. When functions like `xTaskCreate`, `xSemaphoreCreateMutex`, `xQueueCreate` and others get called, they prevent interrupt handlers from calling FreeRTOS API functions in order to keep FreeRTOS kernel variables and state machine consistent (see also here [Interrupts are not executing](https://www.freertos.org/Why-FreeRTOS/FAQs)). In cases when interrupts may be executed after object creation and before the FreeRTOS kernel is started they can be re-enabled:
  73     ```c
  74         portENABLE_INTERRUPTS();
  75     ```
  76     Make sure that the interrupts you execute in such case do not call FreeRTOS API.