Subversion Repositories DashDisplay

Rev

Rev 2 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed

  1. /* ----------------------------------------------------------------------
  2.  * $Date:        5. February 2013
  3.  * $Revision:    V1.02
  4.  *
  5.  * Project:      CMSIS-RTOS API
  6.  * Title:        cmsis_os.h template header file
  7.  *
  8.  * Version 0.02
  9.  *    Initial Proposal Phase
  10.  * Version 0.03
  11.  *    osKernelStart added, optional feature: main started as thread
  12.  *    osSemaphores have standard behavior
  13.  *    osTimerCreate does not start the timer, added osTimerStart
  14.  *    osThreadPass is renamed to osThreadYield
  15.  * Version 1.01
  16.  *    Support for C++ interface
  17.  *     - const attribute removed from the osXxxxDef_t typedef's
  18.  *     - const attribute added to the osXxxxDef macros
  19.  *    Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
  20.  *    Added: osKernelInitialize
  21.  * Version 1.02
  22.  *    Control functions for short timeouts in microsecond resolution:
  23.  *    Added: osKernelSysTick, osKernelSysTickFrequency, osKernelSysTickMicroSec
  24.  *    Removed: osSignalGet
  25.  *----------------------------------------------------------------------------
  26.  *
  27.  * Copyright (c) 2013 ARM LIMITED
  28.  * All rights reserved.
  29.  * Redistribution and use in source and binary forms, with or without
  30.  * modification, are permitted provided that the following conditions are met:
  31.  *  - Redistributions of source code must retain the above copyright
  32.  *    notice, this list of conditions and the following disclaimer.
  33.  *  - Redistributions in binary form must reproduce the above copyright
  34.  *    notice, this list of conditions and the following disclaimer in the
  35.  *    documentation and/or other materials provided with the distribution.
  36.  *  - Neither the name of ARM  nor the names of its contributors may be used
  37.  *    to endorse or promote products derived from this software without
  38.  *    specific prior written permission.
  39.  *
  40.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  41.  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  43.  * ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
  44.  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  45.  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  46.  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  47.  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  48.  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49.  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  50.  * POSSIBILITY OF SUCH DAMAGE.
  51.  *---------------------------------------------------------------------------*/
  52.  
  53.  
  54. #ifndef _CMSIS_OS_H
  55. #define _CMSIS_OS_H
  56.  
  57. /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version.
  58. #define osCMSIS           0x10002      ///< API version (main [31:16] .sub [15:0])
  59.  
  60. /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlying RTOS kernel and version number.
  61. #define osCMSIS_KERNEL    0x10000          ///< RTOS identification and version (main [31:16] .sub [15:0])
  62.  
  63. /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS.
  64. #define osKernelSystemId "KERNEL V1.00"   ///< RTOS identification string
  65.  
  66. /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS.
  67. #define osFeature_MainThread   1       ///< main thread      1=main can be thread, 0=not available
  68. #define osFeature_Pool         1       ///< Memory Pools:    1=available, 0=not available
  69. #define osFeature_MailQ        1       ///< Mail Queues:     1=available, 0=not available
  70. #define osFeature_MessageQ     1       ///< Message Queues:  1=available, 0=not available
  71. #define osFeature_Signals      8       ///< maximum number of Signal Flags available per thread
  72. #define osFeature_Semaphore    30      ///< maximum count for \ref osSemaphoreCreate function
  73. #define osFeature_Wait         1       ///< osWait function: 1=available, 0=not available
  74. #define osFeature_SysTick      1       ///< osKernelSysTick functions: 1=available, 0=not available
  75.  
  76. #include <stdint.h>
  77. #include <stddef.h>
  78.  
  79. #ifdef  __cplusplus
  80. extern "C"
  81. {
  82. #endif
  83.  
  84.  
  85. // ==== Enumeration, structures, defines ====
  86.  
  87. /// Priority used for thread control.
  88. /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS.
  89. typedef enum  {
  90.   osPriorityIdle          = -3,          ///< priority: idle (lowest)
  91.   osPriorityLow           = -2,          ///< priority: low
  92.   osPriorityBelowNormal   = -1,          ///< priority: below normal
  93.   osPriorityNormal        =  0,          ///< priority: normal (default)
  94.   osPriorityAboveNormal   = +1,          ///< priority: above normal
  95.   osPriorityHigh          = +2,          ///< priority: high
  96.   osPriorityRealtime      = +3,          ///< priority: realtime (highest)
  97.   osPriorityError         =  0x84        ///< system cannot determine priority or thread has illegal priority
  98. } osPriority;
  99.  
  100. /// Timeout value.
  101. /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS.
  102. #define osWaitForever     0xFFFFFFFF     ///< wait forever timeout value
  103.  
  104. /// Status code values returned by CMSIS-RTOS functions.
  105. /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS.
  106. typedef enum  {
  107.   osOK                    =     0,       ///< function completed; no error or event occurred.
  108.   osEventSignal           =  0x08,       ///< function completed; signal event occurred.
  109.   osEventMessage          =  0x10,       ///< function completed; message event occurred.
  110.   osEventMail             =  0x20,       ///< function completed; mail event occurred.
  111.   osEventTimeout          =  0x40,       ///< function completed; timeout occurred.
  112.   osErrorParameter        =  0x80,       ///< parameter error: a mandatory parameter was missing or specified an incorrect object.
  113.   osErrorResource         =  0x81,       ///< resource not available: a specified resource was not available.
  114.   osErrorTimeoutResource  =  0xC1,       ///< resource not available within given time: a specified resource was not available within the timeout period.
  115.   osErrorISR              =  0x82,       ///< not allowed in ISR context: the function cannot be called from interrupt service routines.
  116.   osErrorISRRecursive     =  0x83,       ///< function called multiple times from ISR with same object.
  117.   osErrorPriority         =  0x84,       ///< system cannot determine priority or thread has illegal priority.
  118.   osErrorNoMemory         =  0x85,       ///< system is out of memory: it was impossible to allocate or reserve memory for the operation.
  119.   osErrorValue            =  0x86,       ///< value of a parameter is out of range.
  120.   osErrorOS               =  0xFF,       ///< unspecified RTOS error: run-time error but no other error message fits.
  121.   os_status_reserved      =  0x7FFFFFFF  ///< prevent from enum down-size compiler optimization.
  122. } osStatus;
  123.  
  124.  
  125. /// Timer type value for the timer definition.
  126. /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS.
  127. typedef enum  {
  128.   osTimerOnce             =     0,       ///< one-shot timer
  129.   osTimerPeriodic         =     1        ///< repeating timer
  130. } os_timer_type;
  131.  
  132. /// Entry point of a thread.
  133. /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS.
  134. typedef void (*os_pthread) (void const *argument);
  135.  
  136. /// Entry point of a timer call back function.
  137. /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS.
  138. typedef void (*os_ptimer) (void const *argument);
  139.  
  140. // >>> the following data type definitions may shall adapted towards a specific RTOS
  141.  
  142. /// Thread ID identifies the thread (pointer to a thread control block).
  143. /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS.
  144. typedef struct os_thread_cb *osThreadId;
  145.  
  146. /// Timer ID identifies the timer (pointer to a timer control block).
  147. /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS.
  148. typedef struct os_timer_cb *osTimerId;
  149.  
  150. /// Mutex ID identifies the mutex (pointer to a mutex control block).
  151. /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS.
  152. typedef struct os_mutex_cb *osMutexId;
  153.  
  154. /// Semaphore ID identifies the semaphore (pointer to a semaphore control block).
  155. /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS.
  156. typedef struct os_semaphore_cb *osSemaphoreId;
  157.  
  158. /// Pool ID identifies the memory pool (pointer to a memory pool control block).
  159. /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS.
  160. typedef struct os_pool_cb *osPoolId;
  161.  
  162. /// Message ID identifies the message queue (pointer to a message queue control block).
  163. /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS.
  164. typedef struct os_messageQ_cb *osMessageQId;
  165.  
  166. /// Mail ID identifies the mail queue (pointer to a mail queue control block).
  167. /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS.
  168. typedef struct os_mailQ_cb *osMailQId;
  169.  
  170.  
  171. /// Thread Definition structure contains startup information of a thread.
  172. /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS.
  173. typedef struct os_thread_def  {
  174.   os_pthread               pthread;    ///< start address of thread function
  175.   osPriority             tpriority;    ///< initial thread priority
  176.   uint32_t               instances;    ///< maximum number of instances of that thread function
  177.   uint32_t               stacksize;    ///< stack size requirements in bytes; 0 is default stack size
  178. } osThreadDef_t;
  179.  
  180. /// Timer Definition structure contains timer parameters.
  181. /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS.
  182. typedef struct os_timer_def  {
  183.   os_ptimer                 ptimer;    ///< start address of a timer function
  184. } osTimerDef_t;
  185.  
  186. /// Mutex Definition structure contains setup information for a mutex.
  187. /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS.
  188. typedef struct os_mutex_def  {
  189.   uint32_t                   dummy;    ///< dummy value.
  190. } osMutexDef_t;
  191.  
  192. /// Semaphore Definition structure contains setup information for a semaphore.
  193. /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS.
  194. typedef struct os_semaphore_def  {
  195.   uint32_t                   dummy;    ///< dummy value.
  196. } osSemaphoreDef_t;
  197.  
  198. /// Definition structure for memory block allocation.
  199. /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS.
  200. typedef struct os_pool_def  {
  201.   uint32_t                 pool_sz;    ///< number of items (elements) in the pool
  202.   uint32_t                 item_sz;    ///< size of an item
  203.   void                       *pool;    ///< pointer to memory for pool
  204. } osPoolDef_t;
  205.  
  206. /// Definition structure for message queue.
  207. /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS.
  208. typedef struct os_messageQ_def  {
  209.   uint32_t                queue_sz;    ///< number of elements in the queue
  210.   uint32_t                 item_sz;    ///< size of an item
  211.   void                       *pool;    ///< memory array for messages
  212. } osMessageQDef_t;
  213.  
  214. /// Definition structure for mail queue.
  215. /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS.
  216. typedef struct os_mailQ_def  {
  217.   uint32_t                queue_sz;    ///< number of elements in the queue
  218.   uint32_t                 item_sz;    ///< size of an item
  219.   void                       *pool;    ///< memory array for mail
  220. } osMailQDef_t;
  221.  
  222. /// Event structure contains detailed information about an event.
  223. /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS.
  224. ///       However the struct may be extended at the end.
  225. typedef struct  {
  226.   osStatus                 status;     ///< status code: event or error information
  227.   union  {
  228.     uint32_t                    v;     ///< message as 32-bit value
  229.     void                       *p;     ///< message or mail as void pointer
  230.     int32_t               signals;     ///< signal flags
  231.   } value;                             ///< event value
  232.   union  {
  233.     osMailQId             mail_id;     ///< mail id obtained by \ref osMailCreate
  234.     osMessageQId       message_id;     ///< message id obtained by \ref osMessageCreate
  235.   } def;                               ///< event definition
  236. } osEvent;
  237.  
  238.  
  239. //  ==== Kernel Control Functions ====
  240.  
  241. /// Initialize the RTOS Kernel for creating objects.
  242. /// \return status code that indicates the execution status of the function.
  243. /// \note MUST REMAIN UNCHANGED: \b osKernelInitialize shall be consistent in every CMSIS-RTOS.
  244. osStatus osKernelInitialize (void);
  245.  
  246. /// Start the RTOS Kernel.
  247. /// \return status code that indicates the execution status of the function.
  248. /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS.
  249. osStatus osKernelStart (void);
  250.  
  251. /// Check if the RTOS kernel is already started.
  252. /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS.
  253. /// \return 0 RTOS is not started, 1 RTOS is started.
  254. int32_t osKernelRunning(void);
  255.  
  256. #if (defined (osFeature_SysTick)  &&  (osFeature_SysTick != 0))     // System Timer available
  257.  
  258. /// Get the RTOS kernel system timer counter
  259. /// \note MUST REMAIN UNCHANGED: \b osKernelSysTick shall be consistent in every CMSIS-RTOS.
  260. /// \return RTOS kernel system timer as 32-bit value
  261. uint32_t osKernelSysTick (void);
  262.  
  263. /// The RTOS kernel system timer frequency in Hz
  264. /// \note Reflects the system timer setting and is typically defined in a configuration file.
  265. #define osKernelSysTickFrequency 100000000
  266.  
  267. /// Convert a microseconds value to a RTOS kernel system timer value.
  268. /// \param         microsec     time value in microseconds.
  269. /// \return time value normalized to the \ref osKernelSysTickFrequency
  270. #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
  271.  
  272. #endif    // System Timer available
  273.  
  274. //  ==== Thread Management ====
  275.  
  276. /// Create a Thread Definition with function, priority, and stack requirements.
  277. /// \param         name         name of the thread function.
  278. /// \param         priority     initial priority of the thread function.
  279. /// \param         instances    number of possible thread instances.
  280. /// \param         stacksz      stack size (in bytes) requirements for the thread function.
  281. /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the
  282. ///       macro body is implementation specific in every CMSIS-RTOS.
  283. #if defined (osObjectsExternal)  // object is external
  284. #define osThreadDef(name, priority, instances, stacksz)  \
  285. extern const osThreadDef_t os_thread_def_##name
  286. #else                            // define the object
  287. #define osThreadDef(name, priority, instances, stacksz)  \
  288. const osThreadDef_t os_thread_def_##name = \
  289. { (name), (priority), (instances), (stacksz)  }
  290. #endif
  291.  
  292. /// Access a Thread definition.
  293. /// \param         name          name of the thread definition object.
  294. /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the
  295. ///       macro body is implementation specific in every CMSIS-RTOS.
  296. #define osThread(name)  \
  297. &os_thread_def_##name
  298.  
  299. /// Create a thread and add it to Active Threads and set it to state READY.
  300. /// \param[in]     thread_def    thread definition referenced with \ref osThread.
  301. /// \param[in]     argument      pointer that is passed to the thread function as start argument.
  302. /// \return thread ID for reference by other functions or NULL in case of error.
  303. /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS.
  304. osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument);
  305.  
  306. /// Return the thread ID of the current running thread.
  307. /// \return thread ID for reference by other functions or NULL in case of error.
  308. /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS.
  309. osThreadId osThreadGetId (void);
  310.  
  311. /// Terminate execution of a thread and remove it from Active Threads.
  312. /// \param[in]     thread_id   thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
  313. /// \return status code that indicates the execution status of the function.
  314. /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS.
  315. osStatus osThreadTerminate (osThreadId thread_id);
  316.  
  317. /// Pass control to next thread that is in state \b READY.
  318. /// \return status code that indicates the execution status of the function.
  319. /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS.
  320. osStatus osThreadYield (void);
  321.  
  322. /// Change priority of an active thread.
  323. /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
  324. /// \param[in]     priority      new priority value for the thread function.
  325. /// \return status code that indicates the execution status of the function.
  326. /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS.
  327. osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
  328.  
  329. /// Get current priority of an active thread.
  330. /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
  331. /// \return current priority value of the thread function.
  332. /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS.
  333. osPriority osThreadGetPriority (osThreadId thread_id);
  334.  
  335.  
  336. //  ==== Generic Wait Functions ====
  337.  
  338. /// Wait for Timeout (Time Delay).
  339. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue "time delay" value
  340. /// \return status code that indicates the execution status of the function.
  341. osStatus osDelay (uint32_t millisec);
  342.  
  343. #if (defined (osFeature_Wait)  &&  (osFeature_Wait != 0))     // Generic Wait available
  344.  
  345. /// Wait for Signal, Message, Mail, or Timeout.
  346. /// \param[in] millisec          \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
  347. /// \return event that contains signal, message, or mail information or error code.
  348. /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS.
  349. osEvent osWait (uint32_t millisec);
  350.  
  351. #endif  // Generic Wait available
  352.  
  353.  
  354. //  ==== Timer Management Functions ====
  355. /// Define a Timer object.
  356. /// \param         name          name of the timer object.
  357. /// \param         function      name of the timer call back function.
  358. /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the
  359. ///       macro body is implementation specific in every CMSIS-RTOS.
  360. #if defined (osObjectsExternal)  // object is external
  361. #define osTimerDef(name, function)  \
  362. extern const osTimerDef_t os_timer_def_##name
  363. #else                            // define the object
  364. #define osTimerDef(name, function)  \
  365. const osTimerDef_t os_timer_def_##name = \
  366. { (function) }
  367. #endif
  368.  
  369. /// Access a Timer definition.
  370. /// \param         name          name of the timer object.
  371. /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the
  372. ///       macro body is implementation specific in every CMSIS-RTOS.
  373. #define osTimer(name) \
  374. &os_timer_def_##name
  375.  
  376. /// Create a timer.
  377. /// \param[in]     timer_def     timer object referenced with \ref osTimer.
  378. /// \param[in]     type          osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
  379. /// \param[in]     argument      argument to the timer call back function.
  380. /// \return timer ID for reference by other functions or NULL in case of error.
  381. /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS.
  382. osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument);
  383.  
  384. /// Start or restart a timer.
  385. /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
  386. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue "time delay" value of the timer.
  387. /// \return status code that indicates the execution status of the function.
  388. /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS.
  389. osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
  390.  
  391. /// Stop the timer.
  392. /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
  393. /// \return status code that indicates the execution status of the function.
  394. /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS.
  395. osStatus osTimerStop (osTimerId timer_id);
  396.  
  397. /// Delete a timer that was created by \ref osTimerCreate.
  398. /// \param[in]     timer_id      timer ID obtained by \ref osTimerCreate.
  399. /// \return status code that indicates the execution status of the function.
  400. /// \note MUST REMAIN UNCHANGED: \b osTimerDelete shall be consistent in every CMSIS-RTOS.
  401. osStatus osTimerDelete (osTimerId timer_id);
  402.  
  403.  
  404. //  ==== Signal Management ====
  405.  
  406. /// Set the specified Signal Flags of an active thread.
  407. /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
  408. /// \param[in]     signals       specifies the signal flags of the thread that should be set.
  409. /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
  410. /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS.
  411. int32_t osSignalSet (osThreadId thread_id, int32_t signals);
  412.  
  413. /// Clear the specified Signal Flags of an active thread.
  414. /// \param[in]     thread_id     thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
  415. /// \param[in]     signals       specifies the signal flags of the thread that shall be cleared.
  416. /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters or call from ISR.
  417. /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS.
  418. int32_t osSignalClear (osThreadId thread_id, int32_t signals);
  419.  
  420. /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread.
  421. /// \param[in]     signals       wait until all specified signal flags set or 0 for any single signal flag.
  422. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  423. /// \return event flag information or error code.
  424. /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS.
  425. osEvent osSignalWait (int32_t signals, uint32_t millisec);
  426.  
  427.  
  428. //  ==== Mutex Management ====
  429.  
  430. /// Define a Mutex.
  431. /// \param         name          name of the mutex object.
  432. /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the
  433. ///       macro body is implementation specific in every CMSIS-RTOS.
  434. #if defined (osObjectsExternal)  // object is external
  435. #define osMutexDef(name)  \
  436. extern const osMutexDef_t os_mutex_def_##name
  437. #else                            // define the object
  438. #define osMutexDef(name)  \
  439. const osMutexDef_t os_mutex_def_##name = { 0 }
  440. #endif
  441.  
  442. /// Access a Mutex definition.
  443. /// \param         name          name of the mutex object.
  444. /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the
  445. ///       macro body is implementation specific in every CMSIS-RTOS.
  446. #define osMutex(name)  \
  447. &os_mutex_def_##name
  448.  
  449. /// Create and Initialize a Mutex object.
  450. /// \param[in]     mutex_def     mutex definition referenced with \ref osMutex.
  451. /// \return mutex ID for reference by other functions or NULL in case of error.
  452. /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS.
  453. osMutexId osMutexCreate (const osMutexDef_t *mutex_def);
  454.  
  455. /// Wait until a Mutex becomes available.
  456. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
  457. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  458. /// \return status code that indicates the execution status of the function.
  459. /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS.
  460. osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
  461.  
  462. /// Release a Mutex that was obtained by \ref osMutexWait.
  463. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
  464. /// \return status code that indicates the execution status of the function.
  465. /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS.
  466. osStatus osMutexRelease (osMutexId mutex_id);
  467.  
  468. /// Delete a Mutex that was created by \ref osMutexCreate.
  469. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexCreate.
  470. /// \return status code that indicates the execution status of the function.
  471. /// \note MUST REMAIN UNCHANGED: \b osMutexDelete shall be consistent in every CMSIS-RTOS.
  472. osStatus osMutexDelete (osMutexId mutex_id);
  473.  
  474.  
  475. //  ==== Semaphore Management Functions ====
  476.  
  477. #if (defined (osFeature_Semaphore)  &&  (osFeature_Semaphore != 0))     // Semaphore available
  478.  
  479. /// Define a Semaphore object.
  480. /// \param         name          name of the semaphore object.
  481. /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the
  482. ///       macro body is implementation specific in every CMSIS-RTOS.
  483. #if defined (osObjectsExternal)  // object is external
  484. #define osSemaphoreDef(name)  \
  485. extern const osSemaphoreDef_t os_semaphore_def_##name
  486. #else                            // define the object
  487. #define osSemaphoreDef(name)  \
  488. const osSemaphoreDef_t os_semaphore_def_##name = { 0 }
  489. #endif
  490.  
  491. /// Access a Semaphore definition.
  492. /// \param         name          name of the semaphore object.
  493. /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the
  494. ///       macro body is implementation specific in every CMSIS-RTOS.
  495. #define osSemaphore(name)  \
  496. &os_semaphore_def_##name
  497.  
  498. /// Create and Initialize a Semaphore object used for managing resources.
  499. /// \param[in]     semaphore_def semaphore definition referenced with \ref osSemaphore.
  500. /// \param[in]     count         number of available resources.
  501. /// \return semaphore ID for reference by other functions or NULL in case of error.
  502. /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS.
  503. osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count);
  504.  
  505. /// Wait until a Semaphore token becomes available.
  506. /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
  507. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  508. /// \return number of available tokens, or -1 in case of incorrect parameters.
  509. /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS.
  510. int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
  511.  
  512. /// Release a Semaphore token.
  513. /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
  514. /// \return status code that indicates the execution status of the function.
  515. /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS.
  516. osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
  517.  
  518. /// Delete a Semaphore that was created by \ref osSemaphoreCreate.
  519. /// \param[in]     semaphore_id  semaphore object referenced with \ref osSemaphoreCreate.
  520. /// \return status code that indicates the execution status of the function.
  521. /// \note MUST REMAIN UNCHANGED: \b osSemaphoreDelete shall be consistent in every CMSIS-RTOS.
  522. osStatus osSemaphoreDelete (osSemaphoreId semaphore_id);
  523.  
  524. #endif     // Semaphore available
  525.  
  526.  
  527. //  ==== Memory Pool Management Functions ====
  528.  
  529. #if (defined (osFeature_Pool)  &&  (osFeature_Pool != 0))  // Memory Pool Management available
  530.  
  531. /// \brief Define a Memory Pool.
  532. /// \param         name          name of the memory pool.
  533. /// \param         no            maximum number of blocks (objects) in the memory pool.
  534. /// \param         type          data type of a single block (object).
  535. /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the
  536. ///       macro body is implementation specific in every CMSIS-RTOS.
  537. #if defined (osObjectsExternal)  // object is external
  538. #define osPoolDef(name, no, type)   \
  539. extern const osPoolDef_t os_pool_def_##name
  540. #else                            // define the object
  541. #define osPoolDef(name, no, type)   \
  542. const osPoolDef_t os_pool_def_##name = \
  543. { (no), sizeof(type), NULL }
  544. #endif
  545.  
  546. /// \brief Access a Memory Pool definition.
  547. /// \param         name          name of the memory pool
  548. /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the
  549. ///       macro body is implementation specific in every CMSIS-RTOS.
  550. #define osPool(name) \
  551. &os_pool_def_##name
  552.  
  553. /// Create and Initialize a memory pool.
  554. /// \param[in]     pool_def      memory pool definition referenced with \ref osPool.
  555. /// \return memory pool ID for reference by other functions or NULL in case of error.
  556. /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS.
  557. osPoolId osPoolCreate (const osPoolDef_t *pool_def);
  558.  
  559. /// Allocate a memory block from a memory pool.
  560. /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
  561. /// \return address of the allocated memory block or NULL in case of no memory available.
  562. /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS.
  563. void *osPoolAlloc (osPoolId pool_id);
  564.  
  565. /// Allocate a memory block from a memory pool and set memory block to zero.
  566. /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
  567. /// \return address of the allocated memory block or NULL in case of no memory available.
  568. /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS.
  569. void *osPoolCAlloc (osPoolId pool_id);
  570.  
  571. /// Return an allocated memory block back to a specific memory pool.
  572. /// \param[in]     pool_id       memory pool ID obtain referenced with \ref osPoolCreate.
  573. /// \param[in]     block         address of the allocated memory block that is returned to the memory pool.
  574. /// \return status code that indicates the execution status of the function.
  575. /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS.
  576. osStatus osPoolFree (osPoolId pool_id, void *block);
  577.  
  578. #endif   // Memory Pool Management available
  579.  
  580.  
  581. //  ==== Message Queue Management Functions ====
  582.  
  583. #if (defined (osFeature_MessageQ)  &&  (osFeature_MessageQ != 0))     // Message Queues available
  584.  
  585. /// \brief Create a Message Queue Definition.
  586. /// \param         name          name of the queue.
  587. /// \param         queue_sz      maximum number of messages in the queue.
  588. /// \param         type          data type of a single message element (for debugger).
  589. /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the
  590. ///       macro body is implementation specific in every CMSIS-RTOS.
  591. #if defined (osObjectsExternal)  // object is external
  592. #define osMessageQDef(name, queue_sz, type)   \
  593. extern const osMessageQDef_t os_messageQ_def_##name
  594. #else                            // define the object
  595. #define osMessageQDef(name, queue_sz, type)   \
  596. const osMessageQDef_t os_messageQ_def_##name = \
  597. { (queue_sz), sizeof (type)  }
  598. #endif
  599.  
  600. /// \brief Access a Message Queue Definition.
  601. /// \param         name          name of the queue
  602. /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the
  603. ///       macro body is implementation specific in every CMSIS-RTOS.
  604. #define osMessageQ(name) \
  605. &os_messageQ_def_##name
  606.  
  607. /// Create and Initialize a Message Queue.
  608. /// \param[in]     queue_def     queue definition referenced with \ref osMessageQ.
  609. /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
  610. /// \return message queue ID for reference by other functions or NULL in case of error.
  611. /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS.
  612. osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id);
  613.  
  614. /// Put a Message to a Queue.
  615. /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
  616. /// \param[in]     info          message information.
  617. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  618. /// \return status code that indicates the execution status of the function.
  619. /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS.
  620. osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
  621.  
  622. /// Get a Message or Wait for a Message from a Queue.
  623. /// \param[in]     queue_id      message queue ID obtained with \ref osMessageCreate.
  624. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  625. /// \return event information that includes status code.
  626. /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS.
  627. osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
  628.  
  629. #endif     // Message Queues available
  630.  
  631.  
  632. //  ==== Mail Queue Management Functions ====
  633.  
  634. #if (defined (osFeature_MailQ)  &&  (osFeature_MailQ != 0))     // Mail Queues available
  635.  
  636. /// \brief Create a Mail Queue Definition.
  637. /// \param         name          name of the queue
  638. /// \param         queue_sz      maximum number of messages in queue
  639. /// \param         type          data type of a single message element
  640. /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the
  641. ///       macro body is implementation specific in every CMSIS-RTOS.
  642. #if defined (osObjectsExternal)  // object is external
  643. #define osMailQDef(name, queue_sz, type) \
  644. extern const osMailQDef_t os_mailQ_def_##name
  645. #else                            // define the object
  646. #define osMailQDef(name, queue_sz, type) \
  647. const osMailQDef_t os_mailQ_def_##name =  \
  648. { (queue_sz), sizeof (type) }
  649. #endif
  650.  
  651. /// \brief Access a Mail Queue Definition.
  652. /// \param         name          name of the queue
  653. /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the
  654. ///       macro body is implementation specific in every CMSIS-RTOS.
  655. #define osMailQ(name)  \
  656. &os_mailQ_def_##name
  657.  
  658. /// Create and Initialize mail queue.
  659. /// \param[in]     queue_def     reference to the mail queue definition obtain with \ref osMailQ
  660. /// \param[in]     thread_id     thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
  661. /// \return mail queue ID for reference by other functions or NULL in case of error.
  662. /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS.
  663. osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id);
  664.  
  665. /// Allocate a memory block from a mail.
  666. /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
  667. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
  668. /// \return pointer to memory block that can be filled with mail or NULL in case of error.
  669. /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS.
  670. void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
  671.  
  672. /// Allocate a memory block from a mail and set memory block to zero.
  673. /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
  674. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
  675. /// \return pointer to memory block that can be filled with mail or NULL in case of error.
  676. /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS.
  677. void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
  678.  
  679. /// Put a mail to a queue.
  680. /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
  681. /// \param[in]     mail          memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc.
  682. /// \return status code that indicates the execution status of the function.
  683. /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS.
  684. osStatus osMailPut (osMailQId queue_id, void *mail);
  685.  
  686. /// Get a mail from a queue.
  687. /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
  688. /// \param[in]     millisec      \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
  689. /// \return event that contains mail information or error code.
  690. /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS.
  691. osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
  692.  
  693. /// Free a memory block from a mail.
  694. /// \param[in]     queue_id      mail queue ID obtained with \ref osMailCreate.
  695. /// \param[in]     mail          pointer to the memory block that was obtained with \ref osMailGet.
  696. /// \return status code that indicates the execution status of the function.
  697. /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS.
  698. osStatus osMailFree (osMailQId queue_id, void *mail);
  699.  
  700. #endif  // Mail Queues available
  701.  
  702.  
  703. #ifdef  __cplusplus
  704. }
  705. #endif
  706.  
  707. #endif  // _CMSIS_OS_H
  708.