| CMSIS-RTOS2 Real-Time Operating System API |

Loading...
Searching...
No Matches
Safety Classes

RTOS Objects and MPU Protection explains that MPU Protected Zones do not provide full access protection to RTOS objects accessed via CMSIS-RTOS2 API. The concept of a safety class fills this gap.

Every RTOS object, including thread is assigned with a numeric safety class value. A thread cannot modify an RTOS object if its safety class value is higher than the safety class value of the thread. For example, it is not possible to change the priority or suspend a thread that has a higher safety class value than the thread that is currently executed.

Function references

- Following functions and macros are used explicitly for managing safety classes:
  - osSafetyClass : Safety class value in attribute bit field format.
  - osThreadGetClass : Get safety class of a thread.
  - osSafetyWithSameClass : Objects with same safety class.
  - osSafetyWithLowerClass : Objects with lower safety class.
  - osKernelProtect : Protect the RTOS Kernel scheduler access.
  - osThreadSuspendClass : Suspend execution of threads for specified safety classes.
  - osThreadResumeClass : Resume execution of threads for specified safety classes.
  - osKernelDestroyClass : Destroy objects for specified safety classes.
- CMSIS-RTOS2 API functions that support safety class assignment when creating RTOS objects are listed in Assign Safety Class to an RTOS Object.
- CMSIS-RTOS2 API functions that verify safety class assignment before execution are listed in Handle Object Access Violation lists.

# Assign Safety Class to an RTOS Object

It is possible to create any objects regardless of the safety class after the kernel initialize with osKernelInitialize, but before the kernel is started with osKernelStart. This allows to setup a system before actually starting the RTOS kernel.

Threads of a higher safety class can create RTOS objects that belong to a lower or same safety class. For the object types listed below, the attr_bits can have an optional safety class value that is assigned when the RTOS object is created with the os<Object>New function. The macro osSafetyClass encodes the value for the attr_bits field in the attr struct. For example:

const osEventFlagsAttr_t evt_flags_attr = {
.attr_bits = osSafetyClass(SAFETY_CLASS_SAFE_MODE_OPERATION)
};
osEventFlagsId_t evt_flags;
evt_flags = osEventFlagsNew(&evt_flags_attr);

The following object types support safety class assignment when creating an object with corresponding os<Object>New function:

- osThreadAttr_t Attributes structure for thread. Used in the osThreadNew function.
- osEventFlagsAttr_t Attributes structure for event flags. Used in the osThreadNew function.
- osTimerAttr_t Attributes structure for timer. Used in the osTimerNew function.
- osMutexAttr_t Attributes structure for mutex. Used in the osMutexNew function.
- osSemaphoreAttr_t Attributes structure for semaphore. Used in the osSemaphoreNew function.
- osMemoryPoolAttr_t Attributes structure for memory pool. Used in the osMemoryPoolNew function.
- osMessageQueueAttr_t Attributes structure for message queue. Used in the osMessageQueueNew function.

If safety class is not provided when creating the RTOS object then it inherits the safety class of the current running thread that creates the object. If the object is created before kernel is started and no safety class is provided, then it receives default safety class 0. This simplifies integration of third-party code that can be classified as non-safety critical.

# Handle Object Access Violation

RTOS API call returns error code osErrorSafetyClass if the requested object manipulation cannot be performed because the target object has higher safety class than the safety class of the running thread. For example:

status = osEventFlagsSet(evt_flags, 1);
if (status == osErrorSafetyClass)
{
//handle the safety class error
}

Following functions compare the safety class of the running thread with the safety class of the target object.

In Kernel Information and Control functions:

Comparison is done with safety class configured with osKernelProtect

- osKernelLock
- osKernelRestoreLock
- osKernelSuspend
- osKernelProtect
- osKernelDestroyClass

In Thread Management functions:

- osThreadNew
- osThreadSetPriority
- osThreadSuspend
- osThreadResume
- osThreadDetach
- osThreadJoin
- osThreadTerminate
- osThreadSuspendClass
- osThreadResumeClass

In Thread Flags functions:

- osThreadFlagsSet

In Event Flags functions:

- osEventFlagsNew
- osEventFlagsSet
- osEventFlagsClear
- osEventFlagsWait
- osEventFlagsDelete

In Timer Management functions:

- osTimerNew
- osTimerStart
- osTimerStop
- osTimerDelete

In Mutex Management functions:

- osMutexNew
- osMutexAcquire
- osMutexDelete

In Semaphores functions:

- osSemaphoreNew
- osSemaphoreAcquire
- osSemaphoreRelease
- osSemaphoreDelete

In Memory Pool functions:

- osMemoryPoolNew
- osMemoryPoolAlloc
- osMemoryPoolFree
- osMemoryPoolDelete

In Message Queue functions:

- osMessageQueueNew
- osMessageQueuePut
- osMessageQueueGet
- osMessageQueueReset
- osMessageQueueDelete