Subversion Repositories testOled

Rev

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