CMSIS-RTOS API参考手册

【实例简介】
CMSIS-RTOS API参考手册 V1.02 ，根据Keil官方网站文档整理，方便使用FreeRTOS、uc/os等底层操作系统的
The CMsis-RTos APi is designed to optionally incorporate multi-processor systems and or access protection via the Cortex-M Memory protection Unit(MPU) In some RTos implementations threads may execute on different processors and Mail and Message ueues can therefore reside in shared memory resources The CMSIS-RTOs API encourages the software industry to evolve existing RTos implementations Kernel objects are defined and accessed using macros. this allows differentiation rtos implementations can be different and optimized in various aspects towards the Cortex-M processors Optional features may be for example Generic wait function; i.e. with support of time intervals Support of the Cortex-M Memory Protection Unit(MPU) Zero-copy mail queue Support of multi-processor systems Support of a dma controller Deterministic context switching Round-robin context switching Deadlock avoidance, for example with priority inversion Zero interrupt latency by using the Cortex-M3/M4 instructions LDREX and STREX Function overview The following list provides a brief overview of all CMSIS-RTOS functions. Functions marked with $s are optional, A specific CMsIs-Rtos implementation may not provide all functions but this is clearly indicated with osFeature XXXX defines Note Functions that are not supported by the rTX Implementation are marked with a(*) Kernel Information and contro osKernelinitialize. Initia lize the rtos kernel osKernelstart. start the rtos kernel osKernelRunning Query if the rtos kernel is running osKernelSysTick: Get RTOs kernel system timer counter. osKernelsys TickFrequency: Rtos kernel system timer frequency in Hz. osKernelSysTickMicroSec Convert microseconds value to Rtos kernel system timer value Thread Management os Thread Create: Start execution of a thread function osThreadTerminate: Stop execution of a thread function osThreadYield Pass execution to next ready thread function osThreadGetId: Get the thread identifier to reference this thread os ThreadsetPriority Change the execution priority of a thread function osThreadGetPriority Obtain the current execution priority of a thread function Generic Wait Functions os Delay Wait for a specified tim Time swait: Wait for any event of the type Signal, Message, or Mail. (* Management osTimerCreate: Define attributes of the timer callback function osTimerStart Start or restart the timer with a time value osTimerstop: Stop the timer. osTimerDelete: Delete a timer Signal Events ossignalset Set signal flags of a thread. osSignalClear: Reset signal flags of a thread os SignalWait Suspend execution until specific signal flags are set. · Mutexes Os Mutex Create: Define and initialize a mutex os MutexWait obtain a mutex or wait until it becomes available osMutexRelease: Release a mutex os MutexDelete: Delete a mutex · Semaphores oSSemaphore Create Define and initialize a semaphore osSemaphoreWait: obtain a semaphore token or Wait until it becomes available osSemaphoreRelease: Release a semaphore token osSemaphoreDelete: Delete a semaphore Memory Pool osPoolCreate Define and initialize a fix-size memory pool os PoolAlloc Allocate a memory block. OsPool CAlloc Allocate a memory block and zero-set this block. osPoolFree: Return a memory black to the memory pool · Message Queue osMessageCreate: Define and initialize a message queue os MessagePut: Put a message into a message queue. os Get Get a message or suspend thread execution until message arrives. Mail Queue osMailCreate: Define and initialize a mail queue with fix-size memory blocks OSMailAlloc: Allocate a memory block OSMailCAlloc Allocate a memory block and zero-set this block osMaillPut: Put a memory block into a mail queue osMailGet: Get a mail or suspend thread execution until mail arrives. osMailFree Return a memory block to the mail queue RTX Specific Functions os idle demon: System thread running when no other thread is ready to run os suspend: Suspend the rtx task scheduler. os resume: Resume the rtx task scheduler os tick init: Initialize an alternative hardware timer as rtx kernel timer. os tick val: get alternative hardware timer's current value os tick ovf: Get alternative hardware timers overflow flag os tick irgack: Acknowledge alternative hardware timer interrupt os error: Called when a runtime error is detected Timout value The timeout value specifies the number of timer ticks until a timeout or time delay elapses. The value is an upper bound and depends on the actual time elapsed since the last timer tick r a value of 1 the system waits until the next timer tick occurs. that means that the actual timeout value can be one timer tick less than the specified timeout value Timer Ticks Timer Value Timer values Calls from Interrupt Service Routines The following CMsis-RTos functions can be called from threads and interrupt service Routines (isr: osKernelRunning osSigna ISet osSemaphore Release osPoolAloc, osPoo calloc, os PoolFree osMessagePut, osMessageGet osMailAlloc, os MailcAlloc, osMailget, osMailPut, osMailFree Functions that cannot be called from an isr are verifying the interrupt status and return in case they are called from an iSr context, the status code os ErrorIsR. In some implementations, this condition might be caught using the HARd FAULT vector. Some CMsis-RTos implementations support CMSIS-RTOS function calls from multiple iSrs at the same time. If this is im possible the cmsis-Rtos rejects calls by nested iSr functions with the status code OS ErrorisRRecursive Kernel information and control CMSIS-RTOS API Provide version/system information and start the rtos kernel more Macros #define os Feature MainThread 1 main thread 1=main can be thread 0=not available more define osFeature Sys Tick 1 osKernelSysTick functions: 1=available, 0=not available More #define oscMSIs 0x10002 API version(main [31: 16]. sub [15: 0])More #define oscMsIS KErNEl 0x 10000 RTOS identification and version(main [31: 16].sub [15: 0] More # define oskernelsystemIdKERNEL V100 RTOS identification string. More # define osKernelSys Tick Frequency 100000000 The Rtos kernel system timer frequency in Hz. More define osKernelsysTickMicro Sec(microsec)(((uint64_t microsec (osKernelSysTick Frequency)/1000000) Convert a microseconds value to a rtos kernel system timer value, More. Functions osStatus skErne lize(void) Initialize the rtos Kernel for creating objects. More osStatus osKernelstart (void) Start the rtos Kernel, more int32_t osKernelRunning(void) Check if the rtos kernel is already started. more uint32 t oskernelsys Tick(void) Get the rtos kernel system timer counter. More Description The Kernel Information and Control function group allows to: obtain information about the system and the underlying kernel obtain version information about the CmsIs-rtos api initialize of the Rtos kernel for creating objects start the rtos kernel and thread switching check the execution status of the rtos kernel The function main is a special thread function that may be started at system initialization. In this case it has the initial priority osPriority Normal When reaching main it is necessary to 1. Call osKernelInitializeo to initialize the CMsIs-Rtos Kernel 2. Setup device peripherals and create other Rtos objects using the os*Create functions 3. Start the Kernel and begin thread switching by calling osKernelstart() Code Example int main (void) osKernelInitialize O l/ initialize CMS IS-RTOS // initialize peripherals here // create thread functions that start executing / example: tid name osThreadCreate (osThread (name), NULL) osKernel Start O // start thread execution Macro Definition Documentation define oscMsIs 0x10002 Version information of the CMsis RToS APi whereby major version is in bits [31: 16] and sub version in bits [15: 0]. The value 0x10000 represents version 1.00. Note MUST REMAIN UNCHANGED: OSCMSIS identifies the cmsIs-rtos APi version *define osCMSIS KERNEL 0x10000 Identifies the underlying rtos kernel and version number. the actual name of that define depends on the rtos Kernel used in the implementation. For example, oscMsIS_FreeRTos identifies the FreeRtos kernel and the value indicates the version number of that kernel whereby the major version is in bits [31: 16] and sub version in bits [15: 0]. The value 0x10000 represents version 1.00 note CAN BE CHANGED: oSCMSIS KERNEL identifies the underlying RTos kernel and version number Define os Feature MainThread 1 A CMSIS-RTOS implementation may support to start thread execution with the function main When os Feature MainThread is 1 the rtos offers to start with 'main the rtos kernel is in this case already started When osFeature_Main Thread is o the rtos requires explicit start with osKernelstart CMSIS-RTOS RTX Setting: osFeature_MainThread is 1 Note MUST REMAIN UNCHANGED: osFeature xxx shall be consistent in every CMSIS-RTOS *define os Feature SysTick 1 A CMSIS-RTos implementation may provide access to the rtos kernel system timer. When osFeature SysTick is 1 access to the rtos kernel system timer is provided with osKernelSysTick, osKernelsysTick Frequency, and osKernelSysTick Microsec When osFeature SysTick is 0 access to the Rtos kernel system timer is not implemented CMSIS-RTOS RTX Setting: osFeature_ SysTick is 1 *define oskernelsystemId KERNEL V1.00 Defines a string that identifies the underlying RToS Kernel and provides version information the length of that string is limited to 21 bytes. a valid identification string is for example FreeRTOS v1.00" Note MUST REMAIN UNCHANGED: osKernelSystemId shall be consistent in every CMSIS-RTOs #define oskernelsys Tick Frequency 100000000 Specifies the frequency of the Kernel SysTick timer in Hz. the value is ty pically use to scale a time value and is for example used in osKernelsys Tick MicroSec See Aso skErne sysTick Note Reflects the system timer setting and is typically defined in a configuration file Redefine ((uint64 t)microsec s osKerneIsysTickMicroSec( microsec)(osKerneISys Tick Frequency))/1000000) Allows you to scale a microsecond value to the frequency of the Kernel Sys Tick timer. This macro is ty pically used to check for short timeouts in polling loops See Also osKernelsys Tick Parameters microsec time value in microseconds Returns time value normalized to the os KernelSysTickFrequency Function documentation osStatus oskernelInitialize( void Returns status code that indicates the execution status of the function Note MUST REMAIN UNCHANGED: osKernelInitialize shall be consistent in every CMSIS-RTOS Initialize of the rtos Kernel to allow peripheral setup and creation of other rtos objects with the functions osThread Create: Create a thread function osTimerCreate: Define attributes of the timer callback function osMutex Create: Define and initialize a mutex oSSema phore Create Define and initialize a semaphore osPool Create Define and initialize a fix-size memory pool osMessage Create: Define and initialize a message queue osMailCreate: Define and initialize a mail queue with fix-size memory blocks The rtos kernel does not start thread switching until the function osKerne start is called Note In case that the rtos kernel starts thread execution with the function main the function osKernelInitialize stops thread switching. This allows you to setup the system to a defined state before thread switching is resumed with osKernelstart Code Example #include cmsis os, h nt main (void) if (!osKcrnclRunning () / if kernel is not running, initialize the kernel if (osKernellnitialize (!= osOk) // check osStatus for other possible valid values // exit with an error message int32 t osKerneIRunning( void Note MUST REMAIN UNCHANGED: osKernelRunning shall be consistent in every CMsIS-RTOs Returns O RTOS is not started 1 rtos is started Identifies if the rtos kernel is started. For systems with the option to start the main function as a thread this allows you to identify that the rtos kernel is a ready running Not Interrupt service Routines can call this function Code Example #includecmsis os h int main (void( // program execution starts here if (osKcrnclRunning () i / main is already a thread function osStatus oskernelstart( void Returns status code that indicates the execution status of the function Note MUST REMAIN UNCHANGED: skErne start shall be consistent in every CMsIs-RTOS Start the rtos Kernel and begin thread switching NO ote When the CMsIs-rtos starts thread execution with the function main this function resumes thread switching. The main thread will continue executing after osKernelstart. Status and Error codes osOK: the rtos kernel has been successfully started OsErrorISR: osKernelstart cannot be called from interrupt service routines Note Cannot be called from Interrupt service Routines Code Example #include cmsis os. h int main (void) i if(oskernelInitialize (!=osOk) / check osStatus for other possible valid values // cxit with an crror mcssagc if (!osKernelRunning O) t // is the kernel running if (osKernelStart (!=os0K) l start the kernel // kernel could not be started 【实例截图】
【核心代码】