mbed rtos - modified for the final project of the course "Advanced Operating Systems"
Fork of mbed-rtos by
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) || defined(TOOLCHAIN_ARM_STD) 00119 # define WORDS_STACK_SIZE 512 00120 #elif defined(TOOLCHAIN_ARM_MICRO) 00121 # define WORDS_STACK_SIZE 128 00122 #endif 00123 00124 #define DEFAULT_STACK_SIZE (WORDS_STACK_SIZE*4) 00125 00126 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS. 00127 #define osFeature_MainThread 1 ///< main thread 1=main can be thread, 0=not available 00128 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available 00129 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available 00130 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available 00131 #define osFeature_Signals 16 ///< maximum number of Signal Flags available per thread 00132 #define osFeature_Semaphore 65535 ///< maximum count for \ref osSemaphoreCreate function 00133 #define osFeature_Wait 0 ///< osWait function: 1=available, 0=not available 00134 00135 #if defined (__CC_ARM) 00136 #define os_InRegs __value_in_regs // Compiler specific: force struct in registers 00137 #else 00138 #define os_InRegs 00139 #endif 00140 00141 #include <stdint.h> 00142 #include <stddef.h> 00143 00144 #ifdef __cplusplus 00145 extern "C" 00146 { 00147 #endif 00148 00149 #include "os_tcb.h" 00150 00151 // ==== Enumeration, structures, defines ==== 00152 00153 /// Priority used for thread control. 00154 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS. 00155 typedef enum { 00156 osPriorityIdle = -3, ///< priority: idle (lowest) 00157 osPriorityLow = -2, ///< priority: low 00158 osPriorityBelowNormal = -1, ///< priority: below normal 00159 osPriorityNormal = 0, ///< priority: normal (default) 00160 osPriorityAboveNormal = +1, ///< priority: above normal 00161 osPriorityHigh = +2, ///< priority: high 00162 osPriorityRealtime = +3, ///< priority: realtime (highest) 00163 osPriorityError = 0x84 ///< system cannot determine priority or thread has illegal priority 00164 } osPriority; 00165 00166 /// Timeout value. 00167 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS. 00168 #define osWaitForever 0xFFFFFFFF ///< wait forever timeout value 00169 00170 /// Status code values returned by CMSIS-RTOS functions. 00171 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS. 00172 typedef enum { 00173 osOK = 0, ///< function completed; no error or event occurred. 00174 osEventSignal = 0x08, ///< function completed; signal event occurred. 00175 osEventMessage = 0x10, ///< function completed; message event occurred. 00176 osEventMail = 0x20, ///< function completed; mail event occurred. 00177 osEventTimeout = 0x40, ///< function completed; timeout occurred. 00178 osErrorParameter = 0x80, ///< parameter error: a mandatory parameter was missing or specified an incorrect object. 00179 osErrorResource = 0x81, ///< resource not available: a specified resource was not available. 00180 osErrorTimeoutResource = 0xC1, ///< resource not available within given time: a specified resource was not available within the timeout period. 00181 osErrorISR = 0x82, ///< not allowed in ISR context: the function cannot be called from interrupt service routines. 00182 osErrorISRRecursive = 0x83, ///< function called multiple times from ISR with same object. 00183 osErrorPriority = 0x84, ///< system cannot determine priority or thread has illegal priority. 00184 osErrorNoMemory = 0x85, ///< system is out of memory: it was impossible to allocate or reserve memory for the operation. 00185 osErrorValue = 0x86, ///< value of a parameter is out of range. 00186 osErrorOS = 0xFF, ///< unspecified RTOS error: run-time error but no other error message fits. 00187 os_status_reserved = 0x7FFFFFFF ///< prevent from enum down-size compiler optimization. 00188 } osStatus; 00189 00190 00191 /// Timer type value for the timer definition. 00192 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS. 00193 typedef enum { 00194 osTimerOnce = 0, ///< one-shot timer 00195 osTimerPeriodic = 1 ///< repeating timer 00196 } os_timer_type; 00197 00198 /// Entry point of a thread. 00199 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS. 00200 typedef void (*os_pthread) (void const *argument); 00201 00202 /// Entry point of a timer call back function. 00203 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS. 00204 typedef void (*os_ptimer) (void const *argument); 00205 00206 // >>> the following data type definitions may shall adapted towards a specific RTOS 00207 00208 /// Thread ID identifies the thread (pointer to a thread control block). 00209 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS. 00210 typedef struct os_thread_cb *osThreadId; 00211 00212 /// Timer ID identifies the timer (pointer to a timer control block). 00213 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS. 00214 typedef struct os_timer_cb *osTimerId; 00215 00216 /// Mutex ID identifies the mutex (pointer to a mutex control block). 00217 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS. 00218 typedef struct os_mutex_cb *osMutexId; 00219 00220 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block). 00221 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS. 00222 typedef struct os_semaphore_cb *osSemaphoreId; 00223 00224 /// Pool ID identifies the memory pool (pointer to a memory pool control block). 00225 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS. 00226 typedef struct os_pool_cb *osPoolId; 00227 00228 /// Message ID identifies the message queue (pointer to a message queue control block). 00229 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS. 00230 typedef struct os_messageQ_cb *osMessageQId; 00231 00232 /// Mail ID identifies the mail queue (pointer to a mail queue control block). 00233 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS. 00234 typedef struct os_mailQ_cb *osMailQId; 00235 00236 00237 /// Thread Definition structure contains startup information of a thread. 00238 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS. 00239 typedef struct os_thread_def { 00240 os_pthread pthread; ///< start address of thread function 00241 osPriority tpriority; ///< initial thread priority 00242 uint32_t stacksize; ///< stack size requirements in bytes 00243 unsigned char *stack_pointer; ///< pointer to the stack memory block 00244 struct OS_TCB tcb; 00245 } osThreadDef_t; 00246 00247 /// Timer Definition structure contains timer parameters. 00248 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS. 00249 typedef struct os_timer_def { 00250 os_ptimer ptimer; ///< start address of a timer function 00251 void *timer; ///< pointer to internal data 00252 } osTimerDef_t; 00253 00254 /// Mutex Definition structure contains setup information for a mutex. 00255 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS. 00256 typedef struct os_mutex_def { 00257 void *mutex; ///< pointer to internal data 00258 } osMutexDef_t; 00259 00260 /// Semaphore Definition structure contains setup information for a semaphore. 00261 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS. 00262 typedef struct os_semaphore_def { 00263 void *semaphore; ///< pointer to internal data 00264 } osSemaphoreDef_t; 00265 00266 /// Definition structure for memory block allocation. 00267 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS. 00268 typedef struct os_pool_def { 00269 uint32_t pool_sz; ///< number of items (elements) in the pool 00270 uint32_t item_sz; ///< size of an item 00271 void *pool; ///< pointer to memory for pool 00272 } osPoolDef_t; 00273 00274 /// Definition structure for message queue. 00275 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS. 00276 typedef struct os_messageQ_def { 00277 uint32_t queue_sz; ///< number of elements in the queue 00278 void *pool; ///< memory array for messages 00279 } osMessageQDef_t; 00280 00281 /// Definition structure for mail queue. 00282 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS. 00283 typedef struct os_mailQ_def { 00284 uint32_t queue_sz; ///< number of elements in the queue 00285 uint32_t item_sz; ///< size of an item 00286 void *pool; ///< memory array for mail 00287 } osMailQDef_t; 00288 00289 /// Event structure contains detailed information about an event. 00290 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS. 00291 /// However the struct may be extended at the end. 00292 typedef struct { 00293 osStatus status; ///< status code: event or error information 00294 union { 00295 uint32_t v; ///< message as 32-bit value 00296 void *p; ///< message or mail as void pointer 00297 int32_t signals; ///< signal flags 00298 } value; ///< event value 00299 union { 00300 osMailQId mail_id; ///< mail id obtained by \ref osMailCreate 00301 osMessageQId message_id; ///< message id obtained by \ref osMessageCreate 00302 } def; ///< event definition 00303 } osEvent; 00304 00305 00306 // ==== Kernel Control Functions ==== 00307 00308 /// Initialize the RTOS Kernel for creating objects. 00309 /// \return status code that indicates the execution status of the function. 00310 /// \note MUST REMAIN UNCHANGED: \b osKernelInitialize shall be consistent in every CMSIS-RTOS. 00311 osStatus osKernelInitialize (void); 00312 00313 /// Start the RTOS Kernel. 00314 /// \return status code that indicates the execution status of the function. 00315 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS. 00316 osStatus osKernelStart (void); 00317 00318 /// Check if the RTOS kernel is already started. 00319 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS. 00320 /// \return 0 RTOS is not started, 1 RTOS is started. 00321 int32_t osKernelRunning(void); 00322 00323 00324 // ==== Thread Management ==== 00325 00326 /// Create a Thread Definition with function, priority, and stack requirements. 00327 /// \param name name of the thread function. 00328 /// \param priority initial priority of the thread function. 00329 /// \param stacksz stack size (in bytes) requirements for the thread function. 00330 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the 00331 /// macro body is implementation specific in every CMSIS-RTOS. 00332 #if defined (osObjectsExternal) // object is external 00333 #define osThreadDef(name, priority, stacksz) \ 00334 extern osThreadDef_t os_thread_def_##name 00335 #else // define the object 00336 #define osThreadDef(name, priority, stacksz) \ 00337 unsigned char os_thread_def_stack_##name [stacksz]; \ 00338 osThreadDef_t os_thread_def_##name = \ 00339 { (name), (priority), (stacksz), (os_thread_def_stack_##name)} 00340 #endif 00341 00342 /// Access a Thread definition. 00343 /// \param name name of the thread definition object. 00344 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the 00345 /// macro body is implementation specific in every CMSIS-RTOS. 00346 #define osThread(name) \ 00347 &os_thread_def_##name 00348 00349 /// Create a thread and add it to Active Threads and set it to state READY. 00350 /// \param[in] thread_def thread definition referenced with \ref osThread. 00351 /// \param[in] argument pointer that is passed to the thread function as start argument. 00352 /// \return thread ID for reference by other functions or NULL in case of error. 00353 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS. 00354 osThreadId osThreadCreate (osThreadDef_t *thread_def, void *argument); 00355 00356 /// Return the thread ID of the current running thread. 00357 /// \return thread ID for reference by other functions or NULL in case of error. 00358 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS. 00359 osThreadId osThreadGetId (void); 00360 00361 /// Terminate execution of a thread and remove it from Active Threads. 00362 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00363 /// \return status code that indicates the execution status of the function. 00364 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS. 00365 osStatus osThreadTerminate (osThreadId thread_id); 00366 00367 /// Pass control to next thread that is in state \b READY. 00368 /// \return status code that indicates the execution status of the function. 00369 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS. 00370 osStatus osThreadYield (void); 00371 00372 /// Change priority of an active thread. 00373 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00374 /// \param[in] priority new priority value for the thread function. 00375 /// \return status code that indicates the execution status of the function. 00376 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS. 00377 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority); 00378 00379 /// Get current priority of an active thread. 00380 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00381 /// \return current priority value of the thread function. 00382 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS. 00383 osPriority osThreadGetPriority (osThreadId thread_id); 00384 00385 00386 // ==== Generic Wait Functions ==== 00387 00388 /// Wait for Timeout (Time Delay). 00389 /// \param[in] millisec time delay value 00390 /// \return status code that indicates the execution status of the function. 00391 osStatus osDelay (uint32_t millisec); 00392 00393 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available 00394 00395 /// Wait for Signal, Message, Mail, or Timeout. 00396 /// \param[in] millisec timeout value or 0 in case of no time-out 00397 /// \return event that contains signal, message, or mail information or error code. 00398 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS. 00399 os_InRegs osEvent osWait (uint32_t millisec); 00400 00401 #endif // Generic Wait available 00402 00403 00404 // ==== Timer Management Functions ==== 00405 /// Define a Timer object. 00406 /// \param name name of the timer object. 00407 /// \param function name of the timer call back function. 00408 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the 00409 /// macro body is implementation specific in every CMSIS-RTOS. 00410 #if defined (osObjectsExternal) // object is external 00411 #define osTimerDef(name, function) \ 00412 extern osTimerDef_t os_timer_def_##name 00413 #else // define the object 00414 #define osTimerDef(name, function) \ 00415 uint32_t os_timer_cb_##name[5]; \ 00416 osTimerDef_t os_timer_def_##name = \ 00417 { (function), (os_timer_cb_##name) } 00418 #endif 00419 00420 /// Access a Timer definition. 00421 /// \param name name of the timer object. 00422 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the 00423 /// macro body is implementation specific in every CMSIS-RTOS. 00424 #define osTimer(name) \ 00425 &os_timer_def_##name 00426 00427 /// Create a timer. 00428 /// \param[in] timer_def timer object referenced with \ref osTimer. 00429 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior. 00430 /// \param[in] argument argument to the timer call back function. 00431 /// \return timer ID for reference by other functions or NULL in case of error. 00432 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS. 00433 osTimerId osTimerCreate (osTimerDef_t *timer_def, os_timer_type type, void *argument); 00434 00435 /// Start or restart a timer. 00436 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 00437 /// \param[in] millisec time delay value of the timer. 00438 /// \return status code that indicates the execution status of the function. 00439 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS. 00440 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec); 00441 00442 /// Stop the timer. 00443 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 00444 /// \return status code that indicates the execution status of the function. 00445 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS. 00446 osStatus osTimerStop (osTimerId timer_id); 00447 00448 /// Delete a timer that was created by \ref osTimerCreate. 00449 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate. 00450 /// \return status code that indicates the execution status of the function. 00451 /// \note MUST REMAIN UNCHANGED: \b osTimerDelete shall be consistent in every CMSIS-RTOS. 00452 osStatus osTimerDelete (osTimerId timer_id); 00453 00454 00455 // ==== Signal Management ==== 00456 00457 /// Set the specified Signal Flags of an active thread. 00458 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00459 /// \param[in] signals specifies the signal flags of the thread that should be set. 00460 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 00461 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS. 00462 int32_t osSignalSet (osThreadId thread_id, int32_t signals); 00463 00464 /// Clear the specified Signal Flags of an active thread. 00465 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00466 /// \param[in] signals specifies the signal flags of the thread that shall be cleared. 00467 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 00468 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS. 00469 int32_t osSignalClear (osThreadId thread_id, int32_t signals); 00470 00471 /// Get Signal Flags status of an active thread. 00472 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId. 00473 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters. 00474 /// \note MUST REMAIN UNCHANGED: \b osSignalGet shall be consistent in every CMSIS-RTOS. 00475 int32_t osSignalGet (osThreadId thread_id); 00476 00477 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread. 00478 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag. 00479 /// \param[in] millisec timeout value or 0 in case of no time-out. 00480 /// \return event flag information or error code. 00481 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS. 00482 os_InRegs osEvent osSignalWait (int32_t signals, uint32_t millisec); 00483 00484 00485 // ==== Mutex Management ==== 00486 00487 /// Define a Mutex. 00488 /// \param name name of the mutex object. 00489 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the 00490 /// macro body is implementation specific in every CMSIS-RTOS. 00491 #if defined (osObjectsExternal) // object is external 00492 #define osMutexDef(name) \ 00493 extern osMutexDef_t os_mutex_def_##name 00494 #else // define the object 00495 #define osMutexDef(name) \ 00496 uint32_t os_mutex_cb_##name[3]; \ 00497 osMutexDef_t os_mutex_def_##name = { (os_mutex_cb_##name) } 00498 #endif 00499 00500 /// Access a Mutex definition. 00501 /// \param name name of the mutex object. 00502 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the 00503 /// macro body is implementation specific in every CMSIS-RTOS. 00504 #define osMutex(name) \ 00505 &os_mutex_def_##name 00506 00507 /// Create and Initialize a Mutex object. 00508 /// \param[in] mutex_def mutex definition referenced with \ref osMutex. 00509 /// \return mutex ID for reference by other functions or NULL in case of error. 00510 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS. 00511 osMutexId osMutexCreate (osMutexDef_t *mutex_def); 00512 00513 /// Wait until a Mutex becomes available. 00514 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 00515 /// \param[in] millisec timeout value or 0 in case of no time-out. 00516 /// \return status code that indicates the execution status of the function. 00517 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS. 00518 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec); 00519 00520 /// Release a Mutex that was obtained by \ref osMutexWait. 00521 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 00522 /// \return status code that indicates the execution status of the function. 00523 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS. 00524 osStatus osMutexRelease (osMutexId mutex_id); 00525 00526 /// Delete a Mutex that was created by \ref osMutexCreate. 00527 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate. 00528 /// \return status code that indicates the execution status of the function. 00529 /// \note MUST REMAIN UNCHANGED: \b osMutexDelete shall be consistent in every CMSIS-RTOS. 00530 osStatus osMutexDelete (osMutexId mutex_id); 00531 00532 00533 // ==== Semaphore Management Functions ==== 00534 00535 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0)) // Semaphore available 00536 00537 /// Define a Semaphore object. 00538 /// \param name name of the semaphore object. 00539 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the 00540 /// macro body is implementation specific in every CMSIS-RTOS. 00541 #if defined (osObjectsExternal) // object is external 00542 #define osSemaphoreDef(name) \ 00543 extern osSemaphoreDef_t os_semaphore_def_##name 00544 #else // define the object 00545 #define osSemaphoreDef(name) \ 00546 uint32_t os_semaphore_cb_##name[2]; \ 00547 osSemaphoreDef_t os_semaphore_def_##name = { (os_semaphore_cb_##name) } 00548 #endif 00549 00550 /// Access a Semaphore definition. 00551 /// \param name name of the semaphore object. 00552 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the 00553 /// macro body is implementation specific in every CMSIS-RTOS. 00554 #define osSemaphore(name) \ 00555 &os_semaphore_def_##name 00556 00557 /// Create and Initialize a Semaphore object used for managing resources. 00558 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore. 00559 /// \param[in] count number of available resources. 00560 /// \return semaphore ID for reference by other functions or NULL in case of error. 00561 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS. 00562 osSemaphoreId osSemaphoreCreate (osSemaphoreDef_t *semaphore_def, int32_t count); 00563 00564 /// Wait until a Semaphore token becomes available. 00565 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 00566 /// \param[in] millisec timeout value or 0 in case of no time-out. 00567 /// \return number of available tokens, or -1 in case of incorrect parameters. 00568 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS. 00569 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec); 00570 00571 /// Release a Semaphore token. 00572 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 00573 /// \return status code that indicates the execution status of the function. 00574 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS. 00575 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id); 00576 00577 /// Delete a Semaphore that was created by \ref osSemaphoreCreate. 00578 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate. 00579 /// \return status code that indicates the execution status of the function. 00580 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreDelete shall be consistent in every CMSIS-RTOS. 00581 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id); 00582 00583 #endif // Semaphore available 00584 00585 00586 // ==== Memory Pool Management Functions ==== 00587 00588 #if (defined (osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool Management available 00589 00590 /// \brief Define a Memory Pool. 00591 /// \param name name of the memory pool. 00592 /// \param no maximum number of blocks (objects) in the memory pool. 00593 /// \param type data type of a single block (object). 00594 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the 00595 /// macro body is implementation specific in every CMSIS-RTOS. 00596 #if defined (osObjectsExternal) // object is external 00597 #define osPoolDef(name, no, type) \ 00598 extern osPoolDef_t os_pool_def_##name 00599 #else // define the object 00600 #define osPoolDef(name, no, type) \ 00601 uint32_t os_pool_m_##name[3+((sizeof(type)+3)/4)*(no)]; \ 00602 osPoolDef_t os_pool_def_##name = \ 00603 { (no), sizeof(type), (os_pool_m_##name) } 00604 #endif 00605 00606 /// \brief Access a Memory Pool definition. 00607 /// \param name name of the memory pool 00608 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the 00609 /// macro body is implementation specific in every CMSIS-RTOS. 00610 #define osPool(name) \ 00611 &os_pool_def_##name 00612 00613 /// Create and Initialize a memory pool. 00614 /// \param[in] pool_def memory pool definition referenced with \ref osPool. 00615 /// \return memory pool ID for reference by other functions or NULL in case of error. 00616 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS. 00617 osPoolId osPoolCreate (osPoolDef_t *pool_def); 00618 00619 /// Allocate a memory block from a memory pool. 00620 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 00621 /// \return address of the allocated memory block or NULL in case of no memory available. 00622 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS. 00623 void *osPoolAlloc (osPoolId pool_id); 00624 00625 /// Allocate a memory block from a memory pool and set memory block to zero. 00626 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 00627 /// \return address of the allocated memory block or NULL in case of no memory available. 00628 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS. 00629 void *osPoolCAlloc (osPoolId pool_id); 00630 00631 /// Return an allocated memory block back to a specific memory pool. 00632 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate. 00633 /// \param[in] block address of the allocated memory block that is returned to the memory pool. 00634 /// \return status code that indicates the execution status of the function. 00635 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS. 00636 osStatus osPoolFree (osPoolId pool_id, void *block); 00637 00638 #endif // Memory Pool Management available 00639 00640 00641 // ==== Message Queue Management Functions ==== 00642 00643 #if (defined (osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queues available 00644 00645 /// \brief Create a Message Queue Definition. 00646 /// \param name name of the queue. 00647 /// \param queue_sz maximum number of messages in the queue. 00648 /// \param type data type of a single message element (for debugger). 00649 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the 00650 /// macro body is implementation specific in every CMSIS-RTOS. 00651 #if defined (osObjectsExternal) // object is external 00652 #define osMessageQDef(name, queue_sz, type) \ 00653 extern osMessageQDef_t os_messageQ_def_##name 00654 #else // define the object 00655 #define osMessageQDef(name, queue_sz, type) \ 00656 uint32_t os_messageQ_q_##name[4+(queue_sz)]; \ 00657 osMessageQDef_t os_messageQ_def_##name = \ 00658 { (queue_sz), (os_messageQ_q_##name) } 00659 #endif 00660 00661 /// \brief Access a Message Queue Definition. 00662 /// \param name name of the queue 00663 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the 00664 /// macro body is implementation specific in every CMSIS-RTOS. 00665 #define osMessageQ(name) \ 00666 &os_messageQ_def_##name 00667 00668 /// Create and Initialize a Message Queue. 00669 /// \param[in] queue_def queue definition referenced with \ref osMessageQ. 00670 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 00671 /// \return message queue ID for reference by other functions or NULL in case of error. 00672 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS. 00673 osMessageQId osMessageCreate (osMessageQDef_t *queue_def, osThreadId thread_id); 00674 00675 /// Put a Message to a Queue. 00676 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 00677 /// \param[in] info message information. 00678 /// \param[in] millisec timeout value or 0 in case of no time-out. 00679 /// \return status code that indicates the execution status of the function. 00680 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS. 00681 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec); 00682 00683 /// Get a Message or Wait for a Message from a Queue. 00684 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate. 00685 /// \param[in] millisec timeout value or 0 in case of no time-out. 00686 /// \return event information that includes status code. 00687 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS. 00688 os_InRegs osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec); 00689 00690 #endif // Message Queues available 00691 00692 00693 // ==== Mail Queue Management Functions ==== 00694 00695 #if (defined (osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queues available 00696 00697 /// \brief Create a Mail Queue Definition. 00698 /// \param name name of the queue 00699 /// \param queue_sz maximum number of messages in queue 00700 /// \param type data type of a single message element 00701 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the 00702 /// macro body is implementation specific in every CMSIS-RTOS. 00703 #if defined (osObjectsExternal) // object is external 00704 #define osMailQDef(name, queue_sz, type) \ 00705 extern osMailQDef_t os_mailQ_def_##name 00706 #else // define the object 00707 #define osMailQDef(name, queue_sz, type) \ 00708 uint32_t os_mailQ_q_##name[4+(queue_sz)]; \ 00709 uint32_t os_mailQ_m_##name[3+((sizeof(type)+3)/4)*(queue_sz)]; \ 00710 void * os_mailQ_p_##name[2] = { (os_mailQ_q_##name), os_mailQ_m_##name }; \ 00711 osMailQDef_t os_mailQ_def_##name = \ 00712 { (queue_sz), sizeof(type), (os_mailQ_p_##name) } 00713 #endif 00714 00715 /// \brief Access a Mail Queue Definition. 00716 /// \param name name of the queue 00717 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the 00718 /// macro body is implementation specific in every CMSIS-RTOS. 00719 #define osMailQ(name) \ 00720 &os_mailQ_def_##name 00721 00722 /// Create and Initialize mail queue. 00723 /// \param[in] queue_def reference to the mail queue definition obtain with \ref osMailQ 00724 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL. 00725 /// \return mail queue ID for reference by other functions or NULL in case of error. 00726 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS. 00727 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id); 00728 00729 /// Allocate a memory block from a mail. 00730 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00731 /// \param[in] millisec timeout value or 0 in case of no time-out 00732 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 00733 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS. 00734 void *osMailAlloc (osMailQId queue_id, uint32_t millisec); 00735 00736 /// Allocate a memory block from a mail and set memory block to zero. 00737 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00738 /// \param[in] millisec timeout value or 0 in case of no time-out 00739 /// \return pointer to memory block that can be filled with mail or NULL in case of error. 00740 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS. 00741 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec); 00742 00743 /// Put a mail to a queue. 00744 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00745 /// \param[in] mail memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc. 00746 /// \return status code that indicates the execution status of the function. 00747 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS. 00748 osStatus osMailPut (osMailQId queue_id, void *mail); 00749 00750 /// Get a mail from a queue. 00751 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00752 /// \param[in] millisec timeout value or 0 in case of no time-out 00753 /// \return event that contains mail information or error code. 00754 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS. 00755 os_InRegs osEvent osMailGet (osMailQId queue_id, uint32_t millisec); 00756 00757 /// Free a memory block from a mail. 00758 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate. 00759 /// \param[in] mail pointer to the memory block that was obtained with \ref osMailGet. 00760 /// \return status code that indicates the execution status of the function. 00761 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS. 00762 osStatus osMailFree (osMailQId queue_id, void *mail); 00763 00764 #endif // Mail Queues available 00765 00766 00767 #ifdef __cplusplus 00768 } 00769 #endif 00770 00771 #endif // _CMSIS_OS_H
Generated on Tue Jul 12 2022 21:49:11 by 1.7.2