Ashley Mills
local fork
Fork of
mbed-rtos
by 
mbed official
Embed:
(wiki syntax)
Show/hide line numbers
cmsis_os.h
00001 /* ---------------------------------------------------------------------- 00002 * Copyright (C) 2012 ARM Limited. All rights reserved. 00003 * 00004 * $Date: 5. June 2012 00005 * $Revision: V1.01 00006 * 00007 * Project: CMSIS-RTOS API 00008 * Title: cmsis_os.h RTX header file 00009 * 00010 * Version 0.02 00011 * Initial Proposal Phase 00012 * Version 0.03 00013 * osKernelStart added, optional feature: main started as thread 00014 * osSemaphores have standard behavior 00015 * osTimerCreate does not start the timer, added osTimerStart 00016 * osThreadPass is renamed to osThreadYield 00017 * Version 1.01 00018 * Support for C++ interface 00019 * - const attribute removed from the osXxxxDef_t typedef's 00020 * - const attribute added to the osXxxxDef macros 00021 * Added: osTimerDelete, osMutexDelete, osSemaphoreDelete 00022 * Added: osKernelInitialize 00023 * -------------------------------------------------------------------- */ 00024 00025 /** 00026 \page cmsis_os_h Header File Template: cmsis_os.h 00027 00028 The file \b cmsis_os.h is a template header file for a CMSIS-RTOS compliant Real-Time Operating System (RTOS). 00029 Each RTOS that is compliant with CMSIS-RTOS shall provide a specific \b cmsis_os.h header file that represents 00030 its implementation. 00031 00032 The file cmsis_os.h contains: 00033 - CMSIS-RTOS API function definitions 00034 - struct definitions for parameters and return types 00035 - status and priority values used by CMSIS-RTOS API functions 00036 - macros for defining threads and other kernel objects 00037 00038 00039 <b>Name conventions and header file modifications</b> 00040 00041 All definitions are prefixed with \b os to give an unique name space for CMSIS-RTOS functions. 00042 Definitions that are prefixed \b os_ are not used in the application code but local to this header file. 00043 All definitions and functions that belong to a module are grouped and have a common prefix, i.e. \b osThread. 00044 00045 Definitions that are marked with <b>CAN BE CHANGED</b> can be adapted towards the needs of the actual CMSIS-RTOS implementation. 00046 These definitions can be specific to the underlying RTOS kernel. 00047 00048 Definitions that are marked with <b>MUST REMAIN UNCHANGED</b> cannot be altered. Otherwise the CMSIS-RTOS implementation is no longer 00049 compliant to the standard. Note that some functions are optional and need not to be provided by every CMSIS-RTOS implementation. 00050 00051 00052 <b>Function calls from interrupt service routines</b> 00053 00054 The following CMSIS-RTOS functions can be called from threads and interrupt service routines (ISR): 00055 - \ref osSignalSet 00056 - \ref osSemaphoreRelease 00057 - \ref osPoolAlloc, \ref osPoolCAlloc, \ref osPoolFree 00058 - \ref osMessagePut, \ref osMessageGet 00059 - \ref osMailAlloc, \ref osMailCAlloc, \ref osMailGet, \ref osMailPut, \ref osMailFree 00060 00061 Functions that cannot be called from an ISR are verifying the interrupt status and return in case that they are called 00062 from an ISR context the status code \b osErrorISR. In some implementations this condition might be caught using the HARD FAULT vector. 00063 00064 Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISR at the same time. 00065 If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive. 00066 00067 00068 <b>Define and reference object definitions</b> 00069 00070 With <b>\#define osObjectsExternal</b> objects are defined as external symbols. This allows to create a consistent header file 00071 that is used throughout a project as shown below: 00072 00073 <i>Header File</i> 00074 \code 00075 #include <cmsis_os.h> // CMSIS RTOS header file 00076 00077 // Thread definition 00078 extern void thread_sample (void const *argument); // function prototype 00079 osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100); 00080 00081 // Pool definition 00082 osPoolDef(MyPool, 10, long); 00083 \endcode 00084 00085 00086 This header file defines all objects when included in a C/C++ source file. When <b>\#define osObjectsExternal</b> is 00087 present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be 00088 used throughout the whole project. 00089 00090 <i>Example</i> 00091 \code 00092 #include "osObjects.h" // Definition of the CMSIS-RTOS objects 00093 \endcode 00094 00095 \code 00096 #define osObjectExternal // Objects will be defined as external symbols 00097 #include "osObjects.h" // Reference to the CMSIS-RTOS objects 00098 \endcode 00099 00100 */ 00101 00102 #ifndef _CMSIS_OS_H 00103 #define _CMSIS_OS_H 00104 00105 /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version. 00106 #define osCMSIS 0x10001 ///< API version (main [31:16] .sub [15:0]) 00107 00108 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlying RTOS kernel and version number. 00109 #define osCMSIS_RTX ((4<<16)|61) ///< RTOS identification and version (main [31:16] .sub [15:0]) 00110 00111 /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS. 00112 #define osKernelSystemId "RTX V4.61" ///< RTOS identification string 00113 00114 00115 #define CMSIS_OS_RTX 00116 00117 // The stack space occupied is mainly dependent on the underling C standard library 00118 #if defined(TOOLCHAIN_GCC_ARM) || defined(TOOLCHAIN_CS_ARM) || defined(TOOLCHAIN_CR_ARM) 00119 # define WORDS_STACK_SIZE 512 00120 #elif defined(TOOLCHAIN_ARM) 00121 # define WORDS_STACK_SIZE 512 00122 #elif defined(TOOLCHAIN_uARM) 00123 # define WORDS_STACK_SIZE 128 00124 #endif 00125 00126 #define DEFAULT_STACK_SIZE (WORDS_STACK_SIZE*4) 00127 00128 00129 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS. 00130 #define osFeature_MainThread 1 ///< main thread 1=main can be thread, 0=not available 00131 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available 00132 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available 00133 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available 00134 #define osFeature_Signals 16 ///< maximum number of Signal Flags available per thread 00135 #define osFeature_Semaphore 65535 ///< maximum count for \ref osSemaphoreCreate function 00136 #define osFeature_Wait 0 ///< osWait function: 1=available, 0=not available 00137 00138 #if defined (__CC_ARM) 00139 #define os_InRegs __value_in_regs // Compiler specific: force struct in registers 00140 #else 00141 #define os_InRegs 00142 #endif 00143 00144 #include <stdint.h> 00145 #include <stddef.h> 00146 00147 #ifdef __cplusplus 00148 extern "C" 00149 { 00150 #endif 00151 00152 #include "os_tcb.h" 00153 00154 // ==== Enumeration, structures, defines ==== 00155 00156 /// Priority used for thread control. 00157 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS. 00158 typedef enum { 00159 osPriorityIdle = -3, ///< priority: idle (lowest) 00160 osPriorityLow = -2, ///< priority: low 00161 osPriorityBelowNormal = -1, ///< priority: below normal 00162 osPriorityNormal = 0, ///< priority: normal (default) 00163 osPriorityAboveNormal = +1, ///< priority: above normal 00164 osPriorityHigh = +2, ///< priority: high 00165 osPriorityRealtime = +3, ///< priority: realtime (highest) 00166 osPriorityError = 0x84 ///< system cannot determine priority or thread has illegal priority 00167 } osPriority; 00168 00169 /// Timeout value. 00170 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS. 00171 #define osWaitForever 0xFFFFFFFF ///< wait forever timeout value 00172 00173 /// Status code values returned by CMSIS-RTOS functions. 00174 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS. 00175 typedef enum { 00176 osOK = 0, ///< function completed; no error or event occurred. 00177 osEventSignal = 0x08, ///< function completed; signal event occurred. 00178 osEventMessage = 0x10, ///< function completed; message event occurred. 00179 osEventMail = 0x20, ///< function completed; mail event occurred. 00180 osEventTimeout = 0x40, ///< function completed; timeout occurred. 00181 osErrorParameter = 0x80, ///< parameter error: a mandatory parameter was missing or specified an incorrect object. 00182 osErrorResource = 0x81, ///< resource not available: a specified resource was not available. 00183 osErrorTimeoutResource = 0xC1, ///< resource not available within given time: a specified resource was not available within the timeout period. 00184 osErrorISR = 0x82, ///< not allowed in ISR context: the function cannot be called from interrupt service routines. 00185 osErrorISRRecursive = 0x83, ///< function called multiple times from ISR with same object. 00186 osErrorPriority = 0x84, ///< system cannot determine priority or thread has illegal priority. 00187 osErrorNoMemory = 0x85, ///< system is out of memory: it was impossible to allocate or reserve memory for the operation. 00188 osErrorValue = 0x86, ///< value of a parameter is out of range. 00189 osErrorOS = 0xFF, ///< unspecified RTOS error: run-time error but no other error message fits. 00190 os_status_reserved = 0x7FFFFFFF ///< prevent from enum down-size compiler optimization. 00191 } osStatus; 00192 00193 00194 /// Timer type value for the timer definition. 00195 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS. 00196 typedef enum { 00197 osTimerOnce = 0, ///< one-shot timer 00198 osTimerPeriodic = 1 ///< repeating timer 00199 } os_timer_type; 00200 00201 /// Entry point of a thread. 00202 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS. 00203 typedef void (*os_pthread) (void const *argument); 00204 00205 /// Entry point of a timer call back function. 00206 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS. 00207 typedef void (*os_ptimer) (void const *argument); 00208 00209 // >>> the following data type definitions may shall adapted towards a specific RTOS 00210 00211 /// Thread ID identifies the thread (pointer to a thread control block). 00212 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS. 00213 typedef struct os_thread_cb *osThreadId; 00214 00215 /// Timer ID identifies the timer (pointer to a timer control block). 00216 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS. 00217 typedef struct os_timer_cb *osTimerId; 00218 00219 /// Mutex ID identifies the mutex (pointer to a mutex control block). 00220 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS. 00221 typedef struct os_mutex_cb *osMutexId; 00222 00223 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block). 00224 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS. 00225 typedef struct os_semaphore_cb *osSemaphoreId; 00226 00227 /// Pool ID identifies the memory pool (pointer to a memory pool control block). 00228 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS. 00229 typedef struct os_pool_cb *osPoolId; 00230 00231 /// Message ID identifies the message queue (pointer to a message queue control block). 00232 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS. 00233 typedef struct os_messageQ_cb *osMessageQId; 00234 00235 /// Mail ID identifies the mail queue (pointer to a mail queue control block). 00236 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS. 00237 typedef struct os_mailQ_cb *osMailQId; 00238 00239 00240 /// Thread Definition structure contains startup information of a thread. 00241 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS. 00242 typedef struct os_thread_def { 00243 os_pthread pthread; ///< start address of thread function 00244 osPriority tpriority; ///< initial thread priority 00245 uint32_t stacksize; ///< stack size requirements in bytes 00246 unsigned char *stack_pointer; ///< pointer to the stack memory block 00247 struct OS_TCB tcb; 00248 } osThreadDef_t; 00249 00250 /// Timer Definition structure contains timer parameters. 00251 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS. 00252 typedef struct os_timer_def { 00253 os_ptimer ptimer; ///< start address of a timer function 00254 void *timer; ///< pointer to internal data 00255 } osTimerDef_t; 00256 00257 /// Mutex Definition structure contains setup information for a mutex. 00258 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS. 00259 typedef struct os_mutex_def { 00260 void *mutex; ///< pointer to internal data 00261 } osMutexDef_t; 00262 00263 /// Semaphore Definition structure contains setup information for a semaphore. 00264 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS. 00265 typedef struct os_semaphore_def { 00266 void *semaphore; ///< pointer to internal data 00267 } osSemaphoreDef_t; 00268 00269 /// Definition structure for memory block allocation. 00270 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS. 00271 typedef struct os_pool_def { 00272 uint32_t pool_sz; ///< number of items (elements) in the pool 00273 uint32_t item_sz; ///< size of an item 00274 void *pool; ///< pointer to memory for pool 00275 } osPoolDef_t; 00276 00277 /// Definition structure for message queue. 00278 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS. 00279 typedef struct os_messageQ_def { 00280 uint32_t queue_sz; ///< number of elements in the queue 00281 void *pool; ///< memory array for messages 00282 } osMessageQDef_t; 00283 00284 /// Definition structure for mail queue. 00285 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS. 00286 typedef struct os_mailQ_def { 00287 uint32_t queue_sz; ///< number of elements in the queue 00288 uint32_t item_sz; ///< size of an item 00289 void *pool; ///< memory array for mail 00290 } osMailQDef_t; 00291 00292 /// Event structure contains detailed information about an event. 00293 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS. 00294 /// However the struct may be extended at the end. 00295 typedef struct { 00296 osStatus status; ///< status code: event or error information 00297 union { 00298 uint32_t v; ///< message as 32-bit value 00299 void *p; ///< message or mail as void pointer 00300 int32_t signals; ///< signal flags 00301 } value; ///< event value 00302 union { 00303 osMailQId mail_id; ///< mail id obtained by \ref osMailCreate 00304 osMessageQId message_id; ///< message id obtained by \ref osMessageCreate 00305 } def; ///< event definition 00306 } osEvent; 00307 00308 00309 // ==== Kernel Control Functions ==== 00310 00311 /// Initialize the RTOS Kernel for creating objects. 00312 /// \return status code that indicates the execution status of the function. 00313 /// \note MUST REMAIN UNCHANGED: \b osKernelInitialize shall be consistent in every CMSIS-RTOS. 00314 osStatus osKernelInitialize (void); 00315 00316 /// Start the RTOS Kernel. 00317 /// \return status code that indicates the execution status of the function. 00318 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS. 00319 osStatus osKernelStart (void); 00320 00321 /// Check if the RTOS kernel is already started. 00322 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS. 00323 /// \return 0 RTOS is not started, 1 RTOS is started. 00324 int32_t osKernelRunning(void); 00325 00326 00327 // ==== Thread Management ==== 00328 00329 /// Create a Thread Definition with function, priority, and stack requirements. 00330 /// \param name name of the thread function. 00331 /// \param priority initial priority of the thread function. 00332 /// \param stacksz stack size (in bytes) requirements for the thread function. 00333 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the 00334 /// macro body is implementation specific in every CMSIS-RTOS. 00335 #if defined (osObjectsExternal) // object is external 00336 #define osThreadDef(name, priority, stacksz) \ 00337 extern osThreadDef_t os_thread_def_##name 00338 #else // define the object 00339 #define osThreadDef(name, priority, stacksz) \ 00340 unsigned char os_thread_def_stack_##name [stacksz]; \ 00341 osThreadDef_t os_thread_def_##name = \ 00342 { (name), (priority), (stacksz), (os_thread_def_stack_##name)} 00343 #endif 00344 00345 /// Access a Thread definition. 00346 /// \param name name of the thread definition object. 00347 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the 00348 /// macro body is implementation specific in every CMSIS-RTOS. 00349 #define osThread(name) \ 00350 &os_thread_def_##name 00351 00352 /// Create a thread and add it to Active Threads and set it to state READY. 00353 /// \param[in] thread_def thread definition referenced with \ref osThread. 00354 /// \param[in] argument pointer that is passed to the thread function as start argument. 00355 /// \return thread ID for reference by other functions or NULL in case of error. 00356 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS. 00357 osThreadId osThreadCreate (osThreadDef_t *thread_def, void *argument); 00358 00359 /// Return the thread ID of the current running thread. 00360 /// \return thread ID for reference by other functions or NULL in case of error. 00361 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS. 00362 osThreadId osThreadGetId (void); 00363 00364 /// Terminate execution of a thread and remove it from Active Threads. 00365 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00366 /// \return status code that indicates the execution status of the function. 00367 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS. 00368 osStatus osThreadTerminate (osThreadId thread_id); 00369 00370 /// Pass control to next thread that is in state \b READY. 00371 /// \return status code that indicates the execution status of the function. 00372 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS. 00373 osStatus osThreadYield (void); 00374 00375 /// Change priority of an active thread. 00376 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00377 /// \param[in] priority new priority value for the thread function. 00378 /// \return status code that indicates the execution status of the function. 00379 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS. 00380 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority); 00381 00382 /// Get current priority of an active thread. 00383 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00384 /// \return current priority value of the thread function. 00385 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS. 00386 osPriority osThreadGetPriority (osThreadId thread_id); 00387 00388 00389 // ==== Generic Wait Functions ==== 00390 00391 /// Wait for Timeout (Time Delay). 00392 /// \param[in] millisec time delay value 00393 /// \return status code that indicates the execution status of the function. 00394 osStatus osDelay (uint32_t millisec); 00395 00396 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available 00397 00398 /// Wait for Signal, Message, Mail, or Timeout. 00399 /// \param[in] millisec timeout value or 0 in case of no time-out 00400 /// \return event that contains signal, message, or mail information or error code. 00401 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS. 00402 os_InRegs osEvent osWait (uint32_t millisec); 00403 00404 #endif // Generic Wait available 00405 00406 00407 // ==== Timer Management Functions ==== 00408 /// Define a Timer object. 00409 /// \param name name of the timer object. 00410 /// \param function name of the timer call back function. 00411 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the 00412 /// macro body is implementation specific in every CMSIS-RTOS. 00413 #if defined (osObjectsExternal) // object is external 00414 #define osTimerDef(name, function) \ 00415 extern osTimerDef_t os_timer_def_##name 00416 #else // define the object 00417 #define osTimerDef(name, function) \ 00418 uint32_t os_timer_cb_##name[5]; \ 00419 osTimerDef_t os_timer_def_##name = \ 00420 { (function), (os_timer_cb_##name) } 00421 #endif 00422 00423 /// Access a Timer definition. 00424 /// \param name name of the timer object. 00425 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the 00426 /// macro body is implementation specific in every CMSIS-RTOS. 00427 #define osTimer(name) \ 00428 &os_timer_def_##name 00429 00430 /// Create a timer. 00431 /// \param[in] timer_def timer object referenced with \ref osTimer. 00432 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. 00433 /// \param[in] argument argument to the timer call back function. 00434 /// \return timer ID for reference by other functions or NULL in case of error. 00435 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS. 00436 osTimerId osTimerCreate (osTimerDef_t *timer_def, os_timer_type type, void *argument); 00437 00438 /// Start or restart a timer. 00439 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 00440 /// \param[in] millisec time delay value of the timer. 00441 /// \return status code that indicates the execution status of the function. 00442 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS. 00443 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec); 00444 00445 /// Stop the timer. 00446 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 00447 /// \return status code that indicates the execution status of the function. 00448 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS. 00449 osStatus osTimerStop (osTimerId timer_id); 00450 00451 /// Delete a timer that was created by \ref osTimerCreate. 00452 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 00453 /// \return status code that indicates the execution status of the function. 00454 /// \note MUST REMAIN UNCHANGED: \b osTimerDelete shall be consistent in every CMSIS-RTOS. 00455 osStatus osTimerDelete (osTimerId timer_id); 00456 00457 00458 // ==== Signal Management ==== 00459 00460 /// Set the specified Signal Flags of an active thread. 00461 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00462 /// \param[in] signals specifies the signal flags of the thread that should be set. 00463 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 00464 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS. 00465 int32_t osSignalSet (osThreadId thread_id, int32_t signals); 00466 00467 /// Clear the specified Signal Flags of an active thread. 00468 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00469 /// \param[in] signals specifies the signal flags of the thread that shall be cleared. 00470 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 00471 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS. 00472 int32_t osSignalClear (osThreadId thread_id, int32_t signals); 00473 00474 /// Get Signal Flags status of an active thread. 00475 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00476 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 00477 /// \note MUST REMAIN UNCHANGED: \b osSignalGet shall be consistent in every CMSIS-RTOS. 00478 int32_t osSignalGet (osThreadId thread_id); 00479 00480 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread. 00481 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag. 00482 /// \param[in] millisec timeout value or 0 in case of no time-out. 00483 /// \return event flag information or error code. 00484 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS. 00485 os_InRegs osEvent osSignalWait (int32_t signals, uint32_t millisec); 00486 00487 00488 // ==== Mutex Management ==== 00489 00490 /// Define a Mutex. 00491 /// \param name name of the mutex object. 00492 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the 00493 /// macro body is implementation specific in every CMSIS-RTOS. 00494 #if defined (osObjectsExternal) // object is external 00495 #define osMutexDef(name) \ 00496 extern osMutexDef_t os_mutex_def_##name 00497 #else // define the object 00498 #define osMutexDef(name) \ 00499 uint32_t os_mutex_cb_##name[3]; \ 00500 osMutexDef_t os_mutex_def_##name = { (os_mutex_cb_##name) } 00501 #endif 00502 00503 /// Access a Mutex definition. 00504 /// \param name name of the mutex object. 00505 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the 00506 /// macro body is implementation specific in every CMSIS-RTOS. 00507 #define osMutex(name) \ 00508 &os_mutex_def_##name 00509 00510 /// Create and Initialize a Mutex object. 00511 /// \param[in] mutex_def mutex definition referenced with \ref osMutex. 00512 /// \return mutex ID for reference by other functions or NULL in case of error. 00513 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS. 00514 osMutexId osMutexCreate (osMutexDef_t *mutex_def); 00515 00516 /// Wait until a Mutex becomes available. 00517 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 00518 /// \param[in] millisec timeout value or 0 in case of no time-out. 00519 /// \return status code that indicates the execution status of the function. 00520 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS. 00521 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec); 00522 00523 /// Release a Mutex that was obtained by \ref osMutexWait. 00524 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 00525 /// \return status code that indicates the execution status of the function. 00526 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS. 00527 osStatus osMutexRelease (osMutexId mutex_id); 00528 00529 /// Delete a Mutex that was created by \ref osMutexCreate. 00530 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 00531 /// \return status code that indicates the execution status of the function. 00532 /// \note MUST REMAIN UNCHANGED: \b osMutexDelete shall be consistent in every CMSIS-RTOS. 00533 osStatus osMutexDelete (osMutexId mutex_id); 00534 00535 00536 // ==== Semaphore Management Functions ==== 00537 00538 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0)) // Semaphore available 00539 00540 /// Define a Semaphore object. 00541 /// \param name name of the semaphore object. 00542 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the 00543 /// macro body is implementation specific in every CMSIS-RTOS. 00544 #if defined (osObjectsExternal) // object is external 00545 #define osSemaphoreDef(name) \ 00546 extern osSemaphoreDef_t os_semaphore_def_##name 00547 #else // define the object 00548 #define osSemaphoreDef(name) \ 00549 uint32_t os_semaphore_cb_##name[2]; \ 00550 osSemaphoreDef_t os_semaphore_def_##name = { (os_semaphore_cb_##name) } 00551 #endif 00552 00553 /// Access a Semaphore definition. 00554 /// \param name name of the semaphore object. 00555 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the 00556 /// macro body is implementation specific in every CMSIS-RTOS. 00557 #define osSemaphore(name) \ 00558 &os_semaphore_def_##name 00559 00560 /// Create and Initialize a Semaphore object used for managing resources. 00561 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore. 00562 /// \param[in] count number of available resources. 00563 /// \return semaphore ID for reference by other functions or NULL in case of error. 00564 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS. 00565 osSemaphoreId osSemaphoreCreate (osSemaphoreDef_t *semaphore_def, int32_t count); 00566 00567 /// Wait until a Semaphore token becomes available. 00568 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 00569 /// \param[in] millisec timeout value or 0 in case of no time-out. 00570 /// \return number of available tokens, or -1 in case of incorrect parameters. 00571 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS. 00572 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec); 00573 00574 /// Release a Semaphore token. 00575 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 00576 /// \return status code that indicates the execution status of the function. 00577 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS. 00578 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id); 00579 00580 /// Delete a Semaphore that was created by \ref osSemaphoreCreate. 00581 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 00582 /// \return status code that indicates the execution status of the function. 00583 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreDelete shall be consistent in every CMSIS-RTOS. 00584 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id); 00585 00586 #endif // Semaphore available 00587 00588 00589 // ==== Memory Pool Management Functions ==== 00590 00591 #if (defined (osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool Management available 00592 00593 /// \brief Define a Memory Pool. 00594 /// \param name name of the memory pool. 00595 /// \param no maximum number of blocks (objects) in the memory pool. 00596 /// \param type data type of a single block (object). 00597 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the 00598 /// macro body is implementation specific in every CMSIS-RTOS. 00599 #if defined (osObjectsExternal) // object is external 00600 #define osPoolDef(name, no, type) \ 00601 extern osPoolDef_t os_pool_def_##name 00602 #else // define the object 00603 #define osPoolDef(name, no, type) \ 00604 uint32_t os_pool_m_##name[3+((sizeof(type)+3)/4)*(no)]; \ 00605 osPoolDef_t os_pool_def_##name = \ 00606 { (no), sizeof(type), (os_pool_m_##name) } 00607 #endif 00608 00609 /// \brief Access a Memory Pool definition. 00610 /// \param name name of the memory pool 00611 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the 00612 /// macro body is implementation specific in every CMSIS-RTOS. 00613 #define osPool(name) \ 00614 &os_pool_def_##name 00615 00616 /// Create and Initialize a memory pool. 00617 /// \param[in] pool_def memory pool definition referenced with \ref osPool. 00618 /// \return memory pool ID for reference by other functions or NULL in case of error. 00619 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS. 00620 osPoolId osPoolCreate (osPoolDef_t *pool_def); 00621 00622 /// Allocate a memory block from a memory pool. 00623 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 00624 /// \return address of the allocated memory block or NULL in case of no memory available. 00625 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS. 00626 void *osPoolAlloc (osPoolId pool_id); 00627 00628 /// Allocate a memory block from a memory pool and set memory block to zero. 00629 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 00630 /// \return address of the allocated memory block or NULL in case of no memory available. 00631 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS. 00632 void *osPoolCAlloc (osPoolId pool_id); 00633 00634 /// Return an allocated memory block back to a specific memory pool. 00635 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 00636 /// \param[in] block address of the allocated memory block that is returned to the memory pool. 00637 /// \return status code that indicates the execution status of the function. 00638 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS. 00639 osStatus osPoolFree (osPoolId pool_id, void *block); 00640 00641 #endif // Memory Pool Management available 00642 00643 00644 // ==== Message Queue Management Functions ==== 00645 00646 #if (defined (osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queues available 00647 00648 /// \brief Create a Message Queue Definition. 00649 /// \param name name of the queue. 00650 /// \param queue_sz maximum number of messages in the queue. 00651 /// \param type data type of a single message element (for debugger). 00652 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the 00653 /// macro body is implementation specific in every CMSIS-RTOS. 00654 #if defined (osObjectsExternal) // object is external 00655 #define osMessageQDef(name, queue_sz, type) \ 00656 extern osMessageQDef_t os_messageQ_def_##name 00657 #else // define the object 00658 #define osMessageQDef(name, queue_sz, type) \ 00659 uint32_t os_messageQ_q_##name[4+(queue_sz)]; \ 00660 osMessageQDef_t os_messageQ_def_##name = \ 00661 { (queue_sz), (os_messageQ_q_##name) } 00662 #endif 00663 00664 /// \brief Access a Message Queue Definition. 00665 /// \param name name of the queue 00666 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the 00667 /// macro body is implementation specific in every CMSIS-RTOS. 00668 #define osMessageQ(name) \ 00669 &os_messageQ_def_##name 00670 00671 /// Create and Initialize a Message Queue. 00672 /// \param[in] queue_def queue definition referenced with \ref osMessageQ. 00673 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 00674 /// \return message queue ID for reference by other functions or NULL in case of error. 00675 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS. 00676 osMessageQId osMessageCreate (osMessageQDef_t *queue_def, osThreadId thread_id); 00677 00678 /// Put a Message to a Queue. 00679 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 00680 /// \param[in] info message information. 00681 /// \param[in] millisec timeout value or 0 in case of no time-out. 00682 /// \return status code that indicates the execution status of the function. 00683 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS. 00684 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec); 00685 00686 /// Get a Message or Wait for a Message from a Queue. 00687 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 00688 /// \param[in] millisec timeout value or 0 in case of no time-out. 00689 /// \return event information that includes status code. 00690 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS. 00691 os_InRegs osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec); 00692 00693 #endif // Message Queues available 00694 00695 00696 // ==== Mail Queue Management Functions ==== 00697 00698 #if (defined (osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queues available 00699 00700 /// \brief Create a Mail Queue Definition. 00701 /// \param name name of the queue 00702 /// \param queue_sz maximum number of messages in queue 00703 /// \param type data type of a single message element 00704 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the 00705 /// macro body is implementation specific in every CMSIS-RTOS. 00706 #if defined (osObjectsExternal) // object is external 00707 #define osMailQDef(name, queue_sz, type) \ 00708 extern osMailQDef_t os_mailQ_def_##name 00709 #else // define the object 00710 #define osMailQDef(name, queue_sz, type) \ 00711 uint32_t os_mailQ_q_##name[4+(queue_sz)]; \ 00712 uint32_t os_mailQ_m_##name[3+((sizeof(type)+3)/4)*(queue_sz)]; \ 00713 void * os_mailQ_p_##name[2] = { (os_mailQ_q_##name), os_mailQ_m_##name }; \ 00714 osMailQDef_t os_mailQ_def_##name = \ 00715 { (queue_sz), sizeof(type), (os_mailQ_p_##name) } 00716 #endif 00717 00718 /// \brief Access a Mail Queue Definition. 00719 /// \param name name of the queue 00720 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the 00721 /// macro body is implementation specific in every CMSIS-RTOS. 00722 #define osMailQ(name) \ 00723 &os_mailQ_def_##name 00724 00725 /// Create and Initialize mail queue. 00726 /// \param[in] queue_def reference to the mail queue definition obtain with \ref osMailQ 00727 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 00728 /// \return mail queue ID for reference by other functions or NULL in case of error. 00729 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS. 00730 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id); 00731 00732 /// Allocate a memory block from a mail. 00733 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00734 /// \param[in] millisec timeout value or 0 in case of no time-out 00735 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 00736 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS. 00737 void *osMailAlloc (osMailQId queue_id, uint32_t millisec); 00738 00739 /// Allocate a memory block from a mail and set memory block to zero. 00740 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00741 /// \param[in] millisec timeout value or 0 in case of no time-out 00742 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 00743 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS. 00744 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec); 00745 00746 /// Put a mail to a queue. 00747 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00748 /// \param[in] mail memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc. 00749 /// \return status code that indicates the execution status of the function. 00750 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS. 00751 osStatus osMailPut (osMailQId queue_id, void *mail); 00752 00753 /// Get a mail from a queue. 00754 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00755 /// \param[in] millisec timeout value or 0 in case of no time-out 00756 /// \return event that contains mail information or error code. 00757 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS. 00758 os_InRegs osEvent osMailGet (osMailQId queue_id, uint32_t millisec); 00759 00760 /// Free a memory block from a mail. 00761 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00762 /// \param[in] mail pointer to the memory block that was obtained with \ref osMailGet. 00763 /// \return status code that indicates the execution status of the function. 00764 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS. 00765 osStatus osMailFree (osMailQId queue_id, void *mail); 00766 00767 #endif // Mail Queues available 00768 00769 00770 #ifdef __cplusplus 00771 } 00772 #endif 00773 00774 #endif // _CMSIS_OS_H
Generated on Wed Jul 13 2022 09:08:00 by
1.7.2