cmsis_os2.h

00001 /*
00002  * Copyright (c) 2013-2018 Arm Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: Apache-2.0
00005  *
00006  * Licensed under the Apache License, Version 2.0 (the License); you may
00007  * not use this file except in compliance with the License.
00008  * You may obtain a copy of the License at
00009  *
00010  * www.apache.org/licenses/LICENSE-2.0
00011  *
00012  * Unless required by applicable law or agreed to in writing, software
00013  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00014  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015  * See the License for the specific language governing permissions and
00016  * limitations under the License.
00017  *
00018  * ----------------------------------------------------------------------
00019  *
00020  * $Date:        18. June 2018
00021  * $Revision:    V2.1.3
00022  *
00023  * Project:      CMSIS-RTOS2 API
00024  * Title:        cmsis_os2.h header file
00025  *
00026  * Version 2.1.3
00027  *    Additional functions allowed to be called from Interrupt Service Routines:
00028  *    - osThreadGetId
00029  * Version 2.1.2
00030  *    Additional functions allowed to be called from Interrupt Service Routines:
00031  *    - osKernelGetInfo, osKernelGetState
00032  * Version 2.1.1
00033  *    Additional functions allowed to be called from Interrupt Service Routines:
00034  *    - osKernelGetTickCount, osKernelGetTickFreq
00035  *    Changed Kernel Tick type to uint32_t:
00036  *    - updated: osKernelGetTickCount, osDelayUntil
00037  * Version 2.1.0
00038  *    Support for critical and uncritical sections (nesting safe):
00039  *    - updated: osKernelLock, osKernelUnlock
00040  *    - added: osKernelRestoreLock
00041  *    Updated Thread and Event Flags:
00042  *    - changed flags parameter and return type from int32_t to uint32_t
00043  * Version 2.0.0
00044  *    Initial Release
00045  *---------------------------------------------------------------------------*/
00046  
00047 #ifndef CMSIS_OS2_H_
00048 #define CMSIS_OS2_H_
00049  
00050 #ifndef __NO_RETURN
00051 #if   defined(__CC_ARM)
00052 #define __NO_RETURN __declspec(noreturn)
00053 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
00054 #define __NO_RETURN __attribute__((__noreturn__))
00055 #elif defined(__GNUC__)
00056 #define __NO_RETURN __attribute__((__noreturn__))
00057 #elif defined(__ICCARM__)
00058 #define __NO_RETURN __noreturn
00059 #else
00060 #define __NO_RETURN
00061 #endif
00062 #endif
00063  
00064 #include <stdint.h>
00065 #include <stddef.h>
00066  
00067 #ifdef  __cplusplus
00068 extern "C"
00069 {
00070 #endif
00071  
00072  
00073 //  ==== Enumerations, structures, defines ====
00074  
00075 /// Version information.
00076 typedef struct {
00077   uint32_t                       api;   ///< API version (major.minor.rev: mmnnnrrrr dec).
00078   uint32_t                    kernel;   ///< Kernel version (major.minor.rev: mmnnnrrrr dec).
00079 } osVersion_t;
00080  
00081 /// Kernel state.
00082 typedef enum {
00083   osKernelInactive        =  0,         ///< Inactive.
00084   osKernelReady           =  1,         ///< Ready.
00085   osKernelRunning         =  2,         ///< Running.
00086   osKernelLocked          =  3,         ///< Locked.
00087   osKernelSuspended       =  4,         ///< Suspended.
00088   osKernelError           = -1,         ///< Error.
00089   osKernelReserved        = 0x7FFFFFFFU ///< Prevents enum down-size compiler optimization.
00090 } osKernelState_t;
00091  
00092 /// Thread state.
00093 typedef enum {
00094   osThreadInactive        =  0,         ///< Inactive.
00095   osThreadReady           =  1,         ///< Ready.
00096   osThreadRunning         =  2,         ///< Running.
00097   osThreadBlocked         =  3,         ///< Blocked.
00098   osThreadTerminated      =  4,         ///< Terminated.
00099   osThreadError           = -1,         ///< Error.
00100   osThreadReserved        = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
00101 } osThreadState_t;
00102  
00103 /// Priority values.
00104 typedef enum {
00105   osPriorityNone          =  0,         ///< No priority (not initialized).
00106   osPriorityIdle          =  1,         ///< Reserved for Idle thread.
00107   osPriorityLow           =  8,         ///< Priority: low
00108   osPriorityLow1          =  8+1,       ///< Priority: low + 1
00109   osPriorityLow2          =  8+2,       ///< Priority: low + 2
00110   osPriorityLow3          =  8+3,       ///< Priority: low + 3
00111   osPriorityLow4          =  8+4,       ///< Priority: low + 4
00112   osPriorityLow5          =  8+5,       ///< Priority: low + 5
00113   osPriorityLow6          =  8+6,       ///< Priority: low + 6
00114   osPriorityLow7          =  8+7,       ///< Priority: low + 7
00115   osPriorityBelowNormal   = 16,         ///< Priority: below normal
00116   osPriorityBelowNormal1  = 16+1,       ///< Priority: below normal + 1
00117   osPriorityBelowNormal2  = 16+2,       ///< Priority: below normal + 2
00118   osPriorityBelowNormal3  = 16+3,       ///< Priority: below normal + 3
00119   osPriorityBelowNormal4  = 16+4,       ///< Priority: below normal + 4
00120   osPriorityBelowNormal5  = 16+5,       ///< Priority: below normal + 5
00121   osPriorityBelowNormal6  = 16+6,       ///< Priority: below normal + 6
00122   osPriorityBelowNormal7  = 16+7,       ///< Priority: below normal + 7
00123   osPriorityNormal        = 24,         ///< Priority: normal
00124   osPriorityNormal1       = 24+1,       ///< Priority: normal + 1
00125   osPriorityNormal2       = 24+2,       ///< Priority: normal + 2
00126   osPriorityNormal3       = 24+3,       ///< Priority: normal + 3
00127   osPriorityNormal4       = 24+4,       ///< Priority: normal + 4
00128   osPriorityNormal5       = 24+5,       ///< Priority: normal + 5
00129   osPriorityNormal6       = 24+6,       ///< Priority: normal + 6
00130   osPriorityNormal7       = 24+7,       ///< Priority: normal + 7
00131   osPriorityAboveNormal   = 32,         ///< Priority: above normal
00132   osPriorityAboveNormal1  = 32+1,       ///< Priority: above normal + 1
00133   osPriorityAboveNormal2  = 32+2,       ///< Priority: above normal + 2
00134   osPriorityAboveNormal3  = 32+3,       ///< Priority: above normal + 3
00135   osPriorityAboveNormal4  = 32+4,       ///< Priority: above normal + 4
00136   osPriorityAboveNormal5  = 32+5,       ///< Priority: above normal + 5
00137   osPriorityAboveNormal6  = 32+6,       ///< Priority: above normal + 6
00138   osPriorityAboveNormal7  = 32+7,       ///< Priority: above normal + 7
00139   osPriorityHigh          = 40,         ///< Priority: high
00140   osPriorityHigh1         = 40+1,       ///< Priority: high + 1
00141   osPriorityHigh2         = 40+2,       ///< Priority: high + 2
00142   osPriorityHigh3         = 40+3,       ///< Priority: high + 3
00143   osPriorityHigh4         = 40+4,       ///< Priority: high + 4
00144   osPriorityHigh5         = 40+5,       ///< Priority: high + 5
00145   osPriorityHigh6         = 40+6,       ///< Priority: high + 6
00146   osPriorityHigh7         = 40+7,       ///< Priority: high + 7
00147   osPriorityRealtime      = 48,         ///< Priority: realtime
00148   osPriorityRealtime1     = 48+1,       ///< Priority: realtime + 1
00149   osPriorityRealtime2     = 48+2,       ///< Priority: realtime + 2
00150   osPriorityRealtime3     = 48+3,       ///< Priority: realtime + 3
00151   osPriorityRealtime4     = 48+4,       ///< Priority: realtime + 4
00152   osPriorityRealtime5     = 48+5,       ///< Priority: realtime + 5
00153   osPriorityRealtime6     = 48+6,       ///< Priority: realtime + 6
00154   osPriorityRealtime7     = 48+7,       ///< Priority: realtime + 7
00155   osPriorityISR           = 56,         ///< Reserved for ISR deferred thread.
00156   osPriorityError         = -1,         ///< System cannot determine priority or illegal priority.
00157   osPriorityReserved      = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
00158 } osPriority_t;
00159  
00160 /// Entry point of a thread.
00161 typedef void (*osThreadFunc_t) (void *argument);
00162  
00163 /// Timer callback function.
00164 typedef void (*osTimerFunc_t) (void *argument);
00165  
00166 /// Timer type.
00167 typedef enum {
00168   osTimerOnce               = 0,          ///< One-shot timer.
00169   osTimerPeriodic           = 1           ///< Repeating timer.
00170 } osTimerType_t;
00171  
00172 // Timeout value.
00173 #define osWaitForever         0xFFFFFFFFU ///< Wait forever timeout value.
00174  
00175 // Flags options (\ref osThreadFlagsWait and \ref osEventFlagsWait).
00176 #define osFlagsWaitAny        0x00000000U ///< Wait for any flag (default).
00177 #define osFlagsWaitAll        0x00000001U ///< Wait for all flags.
00178 #define osFlagsNoClear        0x00000002U ///< Do not clear flags which have been specified to wait for.
00179  
00180 // Flags errors (returned by osThreadFlagsXxxx and osEventFlagsXxxx).
00181 #define osFlagsError          0x80000000U ///< Error indicator.
00182 #define osFlagsErrorUnknown   0xFFFFFFFFU ///< osError (-1).
00183 #define osFlagsErrorTimeout   0xFFFFFFFEU ///< osErrorTimeout (-2).
00184 #define osFlagsErrorResource  0xFFFFFFFDU ///< osErrorResource (-3).
00185 #define osFlagsErrorParameter 0xFFFFFFFCU ///< osErrorParameter (-4).
00186 #define osFlagsErrorISR       0xFFFFFFFAU ///< osErrorISR (-6).
00187  
00188 // Thread attributes (attr_bits in \ref osThreadAttr_t).
00189 #define osThreadDetached      0x00000000U ///< Thread created in detached mode (default)
00190 #define osThreadJoinable      0x00000001U ///< Thread created in joinable mode
00191  
00192 // Mutex attributes (attr_bits in \ref osMutexAttr_t).
00193 #define osMutexRecursive      0x00000001U ///< Recursive mutex.
00194 #define osMutexPrioInherit    0x00000002U ///< Priority inherit protocol.
00195 #define osMutexRobust         0x00000008U ///< Robust mutex.
00196  
00197 /// Status code values returned by CMSIS-RTOS functions.
00198 typedef enum {
00199   osOK                      =  0,         ///< Operation completed successfully.
00200   osError                   = -1,         ///< Unspecified RTOS error: run-time error but no other error message fits.
00201   osErrorTimeout            = -2,         ///< Operation not completed within the timeout period.
00202   osErrorResource           = -3,         ///< Resource not available.
00203   osErrorParameter          = -4,         ///< Parameter error.
00204   osErrorNoMemory           = -5,         ///< System is out of memory: it was impossible to allocate or reserve memory for the operation.
00205   osErrorISR                = -6,         ///< Not allowed in ISR context: the function cannot be called from interrupt service routines.
00206   osStatusReserved          = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
00207 } osStatus_t;
00208  
00209  
00210 /// \details Thread ID identifies the thread.
00211 typedef void *osThreadId_t;
00212  
00213 /// \details Timer ID identifies the timer.
00214 typedef void *osTimerId_t;
00215  
00216 /// \details Event Flags ID identifies the event flags.
00217 typedef void *osEventFlagsId_t;
00218  
00219 /// \details Mutex ID identifies the mutex.
00220 typedef void *osMutexId_t;
00221  
00222 /// \details Semaphore ID identifies the semaphore.
00223 typedef void *osSemaphoreId_t;
00224  
00225 /// \details Memory Pool ID identifies the memory pool.
00226 typedef void *osMemoryPoolId_t;
00227  
00228 /// \details Message Queue ID identifies the message queue.
00229 typedef void *osMessageQueueId_t;
00230  
00231  
00232 #ifndef TZ_MODULEID_T
00233 #define TZ_MODULEID_T
00234 /// \details Data type that identifies secure software modules called by a process.
00235 typedef uint32_t TZ_ModuleId_t;
00236 #endif
00237  
00238  
00239 /// Attributes structure for thread.
00240 typedef struct {
00241   const char                   *name;   ///< name of the thread
00242   uint32_t                 attr_bits;   ///< attribute bits
00243   void                      *cb_mem;    ///< memory for control block
00244   uint32_t                   cb_size;   ///< size of provided memory for control block
00245   void                   *stack_mem;    ///< memory for stack
00246   uint32_t                stack_size;   ///< size of stack
00247   osPriority_t              priority;   ///< initial thread priority (default: osPriorityNormal)
00248   TZ_ModuleId_t            tz_module;   ///< TrustZone module identifier
00249   uint32_t                  reserved;   ///< reserved (must be 0)
00250 } osThreadAttr_t;
00251  
00252 /// Attributes structure for timer.
00253 typedef struct {
00254   const char                   *name;   ///< name of the timer
00255   uint32_t                 attr_bits;   ///< attribute bits
00256   void                      *cb_mem;    ///< memory for control block
00257   uint32_t                   cb_size;   ///< size of provided memory for control block
00258 } osTimerAttr_t;
00259  
00260 /// Attributes structure for event flags.
00261 typedef struct {
00262   const char                   *name;   ///< name of the event flags
00263   uint32_t                 attr_bits;   ///< attribute bits
00264   void                      *cb_mem;    ///< memory for control block
00265   uint32_t                   cb_size;   ///< size of provided memory for control block
00266 } osEventFlagsAttr_t;
00267  
00268 /// Attributes structure for mutex.
00269 typedef struct {
00270   const char                   *name;   ///< name of the mutex
00271   uint32_t                 attr_bits;   ///< attribute bits
00272   void                      *cb_mem;    ///< memory for control block
00273   uint32_t                   cb_size;   ///< size of provided memory for control block
00274 } osMutexAttr_t;
00275  
00276 /// Attributes structure for semaphore.
00277 typedef struct {
00278   const char                   *name;   ///< name of the semaphore
00279   uint32_t                 attr_bits;   ///< attribute bits
00280   void                      *cb_mem;    ///< memory for control block
00281   uint32_t                   cb_size;   ///< size of provided memory for control block
00282 } osSemaphoreAttr_t;
00283  
00284 /// Attributes structure for memory pool.
00285 typedef struct {
00286   const char                   *name;   ///< name of the memory pool
00287   uint32_t                 attr_bits;   ///< attribute bits
00288   void                      *cb_mem;    ///< memory for control block
00289   uint32_t                   cb_size;   ///< size of provided memory for control block
00290   void                      *mp_mem;    ///< memory for data storage
00291   uint32_t                   mp_size;   ///< size of provided memory for data storage 
00292 } osMemoryPoolAttr_t;
00293  
00294 /// Attributes structure for message queue.
00295 typedef struct {
00296   const char                   *name;   ///< name of the message queue
00297   uint32_t                 attr_bits;   ///< attribute bits
00298   void                      *cb_mem;    ///< memory for control block
00299   uint32_t                   cb_size;   ///< size of provided memory for control block
00300   void                      *mq_mem;    ///< memory for data storage
00301   uint32_t                   mq_size;   ///< size of provided memory for data storage 
00302 } osMessageQueueAttr_t;
00303  
00304  
00305 //  ==== Kernel Management Functions ====
00306  
00307 /// Initialize the RTOS Kernel.
00308 /// \return status code that indicates the execution status of the function.
00309 osStatus_t osKernelInitialize (void);
00310  
00311 ///  Get RTOS Kernel Information.
00312 /// \param[out]    version       pointer to buffer for retrieving version information.
00313 /// \param[out]    id_buf        pointer to buffer for retrieving kernel identification string.
00314 /// \param[in]     id_size       size of buffer for kernel identification string.
00315 /// \return status code that indicates the execution status of the function.
00316 osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size);
00317  
00318 /// Get the current RTOS Kernel state.
00319 /// \return current RTOS Kernel state.
00320 osKernelState_t osKernelGetState (void);
00321  
00322 /// Start the RTOS Kernel scheduler.
00323 /// \return status code that indicates the execution status of the function.
00324 osStatus_t osKernelStart (void);
00325  
00326 /// Lock the RTOS Kernel scheduler.
00327 /// \return previous lock state (1 - locked, 0 - not locked, error code if negative).
00328 int32_t osKernelLock (void);
00329  
00330 /// Unlock the RTOS Kernel scheduler.
00331 /// \return previous lock state (1 - locked, 0 - not locked, error code if negative).
00332 int32_t osKernelUnlock (void);
00333  
00334 /// Restore the RTOS Kernel scheduler lock state.
00335 /// \param[in]     lock          lock state obtained by \ref osKernelLock or \ref osKernelUnlock.
00336 /// \return new lock state (1 - locked, 0 - not locked, error code if negative).
00337 int32_t osKernelRestoreLock (int32_t lock);
00338  
00339 /// Suspend the RTOS Kernel scheduler.
00340 /// \return time in ticks, for how long the system can sleep or power-down.
00341 uint32_t osKernelSuspend (void);
00342  
00343 /// Resume the RTOS Kernel scheduler.
00344 /// \param[in]     sleep_ticks   time in ticks for how long the system was in sleep or power-down mode.
00345 void osKernelResume (uint32_t sleep_ticks);
00346  
00347 /// Get the RTOS kernel tick count.
00348 /// \return RTOS kernel current tick count.
00349 uint32_t osKernelGetTickCount (void);
00350  
00351 /// Get the RTOS kernel tick frequency.
00352 /// \return frequency of the kernel tick in hertz, i.e. kernel ticks per second.
00353 uint32_t osKernelGetTickFreq (void);
00354  
00355 /// Get the RTOS kernel system timer count.
00356 /// \return RTOS kernel current system timer count as 32-bit value.
00357 uint32_t osKernelGetSysTimerCount (void);
00358  
00359 /// Get the RTOS kernel system timer frequency.
00360 /// \return frequency of the system timer in hertz, i.e. timer ticks per second.
00361 uint32_t osKernelGetSysTimerFreq (void);
00362  
00363  
00364 //  ==== Thread Management Functions ====
00365  
00366 /// Create a thread and add it to Active Threads.
00367 /// \param[in]     func          thread function.
00368 /// \param[in]     argument      pointer that is passed to the thread function as start argument.
00369 /// \param[in]     attr          thread attributes; NULL: default values.
00370 /// \return thread ID for reference by other functions or NULL in case of error.
00371 osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);
00372  
00373 /// Get name of a thread.
00374 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00375 /// \return name as null-terminated string.
00376 const char *osThreadGetName (osThreadId_t thread_id);
00377  
00378 /// Return the thread ID of the current running thread.
00379 /// \return thread ID for reference by other functions or NULL in case of error.
00380 osThreadId_t osThreadGetId (void);
00381  
00382 /// Get current thread state of a thread.
00383 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00384 /// \return current thread state of the specified thread.
00385 osThreadState_t osThreadGetState (osThreadId_t thread_id);
00386  
00387 /// Get stack size of a thread.
00388 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00389 /// \return stack size in bytes.
00390 uint32_t osThreadGetStackSize (osThreadId_t thread_id);
00391  
00392 /// Get available stack space of a thread based on stack watermark recording during execution.
00393 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00394 /// \return remaining stack space in bytes.
00395 uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
00396  
00397 /// Change priority of a thread.
00398 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00399 /// \param[in]     priority      new priority value for the thread function.
00400 /// \return status code that indicates the execution status of the function.
00401 osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority);
00402  
00403 /// Get current priority of a thread.
00404 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00405 /// \return current priority value of the specified thread.
00406 osPriority_t osThreadGetPriority (osThreadId_t thread_id);
00407  
00408 /// Pass control to next thread that is in state \b READY.
00409 /// \return status code that indicates the execution status of the function.
00410 osStatus_t osThreadYield (void);
00411  
00412 /// Suspend execution of a thread.
00413 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00414 /// \return status code that indicates the execution status of the function.
00415 osStatus_t osThreadSuspend (osThreadId_t thread_id);
00416  
00417 /// Resume execution of a thread.
00418 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00419 /// \return status code that indicates the execution status of the function.
00420 osStatus_t osThreadResume (osThreadId_t thread_id);
00421  
00422 /// Detach a thread (thread storage can be reclaimed when thread terminates).
00423 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00424 /// \return status code that indicates the execution status of the function.
00425 osStatus_t osThreadDetach (osThreadId_t thread_id);
00426  
00427 /// Wait for specified thread to terminate.
00428 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00429 /// \return status code that indicates the execution status of the function.
00430 osStatus_t osThreadJoin (osThreadId_t thread_id);
00431  
00432 /// Terminate execution of current running thread.
00433 __NO_RETURN void osThreadExit (void);
00434  
00435 /// Terminate execution of a thread.
00436 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00437 /// \return status code that indicates the execution status of the function.
00438 osStatus_t osThreadTerminate (osThreadId_t thread_id);
00439  
00440 /// Get number of active threads.
00441 /// \return number of active threads.
00442 uint32_t osThreadGetCount (void);
00443  
00444 /// Enumerate active threads.
00445 /// \param[out]    thread_array  pointer to array for retrieving thread IDs.
00446 /// \param[in]     array_items   maximum number of items in array for retrieving thread IDs.
00447 /// \return number of enumerated threads.
00448 uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items);
00449  
00450  
00451 //  ==== Thread Flags Functions ====
00452  
00453 /// Set the specified Thread Flags of a thread.
00454 /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
00455 /// \param[in]     flags         specifies the flags of the thread that shall be set.
00456 /// \return thread flags after setting or error code if highest bit set.
00457 uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags);
00458  
00459 /// Clear the specified Thread Flags of current running thread.
00460 /// \param[in]     flags         specifies the flags of the thread that shall be cleared.
00461 /// \return thread flags before clearing or error code if highest bit set.
00462 uint32_t osThreadFlagsClear (uint32_t flags);
00463  
00464 /// Get the current Thread Flags of current running thread.
00465 /// \return current thread flags.
00466 uint32_t osThreadFlagsGet (void);
00467  
00468 /// Wait for one or more Thread Flags of the current running thread to become signaled.
00469 /// \param[in]     flags         specifies the flags to wait for.
00470 /// \param[in]     options       specifies flags options (osFlagsXxxx).
00471 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00472 /// \return thread flags before clearing or error code if highest bit set.
00473 uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout);
00474  
00475  
00476 //  ==== Generic Wait Functions ====
00477  
00478 /// Wait for Timeout (Time Delay).
00479 /// \param[in]     ticks         \ref CMSIS_RTOS_TimeOutValue "time ticks" value
00480 /// \return status code that indicates the execution status of the function.
00481 osStatus_t osDelay (uint32_t ticks);
00482  
00483 /// Wait until specified time.
00484 /// \param[in]     ticks         absolute time in ticks
00485 /// \return status code that indicates the execution status of the function.
00486 osStatus_t osDelayUntil (uint32_t ticks);
00487  
00488  
00489 //  ==== Timer Management Functions ====
00490  
00491 /// Create and Initialize a timer.
00492 /// \param[in]     func          function pointer to callback function.
00493 /// \param[in]     type          \ref osTimerOnce for one-shot or \ref osTimerPeriodic for periodic behavior.
00494 /// \param[in]     argument      argument to the timer callback function.
00495 /// \param[in]     attr          timer attributes; NULL: default values.
00496 /// \return timer ID for reference by other functions or NULL in case of error.
00497 osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr);
00498  
00499 /// Get name of a timer.
00500 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
00501 /// \return name as null-terminated string.
00502 const char *osTimerGetName (osTimerId_t timer_id);
00503  
00504 /// Start or restart a timer.
00505 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
00506 /// \param[in]     ticks         \ref CMSIS_RTOS_TimeOutValue "time ticks" value of the timer.
00507 /// \return status code that indicates the execution status of the function.
00508 osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks);
00509  
00510 /// Stop a timer.
00511 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
00512 /// \return status code that indicates the execution status of the function.
00513 osStatus_t osTimerStop (osTimerId_t timer_id);
00514  
00515 /// Check if a timer is running.
00516 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
00517 /// \return 0 not running, 1 running.
00518 uint32_t osTimerIsRunning (osTimerId_t timer_id);
00519  
00520 /// Delete a timer.
00521 /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
00522 /// \return status code that indicates the execution status of the function.
00523 osStatus_t osTimerDelete (osTimerId_t timer_id);
00524  
00525  
00526 //  ==== Event Flags Management Functions ====
00527  
00528 /// Create and Initialize an Event Flags object.
00529 /// \param[in]     attr          event flags attributes; NULL: default values.
00530 /// \return event flags ID for reference by other functions or NULL in case of error.
00531 osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr);
00532  
00533 /// Get name of an Event Flags object.
00534 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
00535 /// \return name as null-terminated string.
00536 const char *osEventFlagsGetName (osEventFlagsId_t ef_id);
00537  
00538 /// Set the specified Event Flags.
00539 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
00540 /// \param[in]     flags         specifies the flags that shall be set.
00541 /// \return event flags after setting or error code if highest bit set.
00542 uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags);
00543  
00544 /// Clear the specified Event Flags.
00545 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
00546 /// \param[in]     flags         specifies the flags that shall be cleared.
00547 /// \return event flags before clearing or error code if highest bit set.
00548 uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags);
00549  
00550 /// Get the current Event Flags.
00551 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
00552 /// \return current event flags.
00553 uint32_t osEventFlagsGet (osEventFlagsId_t ef_id);
00554  
00555 /// Wait for one or more Event Flags to become signaled.
00556 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
00557 /// \param[in]     flags         specifies the flags to wait for.
00558 /// \param[in]     options       specifies flags options (osFlagsXxxx).
00559 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00560 /// \return event flags before clearing or error code if highest bit set.
00561 uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout);
00562  
00563 /// Delete an Event Flags object.
00564 /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
00565 /// \return status code that indicates the execution status of the function.
00566 osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id);
00567  
00568  
00569 //  ==== Mutex Management Functions ====
00570  
00571 /// Create and Initialize a Mutex object.
00572 /// \param[in]     attr          mutex attributes; NULL: default values.
00573 /// \return mutex ID for reference by other functions or NULL in case of error.
00574 osMutexId_t osMutexNew (const osMutexAttr_t *attr);
00575  
00576 /// Get name of a Mutex object.
00577 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
00578 /// \return name as null-terminated string.
00579 const char *osMutexGetName (osMutexId_t mutex_id);
00580  
00581 /// Acquire a Mutex or timeout if it is locked.
00582 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
00583 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00584 /// \return status code that indicates the execution status of the function.
00585 osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout);
00586  
00587 /// Release a Mutex that was acquired by \ref osMutexAcquire.
00588 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
00589 /// \return status code that indicates the execution status of the function.
00590 osStatus_t osMutexRelease (osMutexId_t mutex_id);
00591  
00592 /// Get Thread which owns a Mutex object.
00593 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
00594 /// \return thread ID of owner thread or NULL when mutex was not acquired.
00595 osThreadId_t osMutexGetOwner (osMutexId_t mutex_id);
00596  
00597 /// Delete a Mutex object.
00598 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
00599 /// \return status code that indicates the execution status of the function.
00600 osStatus_t osMutexDelete (osMutexId_t mutex_id);
00601  
00602  
00603 //  ==== Semaphore Management Functions ====
00604  
00605 /// Create and Initialize a Semaphore object.
00606 /// \param[in]     max_count     maximum number of available tokens.
00607 /// \param[in]     initial_count initial number of available tokens.
00608 /// \param[in]     attr          semaphore attributes; NULL: default values.
00609 /// \return semaphore ID for reference by other functions or NULL in case of error.
00610 osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr);
00611  
00612 /// Get name of a Semaphore object.
00613 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
00614 /// \return name as null-terminated string.
00615 const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id);
00616  
00617 /// Acquire a Semaphore token or timeout if no tokens are available.
00618 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
00619 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00620 /// \return status code that indicates the execution status of the function.
00621 osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout);
00622  
00623 /// Release a Semaphore token up to the initial maximum count.
00624 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
00625 /// \return status code that indicates the execution status of the function.
00626 osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id);
00627  
00628 /// Get current Semaphore token count.
00629 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
00630 /// \return number of tokens available.
00631 uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id);
00632  
00633 /// Delete a Semaphore object.
00634 /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
00635 /// \return status code that indicates the execution status of the function.
00636 osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id);
00637  
00638  
00639 //  ==== Memory Pool Management Functions ====
00640  
00641 /// Create and Initialize a Memory Pool object.
00642 /// \param[in]     block_count   maximum number of memory blocks in memory pool.
00643 /// \param[in]     block_size    memory block size in bytes.
00644 /// \param[in]     attr          memory pool attributes; NULL: default values.
00645 /// \return memory pool ID for reference by other functions or NULL in case of error.
00646 osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr);
00647  
00648 /// Get name of a Memory Pool object.
00649 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00650 /// \return name as null-terminated string.
00651 const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id);
00652  
00653 /// Allocate a memory block from a Memory Pool.
00654 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00655 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00656 /// \return address of the allocated memory block or NULL in case of no memory is available.
00657 void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout);
00658  
00659 /// Return an allocated memory block back to a Memory Pool.
00660 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00661 /// \param[in]     block         address of the allocated memory block to be returned to the memory pool.
00662 /// \return status code that indicates the execution status of the function.
00663 osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block);
00664  
00665 /// Get maximum number of memory blocks in a Memory Pool.
00666 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00667 /// \return maximum number of memory blocks.
00668 uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id);
00669  
00670 /// Get memory block size in a Memory Pool.
00671 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00672 /// \return memory block size in bytes.
00673 uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id);
00674  
00675 /// Get number of memory blocks used in a Memory Pool.
00676 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00677 /// \return number of memory blocks used.
00678 uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id);
00679  
00680 /// Get number of memory blocks available in a Memory Pool.
00681 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00682 /// \return number of memory blocks available.
00683 uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id);
00684  
00685 /// Delete a Memory Pool object.
00686 /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
00687 /// \return status code that indicates the execution status of the function.
00688 osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id);
00689  
00690  
00691 //  ==== Message Queue Management Functions ====
00692  
00693 /// Create and Initialize a Message Queue object.
00694 /// \param[in]     msg_count     maximum number of messages in queue.
00695 /// \param[in]     msg_size      maximum message size in bytes.
00696 /// \param[in]     attr          message queue attributes; NULL: default values.
00697 /// \return message queue ID for reference by other functions or NULL in case of error.
00698 osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr);
00699  
00700 /// Get name of a Message Queue object.
00701 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00702 /// \return name as null-terminated string.
00703 const char *osMessageQueueGetName (osMessageQueueId_t mq_id);
00704  
00705 /// Put a Message into a Queue or timeout if Queue is full.
00706 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00707 /// \param[in]     msg_ptr       pointer to buffer with message to put into a queue.
00708 /// \param[in]     msg_prio      message priority.
00709 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00710 /// \return status code that indicates the execution status of the function.
00711 osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
00712  
00713 /// Get a Message from a Queue or timeout if Queue is empty.
00714 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00715 /// \param[out]    msg_ptr       pointer to buffer for message to get from a queue.
00716 /// \param[out]    msg_prio      pointer to buffer for message priority or NULL.
00717 /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
00718 /// \return status code that indicates the execution status of the function.
00719 osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout);
00720  
00721 /// Get maximum number of messages in a Message Queue.
00722 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00723 /// \return maximum number of messages.
00724 uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id);
00725  
00726 /// Get maximum message size in a Memory Pool.
00727 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00728 /// \return maximum message size in bytes.
00729 uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id);
00730  
00731 /// Get number of queued messages in a Message Queue.
00732 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00733 /// \return number of queued messages.
00734 uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id);
00735  
00736 /// Get number of available slots for messages in a Message Queue.
00737 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00738 /// \return number of available slots for messages.
00739 uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id);
00740  
00741 /// Reset a Message Queue to initial empty state.
00742 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00743 /// \return status code that indicates the execution status of the function.
00744 osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id);
00745  
00746 /// Delete a Message Queue object.
00747 /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
00748 /// \return status code that indicates the execution status of the function.
00749 osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id);
00750  
00751  
00752 #ifdef  __cplusplus
00753 }
00754 #endif
00755  
00756 #endif  // CMSIS_OS2_H_