begriffs open source - cmsis-freertos/blob - CMSIS/RTOS2/FreeRTOS/Include1/cmsis_os.h

   1 /*
   2  * Copyright (c) 2013-2019 ARM Limited. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: Apache-2.0
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License); you may
   7  * not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
  14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * ----------------------------------------------------------------------
  19  *
  20  * $Date:        10. January 2017
  21  * $Revision:    V2.1.0
  22  *
  23  * Project:      CMSIS-RTOS API
  24  * Title:        cmsis_os.h FreeRTOS header file
  25  *
  26  * Version 0.02
  27  *    Initial Proposal Phase
  28  * Version 0.03
  29  *    osKernelStart added, optional feature: main started as thread
  30  *    osSemaphores have standard behavior
  31  *    osTimerCreate does not start the timer, added osTimerStart
  32  *    osThreadPass is renamed to osThreadYield
  33  * Version 1.01
  34  *    Support for C++ interface
  35  *     - const attribute removed from the osXxxxDef_t typedefs
  36  *     - const attribute added to the osXxxxDef macros
  37  *    Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
  38  *    Added: osKernelInitialize
  39  * Version 1.02
  40  *    Control functions for short timeouts in microsecond resolution:
  41  *    Added: osKernelSysTick, osKernelSysTickFrequency, osKernelSysTickMicroSec
  42  *    Removed: osSignalGet
  43  * Version 2.0.0
  44  *    OS objects creation without macros (dynamic creation and resource allocation):
  45  *     - added: osXxxxNew functions which replace osXxxxCreate
  46  *     - added: osXxxxAttr_t structures
  47  *     - deprecated: osXxxxCreate functions, osXxxxDef_t structures
  48  *     - deprecated: osXxxxDef and osXxxx macros
  49  *    osStatus codes simplified and renamed to osStatus_t
  50  *    osEvent return structure deprecated
  51  *    Kernel:
  52  *     - added: osKernelInfo_t and osKernelGetInfo
  53  *     - added: osKernelState_t and osKernelGetState (replaces osKernelRunning)
  54  *     - added: osKernelLock, osKernelUnlock
  55  *     - added: osKernelSuspend, osKernelResume
  56  *     - added: osKernelGetTickCount, osKernelGetTickFreq
  57  *     - renamed osKernelSysTick to osKernelGetSysTimerCount
  58  *     - replaced osKernelSysTickFrequency with osKernelGetSysTimerFreq
  59  *     - deprecated osKernelSysTickMicroSec
  60  *    Thread:
  61  *     - extended number of thread priorities
  62  *     - renamed osPrioriry to osPrioriry_t
  63  *     - replaced osThreadCreate with osThreadNew
  64  *     - added: osThreadGetName
  65  *     - added: osThreadState_t and osThreadGetState
  66  *     - added: osThreadGetStackSize, osThreadGetStackSpace
  67  *     - added: osThreadSuspend, osThreadResume
  68  *     - added: osThreadJoin, osThreadDetach, osThreadExit
  69  *     - added: osThreadGetCount, osThreadEnumerate
  70  *     - added: Thread Flags (moved from Signals)
  71  *    Signals:
  72  *     - renamed osSignals to osThreadFlags (moved to Thread Flags)
  73  *     - changed return value of Set/Clear/Wait functions
  74  *     - Clear function limited to current running thread
  75  *     - extended Wait function (options)
  76  *     - added: osThreadFlagsGet
  77  *    Event Flags:
  78  *     - added new independent object for handling Event Flags
  79  *    Delay and Wait functions:
  80  *     - added: osDelayUntil
  81  *     - deprecated: osWait
  82  *    Timer:
  83  *     - replaced osTimerCreate with osTimerNew
  84  *     - added: osTimerGetName, osTimerIsRunning
  85  *    Mutex:
  86  *     - extended: attributes (Recursive, Priority Inherit, Robust)
  87  *     - replaced osMutexCreate with osMutexNew
  88  *     - renamed osMutexWait to osMutexAcquire
  89  *     - added: osMutexGetName, osMutexGetOwner
  90  *    Semaphore:
  91  *     - extended: maximum and initial token count
  92  *     - replaced osSemaphoreCreate with osSemaphoreNew
  93  *     - renamed osSemaphoreWait to osSemaphoreAcquire (changed return value)
  94  *     - added: osSemaphoreGetName, osSemaphoreGetCount
  95  *    Memory Pool:
  96  *     - using osMemoryPool prefix instead of osPool
  97  *     - replaced osPoolCreate with osMemoryPoolNew
  98  *     - extended osMemoryPoolAlloc (timeout)
  99  *     - added: osMemoryPoolGetName
 100  *     - added: osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize
 101  *     - added: osMemoryPoolGetCount, osMemoryPoolGetSpace
 102  *     - added: osMemoryPoolDelete
 103  *     - deprecated: osPoolCAlloc
 104  *    Message Queue:
 105  *     - extended: fixed size message instead of a single 32-bit value
 106  *     - using osMessageQueue prefix instead of osMessage
 107  *     - replaced osMessageCreate with osMessageQueueNew
 108  *     - updated: osMessageQueuePut, osMessageQueueGet
 109  *     - added: osMessageQueueGetName
 110  *     - added: osMessageQueueGetCapacity, osMessageQueueGetMsgSize
 111  *     - added: osMessageQueueGetCount, osMessageQueueGetSpace
 112  *     - added: osMessageQueueReset, osMessageQueueDelete
 113  *    Mail Queue:
 114  *     - deprecated (superseded by extended Message Queue functionality)
 115  * Version 2.1.0
 116  *    Support for critical and uncritical sections (nesting safe):
 117  *    - updated: osKernelLock, osKernelUnlock
 118  *    - added: osKernelRestoreLock
 119  *    Updated Thread and Event Flags:
 120  *    - changed flags parameter and return type from int32_t to uint32_t
 121  *---------------------------------------------------------------------------*/
 122
 123 #ifndef CMSIS_OS_H_
 124 #define CMSIS_OS_H_
 125
 126 #include "FreeRTOS.h"
 127 #include "task.h"
 128
 129 #define RTOS_ID_n             ((tskKERNEL_VERSION_MAJOR << 16) | (tskKERNEL_VERSION_MINOR))
 130 #define RTOS_ID_s             ("FreeRTOS " tskKERNEL_VERSION_NUMBER)
 131
 132 #define osCMSIS               0x20001U  ///< API version (main[31:16].sub[15:0])
 133
 134 #define osCMSIS_FreeRTOS      RTOS_ID_n ///< RTOS identification and version (main[31:16].sub[15:0])
 135
 136 #define osKernelSystemId      RTOS_ID_s ///< RTOS identification string
 137
 138 #define osFeature_MainThread  0         ///< main thread      1=main can be thread, 0=not available
 139 #define osFeature_Signals     24U       ///< maximum number of Signal Flags available per thread
 140 #define osFeature_Semaphore   65535U    ///< maximum count for \ref osSemaphoreCreate function
 141 #define osFeature_Wait        0         ///< osWait function: 1=available, 0=not available
 142 #define osFeature_SysTick     1         ///< osKernelSysTick functions: 1=available, 0=not available
 143 #define osFeature_Pool        0         ///< Memory Pools:    1=available, 0=not available
 144 #define osFeature_MessageQ    1         ///< Message Queues:  1=available, 0=not available
 145 #define osFeature_MailQ       0         ///< Mail Queues:     1=available, 0=not available
 146
 147 #if   defined(__CC_ARM)
 148 #define os_InRegs __value_in_regs
 149 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
 150 #define os_InRegs __attribute__((value_in_regs))
 151 #else
 152 #define os_InRegs
 153 #endif
 154
 155 #include "cmsis_os2.h"
 156
 157 #ifdef  __cplusplus
 158 extern "C"
 159 {
 160 #endif
 161
 162
 163 // ==== Enumerations, structures, defines ====
 164
 165 /// Priority values.
 166 #if (osCMSIS < 0x20000U)
 167 typedef enum {
 168   osPriorityIdle          = -3,         ///< Priority: idle (lowest)
 169   osPriorityLow           = -2,         ///< Priority: low
 170   osPriorityBelowNormal   = -1,         ///< Priority: below normal
 171   osPriorityNormal        =  0,         ///< Priority: normal (default)
 172   osPriorityAboveNormal   = +1,         ///< Priority: above normal
 173   osPriorityHigh          = +2,         ///< Priority: high
 174   osPriorityRealtime      = +3,         ///< Priority: realtime (highest)
 175   osPriorityError         = 0x84,       ///< System cannot determine priority or illegal priority.
 176   osPriorityReserved      = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
 177 } osPriority;
 178 #else
 179 #define osPriority osPriority_t
 180 #endif
 181
 182 /// Entry point of a thread.
 183 typedef void (*os_pthread) (void const *argument);
 184
 185 /// Entry point of a timer call back function.
 186 typedef void (*os_ptimer) (void const *argument);
 187
 188 /// Timer type.
 189 #if (osCMSIS < 0x20000U)
 190 typedef enum {
 191   osTimerOnce             = 0,          ///< One-shot timer.
 192   osTimerPeriodic         = 1           ///< Repeating timer.
 193 } os_timer_type;
 194 #else
 195 #define os_timer_type osTimerType_t
 196 #endif
 197
 198 /// Timeout value.
 199 #define osWaitForever       0xFFFFFFFFU ///< Wait forever timeout value.
 200
 201 /// Status code values returned by CMSIS-RTOS functions.
 202 #if (osCMSIS < 0x20000U)
 203 typedef enum {
 204   osOK                    =    0,       ///< Function completed; no error or event occurred.
 205   osEventSignal           = 0x08,       ///< Function completed; signal event occurred.
 206   osEventMessage          = 0x10,       ///< Function completed; message event occurred.
 207   osEventMail             = 0x20,       ///< Function completed; mail event occurred.
 208   osEventTimeout          = 0x40,       ///< Function completed; timeout occurred.
 209   osErrorParameter        = 0x80,       ///< Parameter error: a mandatory parameter was missing or specified an incorrect object.
 210   osErrorResource         = 0x81,       ///< Resource not available: a specified resource was not available.
 211   osErrorTimeoutResource  = 0xC1,       ///< Resource not available within given time: a specified resource was not available within the timeout period.
 212   osErrorISR              = 0x82,       ///< Not allowed in ISR context: the function cannot be called from interrupt service routines.
 213   osErrorISRRecursive     = 0x83,       ///< Function called multiple times from ISR with same object.
 214   osErrorPriority         = 0x84,       ///< System cannot determine priority or thread has illegal priority.
 215   osErrorNoMemory         = 0x85,       ///< System is out of memory: it was impossible to allocate or reserve memory for the operation.
 216   osErrorValue            = 0x86,       ///< Value of a parameter is out of range.
 217   osErrorOS               = 0xFF,       ///< Unspecified RTOS error: run-time error but no other error message fits.
 218   osStatusReserved        = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
 219 } osStatus;
 220 #else
 221 typedef int32_t                  osStatus;
 222 #define osEventSignal           (0x08)
 223 #define osEventMessage          (0x10)
 224 #define osEventMail             (0x20)
 225 #define osEventTimeout          (0x40)
 226 #define osErrorOS               osError
 227 #define osErrorTimeoutResource  osErrorTimeout
 228 #define osErrorISRRecursive     (-126)
 229 #define osErrorValue            (-127)
 230 #define osErrorPriority         (-128)
 231 #endif
 232
 233
 234 // >>> the following data type definitions may be adapted towards a specific RTOS
 235
 236 /// Thread ID identifies the thread.
 237 #if (osCMSIS < 0x20000U)
 238 typedef void *osThreadId;
 239 #else
 240 #define osThreadId osThreadId_t
 241 #endif
 242
 243 /// Timer ID identifies the timer.
 244 #if (osCMSIS < 0x20000U)
 245 typedef void *osTimerId;
 246 #else
 247 #define osTimerId osTimerId_t
 248 #endif
 249
 250 /// Mutex ID identifies the mutex.
 251 #if (osCMSIS < 0x20000U)
 252 typedef void *osMutexId;
 253 #else
 254 #define osMutexId osMutexId_t
 255 #endif
 256
 257 /// Semaphore ID identifies the semaphore.
 258 #if (osCMSIS < 0x20000U)
 259 typedef void *osSemaphoreId;
 260 #else
 261 #define osSemaphoreId osSemaphoreId_t
 262 #endif
 263
 264 /// Pool ID identifies the memory pool.
 265 typedef void *osPoolId;
 266
 267 /// Message ID identifies the message queue.
 268 typedef void *osMessageQId;
 269
 270 /// Mail ID identifies the mail queue.
 271 typedef void *osMailQId;
 272
 273
 274 /// Thread Definition structure contains startup information of a thread.
 275 #if (osCMSIS < 0x20000U)
 276 typedef struct os_thread_def {
 277   os_pthread                 pthread;   ///< start address of thread function
 278   osPriority               tpriority;   ///< initial thread priority
 279   uint32_t                 instances;   ///< maximum number of instances of that thread function
 280   uint32_t                 stacksize;   ///< stack size requirements in bytes; 0 is default stack size
 281 } osThreadDef_t;
 282 #else
 283 typedef struct os_thread_def {
 284   os_pthread                 pthread;   ///< start address of thread function
 285   osThreadAttr_t                attr;   ///< thread attributes
 286 } osThreadDef_t;
 287 #endif
 288
 289 /// Timer Definition structure contains timer parameters.
 290 #if (osCMSIS < 0x20000U)
 291 typedef struct os_timer_def {
 292   os_ptimer                   ptimer;   ///< start address of a timer function
 293 } osTimerDef_t;
 294 #else
 295 typedef struct os_timer_def {
 296   os_ptimer                   ptimer;   ///< start address of a timer function
 297   osTimerAttr_t                 attr;   ///< timer attributes
 298 } osTimerDef_t;
 299 #endif
 300
 301 /// Mutex Definition structure contains setup information for a mutex.
 302 #if (osCMSIS < 0x20000U)
 303 typedef struct os_mutex_def {
 304   uint32_t                     dummy;   ///< dummy value
 305 } osMutexDef_t;
 306 #else
 307 #define osMutexDef_t osMutexAttr_t
 308 #endif
 309
 310 /// Semaphore Definition structure contains setup information for a semaphore.
 311 #if (osCMSIS < 0x20000U)
 312 typedef struct os_semaphore_def {
 313   uint32_t                     dummy;   ///< dummy value
 314 } osSemaphoreDef_t;
 315 #else
 316 #define osSemaphoreDef_t osSemaphoreAttr_t
 317 #endif
 318
 319 /// Definition structure for memory block allocation.
 320 #if (osCMSIS < 0x20000U)
 321 typedef struct os_pool_def {
 322   uint32_t                   pool_sz;   ///< number of items (elements) in the pool
 323   uint32_t                   item_sz;   ///< size of an item
 324   void                         *pool;   ///< pointer to memory for pool
 325 } osPoolDef_t;
 326 #else
 327 typedef struct os_pool_def {
 328   uint32_t                   pool_sz;   ///< number of items (elements) in the pool
 329   uint32_t                   item_sz;   ///< size of an item
 330   osMemoryPoolAttr_t            attr;   ///< memory pool attributes
 331 } osPoolDef_t;
 332 #endif
 333
 334 /// Definition structure for message queue.
 335 #if (osCMSIS < 0x20000U)
 336 typedef struct os_messageQ_def {
 337   uint32_t                  queue_sz;   ///< number of elements in the queue
 338   void                         *pool;   ///< memory array for messages
 339 } osMessageQDef_t;
 340 #else
 341 typedef struct os_messageQ_def {
 342   uint32_t                  queue_sz;   ///< number of elements in the queue
 343   osMessageQueueAttr_t          attr;   ///< message queue attributes
 344 } osMessageQDef_t;
 345 #endif
 346
 347 /// Definition structure for mail queue.
 348 #if (osCMSIS < 0x20000U)
 349 typedef struct os_mailQ_def {
 350   uint32_t                  queue_sz;   ///< number of elements in the queue
 351   uint32_t                   item_sz;   ///< size of an item
 352   void                         *pool;   ///< memory array for mail
 353 } osMailQDef_t;
 354 #else
 355 typedef struct os_mailQ_def {
 356   uint32_t                  queue_sz;   ///< number of elements in the queue
 357   uint32_t                   item_sz;   ///< size of an item
 358   void                         *mail;   ///< pointer to mail
 359   osMemoryPoolAttr_t         mp_attr;   ///< memory pool attributes
 360   osMessageQueueAttr_t       mq_attr;   ///< message queue attributes
 361 } osMailQDef_t;
 362 #endif
 363
 364
 365 /// Event structure contains detailed information about an event.
 366 typedef struct {
 367   osStatus                    status;   ///< status code: event or error information
 368   union {
 369     uint32_t                       v;   ///< message as 32-bit value
 370     void                          *p;   ///< message or mail as void pointer
 371     int32_t                  signals;   ///< signal flags
 372   } value;                              ///< event value
 373   union {
 374     osMailQId                mail_id;   ///< mail id obtained by \ref osMailCreate
 375     osMessageQId          message_id;   ///< message id obtained by \ref osMessageCreate
 376   } def;                                ///< event definition
 377 } osEvent;
 378
 379
 380 //  ==== Kernel Management Functions ====
 381
 382 /// Initialize the RTOS Kernel for creating objects.
 383 /// \return status code that indicates the execution status of the function.
 384 #if (osCMSIS < 0x20000U)
 385 osStatus osKernelInitialize (void);
 386 #endif
 387
 388 /// Start the RTOS Kernel scheduler.
 389 /// \return status code that indicates the execution status of the function.
 390 #if (osCMSIS < 0x20000U)
 391 osStatus osKernelStart (void);
 392 #endif
 393
 394 /// Check if the RTOS kernel is already started.
 395 /// \return 0 RTOS is not started, 1 RTOS is started.
 396 #if (osCMSIS < 0x20000U)
 397 int32_t osKernelRunning(void);
 398 #endif
 399
 400 #if (defined(osFeature_SysTick) && (osFeature_SysTick != 0))  // System Timer available
 401
 402 /// Get the RTOS kernel system timer counter.
 403 /// \return RTOS kernel system timer as 32-bit value
 404 #if (osCMSIS < 0x20000U)
 405 uint32_t osKernelSysTick (void);
 406 #else
 407 #define  osKernelSysTick osKernelGetSysTimerCount
 408 #endif
 409
 410 /// The RTOS kernel system timer frequency in Hz.
 411 /// \note Reflects the system timer setting and is typically defined in a configuration file.
 412 #if (osCMSIS < 0x20000U)
 413 #define osKernelSysTickFrequency 100000000
 414 #endif
 415
 416 /// Convert a microseconds value to a RTOS kernel system timer value.
 417 /// \param         microsec     time value in microseconds.
 418 /// \return time value normalized to the \ref osKernelSysTickFrequency
 419 #if (osCMSIS < 0x20000U)
 420 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
 421 #else
 422 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec *  osKernelGetSysTimerFreq()) / 1000000)
 423 #endif
 424
 425 #endif  // System Timer available
 426
 427
 428 //  ==== Thread Management Functions ====
 429
 430 /// Create a Thread Definition with function, priority, and stack requirements.
 431 /// \param         name          name of the thread function.
 432 /// \param         priority      initial priority of the thread function.
 433 /// \param         instances     number of possible thread instances.
 434 /// \param         stacksz       stack size (in bytes) requirements for the thread function.
 435 #if defined (osObjectsExternal)  // object is external
 436 #define osThreadDef(name, priority, instances, stacksz) \
 437 extern const osThreadDef_t os_thread_def_##name
 438 #else                            // define the object
 439 #define osThreadDef(name, priority, instances, stacksz) \
 440 static uint64_t os_thread_stack##name[(stacksz)?(((stacksz+7)/8)):1]; \
 441 static StaticTask_t os_thread_cb_##name; \
 442 const osThreadDef_t os_thread_def_##name = \
 443 { (name), \
 444   { NULL, osThreadDetached, \
 445     (instances == 1) ? (&os_thread_cb_##name) : NULL,\
 446     (instances == 1) ? sizeof(StaticTask_t) : 0U, \
 447     ((stacksz) && (instances == 1)) ? (&os_thread_stack##name) : NULL, \
 448     8*((stacksz+7)/8), \
 449     (priority), 0U, 0U } }
 450 #endif
 451
 452 /// Access a Thread definition.
 453 /// \param         name          name of the thread definition object.
 454 #define osThread(name) \
 455 &os_thread_def_##name
 456
 457 /// Create a thread and add it to Active Threads and set it to state READY.
 458 /// \param[in]     thread_def    thread definition referenced with \ref osThread.
 459 /// \param[in]     argument      pointer that is passed to the thread function as start argument.
 460 /// \return thread ID for reference by other functions or NULL in case of error.
 461 osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument);
 462
 463 /// Return the thread ID of the current running thread.
 464 /// \return thread ID for reference by other functions or NULL in case of error.
 465 #if (osCMSIS < 0x20000U)
 466 osThreadId osThreadGetId (void);
 467 #endif
 468
 469 /// Change priority of a thread.
 470 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 471 /// \param[in]     priority      new priority value for the thread function.
 472 /// \return status code that indicates the execution status of the function.
 473 #if (osCMSIS < 0x20000U)
 474 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
 475 #endif
 476
 477 /// Get current priority of a thread.
 478 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 479 /// \return current priority value of the specified thread.
 480 #if (osCMSIS < 0x20000U)
 481 osPriority osThreadGetPriority (osThreadId thread_id);
 482 #endif
 483
 484 /// Pass control to next thread that is in state \b READY.
 485 /// \return status code that indicates the execution status of the function.
 486 #if (osCMSIS < 0x20000U)
 487 osStatus osThreadYield (void);
 488 #endif
 489
 490 /// Terminate execution of a thread.
 491 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 492 /// \return status code that indicates the execution status of the function.
 493 #if (osCMSIS < 0x20000U)
 494 osStatus osThreadTerminate (osThreadId thread_id);
 495 #endif
 496
 497
 498 //  ==== Signal Management ====
 499
 500 /// Set the specified Signal Flags of an active thread.
 501 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 502 /// \param[in]     signals       specifies the signal flags of the thread that should be set.
 503 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
 504 int32_t osSignalSet (osThreadId thread_id, int32_t signals);
 505
 506 /// Clear the specified Signal Flags of an active thread.
 507 /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
 508 /// \param[in]     signals       specifies the signal flags of the thread that shall be cleared.
 509 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters or call from ISR.
 510 int32_t osSignalClear (osThreadId thread_id, int32_t signals);
 511
 512 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread.
 513 /// \param[in]     signals       wait until all specified signal flags set or 0 for any single signal flag.
 514 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 515 /// \return event flag information or error code.
 516 os_InRegs osEvent osSignalWait (int32_t signals, uint32_t millisec);
 517
 518
 519 //  ==== Generic Wait Functions ====
 520
 521 /// Wait for Timeout (Time Delay).
 522 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue "time delay" value
 523 /// \return status code that indicates the execution status of the function.
 524 #if (osCMSIS < 0x20000U)
 525 osStatus osDelay (uint32_t millisec);
 526 #endif
 527
 528 #if (defined (osFeature_Wait) && (osFeature_Wait != 0))  // Generic Wait available
 529
 530 /// Wait for Signal, Message, Mail, or Timeout.
 531 /// \param[in] millisec          \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
 532 /// \return event that contains signal, message, or mail information or error code.
 533 os_InRegs osEvent osWait (uint32_t millisec);
 534
 535 #endif  // Generic Wait available
 536
 537
 538 //  ==== Timer Management Functions ====
 539
 540 /// Define a Timer object.
 541 /// \param         name          name of the timer object.
 542 /// \param         function      name of the timer call back function.
 543 #if defined (osObjectsExternal)  // object is external
 544 #define osTimerDef(name, function) \
 545 extern const osTimerDef_t os_timer_def_##name
 546 #else                            // define the object
 547 #define osTimerDef(name, function) \
 548 static StaticTimer_t os_timer_cb_##name; \
 549 const osTimerDef_t os_timer_def_##name = \
 550 { (function), { NULL, 0U, (&os_timer_cb_##name), sizeof(StaticTimer_t) } }
 551 #endif
 552
 553 /// Access a Timer definition.
 554 /// \param         name          name of the timer object.
 555 #define osTimer(name) \
 556 &os_timer_def_##name
 557
 558 /// Create and Initialize a timer.
 559 /// \param[in]     timer_def     timer object referenced with \ref osTimer.
 560 /// \param[in]     type          osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
 561 /// \param[in]     argument      argument to the timer call back function.
 562 /// \return timer ID for reference by other functions or NULL in case of error.
 563 osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument);
 564
 565 /// Start or restart a timer.
 566 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
 567 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue "time delay" value of the timer.
 568 /// \return status code that indicates the execution status of the function.
 569 #if (osCMSIS < 0x20000U)
 570 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
 571 #endif
 572
 573 /// Stop a timer.
 574 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
 575 /// \return status code that indicates the execution status of the function.
 576 #if (osCMSIS < 0x20000U)
 577 osStatus osTimerStop (osTimerId timer_id);
 578 #endif
 579
 580 /// Delete a timer.
 581 /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
 582 /// \return status code that indicates the execution status of the function.
 583 #if (osCMSIS < 0x20000U)
 584 osStatus osTimerDelete (osTimerId timer_id);
 585 #endif
 586
 587
 588 //  ==== Mutex Management Functions ====
 589
 590 /// Define a Mutex.
 591 /// \param         name          name of the mutex object.
 592 #if defined (osObjectsExternal)  // object is external
 593 #define osMutexDef(name) \
 594 extern const osMutexDef_t os_mutex_def_##name
 595 #else                            // define the object
 596 #define osMutexDef(name) \
 597 static StaticSemaphore_t os_mutex_cb_##name; \
 598 const osMutexDef_t os_mutex_def_##name = \
 599 { NULL, osMutexRecursive | osMutexPrioInherit, (&os_mutex_cb_##name), sizeof(StaticSemaphore_t) }
 600 #endif
 601
 602 /// Access a Mutex definition.
 603 /// \param         name          name of the mutex object.
 604 #define osMutex(name) \
 605 &os_mutex_def_##name
 606
 607 /// Create and Initialize a Mutex object.
 608 /// \param[in]     mutex_def     mutex definition referenced with \ref osMutex.
 609 /// \return mutex ID for reference by other functions or NULL in case of error.
 610 osMutexId osMutexCreate (const osMutexDef_t *mutex_def);
 611
 612 /// Wait until a Mutex becomes available.
 613 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
 614 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 615 /// \return status code that indicates the execution status of the function.
 616 #if (osCMSIS < 0x20000U)
 617 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
 618 #else
 619 #define  osMutexWait osMutexAcquire
 620 #endif
 621
 622 /// Release a Mutex that was obtained by \ref osMutexWait.
 623 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
 624 /// \return status code that indicates the execution status of the function.
 625 #if (osCMSIS < 0x20000U)
 626 osStatus osMutexRelease (osMutexId mutex_id);
 627 #endif
 628
 629 /// Delete a Mutex object.
 630 /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
 631 /// \return status code that indicates the execution status of the function.
 632 #if (osCMSIS < 0x20000U)
 633 osStatus osMutexDelete (osMutexId mutex_id);
 634 #endif
 635
 636
 637 //  ==== Semaphore Management Functions ====
 638
 639 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0U))  // Semaphore available
 640
 641 /// Define a Semaphore object.
 642 /// \param         name          name of the semaphore object.
 643 #if defined (osObjectsExternal)  // object is external
 644 #define osSemaphoreDef(name) \
 645 extern const osSemaphoreDef_t os_semaphore_def_##name
 646 #else                            // define the object
 647 #define osSemaphoreDef(name) \
 648 static StaticSemaphore_t os_semaphore_cb_##name; \
 649 const osSemaphoreDef_t os_semaphore_def_##name = \
 650 { NULL, 0U, (&os_semaphore_cb_##name), sizeof(StaticSemaphore_t) }
 651 #endif
 652
 653 /// Access a Semaphore definition.
 654 /// \param         name          name of the semaphore object.
 655 #define osSemaphore(name) \
 656 &os_semaphore_def_##name
 657
 658 /// Create and Initialize a Semaphore object.
 659 /// \param[in]     semaphore_def semaphore definition referenced with \ref osSemaphore.
 660 /// \param[in]     count         maximum and initial number of available tokens.
 661 /// \return semaphore ID for reference by other functions or NULL in case of error.
 662 osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count);
 663
 664 /// Wait until a Semaphore token becomes available.
 665 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
 666 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 667 /// \return number of available tokens, or -1 in case of incorrect parameters.
 668 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
 669
 670 /// Release a Semaphore token.
 671 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
 672 /// \return status code that indicates the execution status of the function.
 673 #if (osCMSIS < 0x20000U)
 674 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
 675 #endif
 676
 677 /// Delete a Semaphore object.
 678 /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
 679 /// \return status code that indicates the execution status of the function.
 680 #if (osCMSIS < 0x20000U)
 681 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id);
 682 #endif
 683
 684 #endif  // Semaphore available
 685
 686
 687 //  ==== Memory Pool Management Functions ====
 688
 689 #if (defined(osFeature_Pool) && (osFeature_Pool != 0))  // Memory Pool available
 690
 691 /// \brief Define a Memory Pool.
 692 /// \param         name          name of the memory pool.
 693 /// \param         no            maximum number of blocks (objects) in the memory pool.
 694 /// \param         type          data type of a single block (object).
 695 #if defined (osObjectsExternal)  // object is external
 696 #define osPoolDef(name, no, type) \
 697 extern const osPoolDef_t os_pool_def_##name
 698 #else                            // define the object
 699 #define osPoolDef(name, no, type) \
 700 const osPoolDef_t os_pool_def_##name = \
 701 { (no), sizeof(type), {NULL} }
 702 #endif
 703
 704 /// \brief Access a Memory Pool definition.
 705 /// \param         name          name of the memory pool
 706 #define osPool(name) \
 707 &os_pool_def_##name
 708
 709 /// Create and Initialize a Memory Pool object.
 710 /// \param[in]     pool_def      memory pool definition referenced with \ref osPool.
 711 /// \return memory pool ID for reference by other functions or NULL in case of error.
 712 osPoolId osPoolCreate (const osPoolDef_t *pool_def);
 713
 714 /// Allocate a memory block from a Memory Pool.
 715 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
 716 /// \return address of the allocated memory block or NULL in case of no memory available.
 717 void *osPoolAlloc (osPoolId pool_id);
 718
 719 /// Allocate a memory block from a Memory Pool and set memory block to zero.
 720 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
 721 /// \return address of the allocated memory block or NULL in case of no memory available.
 722 void *osPoolCAlloc (osPoolId pool_id);
 723
 724 /// Return an allocated memory block back to a Memory Pool.
 725 /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
 726 /// \param[in]     block         address of the allocated memory block to be returned to the memory pool.
 727 /// \return status code that indicates the execution status of the function.
 728 osStatus osPoolFree (osPoolId pool_id, void *block);
 729
 730 #endif  // Memory Pool available
 731
 732
 733 //  ==== Message Queue Management Functions ====
 734
 735 #if (defined(osFeature_MessageQ) && (osFeature_MessageQ != 0))  // Message Queue available
 736
 737 /// \brief Create a Message Queue Definition.
 738 /// \param         name          name of the queue.
 739 /// \param         queue_sz      maximum number of messages in the queue.
 740 /// \param         type          data type of a single message element (for debugger).
 741 #if defined (osObjectsExternal)  // object is external
 742 #define osMessageQDef(name, queue_sz, type) \
 743 extern const osMessageQDef_t os_messageQ_def_##name
 744 #else                            // define the object
 745 #define osMessageQDef(name, queue_sz, type) \
 746 static StaticQueue_t os_mq_cb_##name; \
 747 static uint32_t os_mq_data_##name[(queue_sz) * sizeof(type)]; \
 748 const osMessageQDef_t os_messageQ_def_##name = \
 749 { (queue_sz), \
 750   { NULL, 0U, (&os_mq_cb_##name), sizeof(StaticQueue_t), \
 751               (&os_mq_data_##name), sizeof(os_mq_data_##name) } }
 752 #endif
 753
 754 /// \brief Access a Message Queue Definition.
 755 /// \param         name          name of the queue
 756 #define osMessageQ(name) \
 757 &os_messageQ_def_##name
 758
 759 /// Create and Initialize a Message Queue object.
 760 /// \param[in]     queue_def     message queue definition referenced with \ref osMessageQ.
 761 /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
 762 /// \return message queue ID for reference by other functions or NULL in case of error.
 763 osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id);
 764
 765 /// Put a Message to a Queue.
 766 /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
 767 /// \param[in]     info          message information.
 768 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 769 /// \return status code that indicates the execution status of the function.
 770 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
 771
 772 /// Get a Message from a Queue or timeout if Queue is empty.
 773 /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
 774 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 775 /// \return event information that includes status code.
 776 os_InRegs osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
 777
 778 #endif  // Message Queue available
 779
 780
 781 //  ==== Mail Queue Management Functions ====
 782
 783 #if (defined(osFeature_MailQ) && (osFeature_MailQ != 0))  // Mail Queue available
 784
 785 /// \brief Create a Mail Queue Definition.
 786 /// \param         name          name of the queue.
 787 /// \param         queue_sz      maximum number of mails in the queue.
 788 /// \param         type          data type of a single mail element.
 789 #if defined (osObjectsExternal)  // object is external
 790 #define osMailQDef(name, queue_sz, type) \
 791 extern const osMailQDef_t os_mailQ_def_##name
 792 #else                            // define the object
 793 #define osMailQDef(name, queue_sz, type) \
 794 const osMailQDef_t os_mailQ_def_##name = \
 795 { (queue_sz), sizeof(type), NULL }
 796 #endif
 797
 798 /// \brief Access a Mail Queue Definition.
 799 /// \param         name          name of the queue
 800 #define osMailQ(name) \
 801 &os_mailQ_def_##name
 802
 803 /// Create and Initialize a Mail Queue object.
 804 /// \param[in]     queue_def     mail queue definition referenced with \ref osMailQ.
 805 /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
 806 /// \return mail queue ID for reference by other functions or NULL in case of error.
 807 osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id);
 808
 809 /// Allocate a memory block for mail from a mail memory pool.
 810 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 811 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
 812 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
 813 void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
 814
 815 /// Allocate a memory block for mail from a mail memory pool and set memory block to zero.
 816 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 817 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
 818 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
 819 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
 820
 821 /// Put a Mail into a Queue.
 822 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 823 /// \param[in]     mail          pointer to memory with mail to put into a queue.
 824 /// \return status code that indicates the execution status of the function.
 825 osStatus osMailPut (osMailQId queue_id, const void *mail);
 826
 827 /// Get a Mail from a Queue or timeout if Queue is empty.
 828 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 829 /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
 830 /// \return event information that includes status code.
 831 os_InRegs osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
 832
 833 /// Free a memory block by returning it to a mail memory pool.
 834 /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
 835 /// \param[in]     mail          pointer to memory block that was obtained with \ref osMailGet.
 836 /// \return status code that indicates the execution status of the function.
 837 osStatus osMailFree (osMailQId queue_id, void *mail);
 838
 839 #endif  // Mail Queue available
 840
 841
 842 #ifdef  __cplusplus
 843 }
 844 #endif
 845
 846 #endif  // CMSIS_OS_H_