CMSIS Support

Basic Concepts
Development Guidelines

Basic Concepts

The Cortex Microcontroller Software Interface Standard (CMSIS) is a vendor-independent hardware abstraction layer for microcontrollers based on Arm Cortex processors. Of the CMSIS components, the Real Time Operating System (RTOS) defines a set of universal and standardized APIs to reduce the dependency of application developers on specific RTOS and facilitate software porting and reuse. The CMSIS provides CMSIS-RTOS v1 and CMSIS-RTOS v2. The OpenHarmony LiteOS-M supports only the implementation of CMSIS-RTOS v2.

Development Guidelines

Available APIs

The following table describes CMSIS-RTOS v2 APIs. For more details about the APIs, see the API reference.

Table 1 CMSIS-RTOS v2 APIs

Category	API	Description
Kernel information and control	osKernelGetInfo	Obtains RTOS kernel information.
	osKernelGetState	Obtains the current RTOS kernel status.
	osKernelGetSysTimerCount	Obtains the RTOS kernel system timer count.
	osKernelGetSysTimerFreq	Obtains the RTOS kernel system timer frequency.
	osKernelInitialize	Initializes the RTOS kernel.
	osKernelLock	Locks the RTOS kernel scheduler.
	osKernelUnlock	Unlocks the RTOS kernel scheduler.
	osKernelRestoreLock	Restores the RTOS kernel scheduler to the locked state.
	osKernelResume	Restores the RTOS kernel scheduler. (not implemented yet)
	osKernelStart	Starts the RTOS kernel scheduler.
	osKernelSuspend	Suspends the RTOS kernel scheduler. (not implemented yet)
	osKernelGetTickCount	Obtains the RTOS kernel tick count.
	osKernelGetTickFreq	Obtains the RTOS kernel tick frequency.
Thread management	osThreadDetach	Detaches a thread (thread storage can be reclaimed when the thread terminates). (not implemented yet)
	osThreadEnumerate	Enumerates active threads. (not implemented yet)
	osThreadExit	Terminates execution of the thread that is currently running.
	osThreadGetCount	Obtains the number of active threads.
	osThreadGetId	Returns the ID of the thread that is running.
	osThreadGetName	Obtains the name of a thread.
	osThreadGetPriority	Obtains the current priority of a thread.
	osThreadGetStackSize	Obtains the stack size of a thread.
	osThreadGetStackSpace	Obtains the available stack space of a thread based on the stack waterline record during execution.
	osThreadGetState	Obtains the current status of a thread.
	osThreadJoin	Waits for the specified thread to terminate. (not implemented yet)
	osThreadNew	Creates a thread and add it to active threads.
	osThreadResume	Resumes the execution of a thread.
	osThreadSetPriority	Changes the priority of a thread.
	osThreadSuspend	Suspends the execution of a thread.
	osThreadTerminate	Terminates the execution of a thread.
	osThreadYield	Passes control to the next thread in the ready state.
Thread flag	osThreadFlagsSet	Sets the specified thread flags for a thread. (not implemented yet)
	osThreadFlagsClear	Clears the specified thread flags of the thread that is running. (not implemented yet)
	osThreadFlagsGet	Obtains the current thread flags of the thread that is running. (not implemented yet)
	osThreadFlagsWait	Waits for one or more thread flags of the currently running thread to emit a signal. (not implemented yet)
Event flag	osEventFlagsGetName	Obtains the name of an event flag object. (not implemented yet)
	osEventFlagsNew	Creates and initializes an event flag object.
	osEventFlagsDelete	Deletes an event flag object.
	osEventFlagsSet	Sets the specified event flag.
	osEventFlagsClear	Clears the specified event flag.
	osEventFlagsGet	Obtains the current event flag.
	osEventFlagsWait	Waits for one or more event flags to be signaled.
General wait function	osDelay	Waits for timeout (time delay).
General wait function	osDelayUntil	Waits until the specified time.
Timer management	osTimerDelete	Deletes a timer.
	osTimerGetName	Obtains the name of a timer. (not implemented yet)
	osTimerIsRunning	Check whether a timer is running.
	osTimerNew	Creates and initializes a timer.
	osTimerStart	Starts or restarts a timer.
	osTimerStop	Stops a timer.
Mutex management	osMutexAcquire	Acquires a mutex or waits for timeout (if locked).
	osMutexDelete	Deletes a mutex object.
	osMutexGetName	Obtains the name of a mutex object. (not implemented yet)
	osMutexGetOwner	Obtains the thread that has a mutex object.
	osMutexNew	Creates and initializes a mutex object.
	osMutexRelease	Releases the mutex obtained by calling osMutexAcquire.
Semaphore	osSemaphoreAcquire	Obtains a semaphore token or waits for timeout if no token is available.
	osSemaphoreDelete	Deletes a semaphore object.
	osSemaphoreGetCount	Obtains the number of tokens of the current semaphore.
	osSemaphoreGetName	Obtains the name of a semaphore object. (not implemented yet)
	osSemaphoreNew	Creates and initializes a semaphore object.
	osSemaphoreRelease	Releases a semaphore token till the initial maximum count.
Memory pool	osMemoryPoolAlloc	Allocates a memory block from the memory pool.
	osMemoryPoolDelete	Deletes a memory pool object.
	osMemoryPoolFree	Releases the allocated memory block to the memory pool.
	osMemoryPoolGetBlockSize	Obtains the memory block size in the memory pool.
	osMemoryPoolGetCapacity	Obtains the maximum number of memory blocks in the memory pool.
	osMemoryPoolGetCount	Obtains the number of memory blocks used in the memory pool.
	osMemoryPoolGetName	Obtains the name of a memory pool object.
	osMemoryPoolGetSpace	Obtains the number of available memory blocks in the memory pool.
	osMemoryPoolNew	Creates and initializes a memory pool object.
Message queue	osMessageQueueDelete	Deletes a message queue object.
	osMessageQueueGet	Obtains a message from the queue or waits for timeout if the queue is empty.
	osMessageQueueGetCapacity	Obtains the maximum number of messages in a message queue.
	osMessageQueueGetCount	Obtains the number of queued messages in a message queue.
	osMessageQueueGetMsgSize	Obtains the maximum size of the message in the memory pool.
	osMessageQueueGetName	Obtains the name of a message queue object. (not implemented yet)
	osMessageQueueGetSpace	Obtains the number of available slots for messages in a message queue.
	osMessageQueueNew	Creates and initializes a message queue object.
	osMessageQueuePut	Puts the message into the queue or waits till timeout if the queue is full.
	osMessageQueueReset	Resets the message queue to its initial empty state. (not implemented yet)

How to Develop

The CMSIS-RTOS v2 component can be provided as a library (shown in the figure) or source code. By adding the CMSIS-RTOS v2 component (typically configuration files), you can implement RTOS capabilities on CMSIS-based applications. You only need to include the cmsis_os2.h header file. RTOS APIs can then be called to process RTOS kernel-related events. You do not need to recompile the source code when the kernel is replaced.

The RTOS object control block definition needs to be called for static object allocation. The implementation-specific header file (os_xx.h in the following figure) provides access to such control block definitions. In the OpenHarmony LiteOS-M kernel, the header files whose names start with los_ provide the definitions of the kernel.

Development Example

#include ...
#include "cmsis_os2.h"

/*----------------------------------------------------------------------------
 * Application main thread
 *---------------------------------------------------------------------------*/
void app_main (void *argument) {
  // ...
  for (;;) {}
}

int main (void) {
 // Initialize the system.
  MySystemInit();
  // ...

  osKernelInitialize();                // Initialize CMSIS-RTOS.
  osThreadNew(app_main, NULL, NULL);    // Create the main thread of the application.
  osKernelStart();                     // Start to execute the thread.
  for (;;) {}
}