Subversion Repositories dashGPS

Rev

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

  1. /*
  2.  * Copyright (c) 2013-2018 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:        18. June 2018
  21.  * $Revision:    V2.1.3
  22.  *
  23.  * Project:      CMSIS-RTOS2 API
  24.  * Title:        cmsis_os2.h header file
  25.  *
  26.  * Version 2.1.3
  27.  *    Additional functions allowed to be called from Interrupt Service Routines:
  28.  *    - osThreadGetId
  29.  * Version 2.1.2
  30.  *    Additional functions allowed to be called from Interrupt Service Routines:
  31.  *    - osKernelGetInfo, osKernelGetState
  32.  * Version 2.1.1
  33.  *    Additional functions allowed to be called from Interrupt Service Routines:
  34.  *    - osKernelGetTickCount, osKernelGetTickFreq
  35.  *    Changed Kernel Tick type to uint32_t:
  36.  *    - updated: osKernelGetTickCount, osDelayUntil
  37.  * Version 2.1.0
  38.  *    Support for critical and uncritical sections (nesting safe):
  39.  *    - updated: osKernelLock, osKernelUnlock
  40.  *    - added: osKernelRestoreLock
  41.  *    Updated Thread and Event Flags:
  42.  *    - changed flags parameter and return type from int32_t to uint32_t
  43.  * Version 2.0.0
  44.  *    Initial Release
  45.  *---------------------------------------------------------------------------*/
  46.  
  47. #ifndef CMSIS_OS2_H_
  48. #define CMSIS_OS2_H_
  49.  
  50. #ifndef __NO_RETURN
  51. #if   defined(__CC_ARM)
  52. #define __NO_RETURN __declspec(noreturn)
  53. #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
  54. #define __NO_RETURN __attribute__((__noreturn__))
  55. #elif defined(__GNUC__)
  56. #define __NO_RETURN __attribute__((__noreturn__))
  57. #elif defined(__ICCARM__)
  58. #define __NO_RETURN __noreturn
  59. #else
  60. #define __NO_RETURN
  61. #endif
  62. #endif
  63.  
  64. #include <stdint.h>
  65. #include <stddef.h>
  66.  
  67. #ifdef  __cplusplus
  68. extern "C"
  69. {
  70. #endif
  71.  
  72.  
  73. //  ==== Enumerations, structures, defines ====
  74.  
  75. /// Version information.
  76. typedef struct {
  77.   uint32_t                       api;   ///< API version (major.minor.rev: mmnnnrrrr dec).
  78.   uint32_t                    kernel;   ///< Kernel version (major.minor.rev: mmnnnrrrr dec).
  79. } osVersion_t;
  80.  
  81. /// Kernel state.
  82. typedef enum {
  83.   osKernelInactive        =  0,         ///< Inactive.
  84.   osKernelReady           =  1,         ///< Ready.
  85.   osKernelRunning         =  2,         ///< Running.
  86.   osKernelLocked          =  3,         ///< Locked.
  87.   osKernelSuspended       =  4,         ///< Suspended.
  88.   osKernelError           = -1,         ///< Error.
  89.   osKernelReserved        = 0x7FFFFFFFU ///< Prevents enum down-size compiler optimization.
  90. } osKernelState_t;
  91.  
  92. /// Thread state.
  93. typedef enum {
  94.   osThreadInactive        =  0,         ///< Inactive.
  95.   osThreadReady           =  1,         ///< Ready.
  96.   osThreadRunning         =  2,         ///< Running.
  97.   osThreadBlocked         =  3,         ///< Blocked.
  98.   osThreadTerminated      =  4,         ///< Terminated.
  99.   osThreadError           = -1,         ///< Error.
  100.   osThreadReserved        = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
  101. } osThreadState_t;
  102.  
  103. /// Priority values.
  104. typedef enum {
  105.   osPriorityNone          =  0,         ///< No priority (not initialized).
  106.   osPriorityIdle          =  1,         ///< Reserved for Idle thread.
  107.   osPriorityLow           =  8,         ///< Priority: low
  108.   osPriorityLow1          =  8+1,       ///< Priority: low + 1
  109.   osPriorityLow2          =  8+2,       ///< Priority: low + 2
  110.   osPriorityLow3          =  8+3,       ///< Priority: low + 3
  111.   osPriorityLow4          =  8+4,       ///< Priority: low + 4
  112.   osPriorityLow5          =  8+5,       ///< Priority: low + 5
  113.   osPriorityLow6          =  8+6,       ///< Priority: low + 6
  114.   osPriorityLow7          =  8+7,       ///< Priority: low + 7
  115.   osPriorityBelowNormal   = 16,         ///< Priority: below normal
  116.   osPriorityBelowNormal1  = 16+1,       ///< Priority: below normal + 1
  117.   osPriorityBelowNormal2  = 16+2,       ///< Priority: below normal + 2
  118.   osPriorityBelowNormal3  = 16+3,       ///< Priority: below normal + 3
  119.   osPriorityBelowNormal4  = 16+4,       ///< Priority: below normal + 4
  120.   osPriorityBelowNormal5  = 16+5,       ///< Priority: below normal + 5
  121.   osPriorityBelowNormal6  = 16+6,       ///< Priority: below normal + 6
  122.   osPriorityBelowNormal7  = 16+7,       ///< Priority: below normal + 7
  123.   osPriorityNormal        = 24,         ///< Priority: normal
  124.   osPriorityNormal1       = 24+1,       ///< Priority: normal + 1
  125.   osPriorityNormal2       = 24+2,       ///< Priority: normal + 2
  126.   osPriorityNormal3       = 24+3,       ///< Priority: normal + 3
  127.   osPriorityNormal4       = 24+4,       ///< Priority: normal + 4
  128.   osPriorityNormal5       = 24+5,       ///< Priority: normal + 5
  129.   osPriorityNormal6       = 24+6,       ///< Priority: normal + 6
  130.   osPriorityNormal7       = 24+7,       ///< Priority: normal + 7
  131.   osPriorityAboveNormal   = 32,         ///< Priority: above normal
  132.   osPriorityAboveNormal1  = 32+1,       ///< Priority: above normal + 1
  133.   osPriorityAboveNormal2  = 32+2,       ///< Priority: above normal + 2
  134.   osPriorityAboveNormal3  = 32+3,       ///< Priority: above normal + 3
  135.   osPriorityAboveNormal4  = 32+4,       ///< Priority: above normal + 4
  136.   osPriorityAboveNormal5  = 32+5,       ///< Priority: above normal + 5
  137.   osPriorityAboveNormal6  = 32+6,       ///< Priority: above normal + 6
  138.   osPriorityAboveNormal7  = 32+7,       ///< Priority: above normal + 7
  139.   osPriorityHigh          = 40,         ///< Priority: high
  140.   osPriorityHigh1         = 40+1,       ///< Priority: high + 1
  141.   osPriorityHigh2         = 40+2,       ///< Priority: high + 2
  142.   osPriorityHigh3         = 40+3,       ///< Priority: high + 3
  143.   osPriorityHigh4         = 40+4,       ///< Priority: high + 4
  144.   osPriorityHigh5         = 40+5,       ///< Priority: high + 5
  145.   osPriorityHigh6         = 40+6,       ///< Priority: high + 6
  146.   osPriorityHigh7         = 40+7,       ///< Priority: high + 7
  147.   osPriorityRealtime      = 48,         ///< Priority: realtime
  148.   osPriorityRealtime1     = 48+1,       ///< Priority: realtime + 1
  149.   osPriorityRealtime2     = 48+2,       ///< Priority: realtime + 2
  150.   osPriorityRealtime3     = 48+3,       ///< Priority: realtime + 3
  151.   osPriorityRealtime4     = 48+4,       ///< Priority: realtime + 4
  152.   osPriorityRealtime5     = 48+5,       ///< Priority: realtime + 5
  153.   osPriorityRealtime6     = 48+6,       ///< Priority: realtime + 6
  154.   osPriorityRealtime7     = 48+7,       ///< Priority: realtime + 7
  155.   osPriorityISR           = 56,         ///< Reserved for ISR deferred thread.
  156.   osPriorityError         = -1,         ///< System cannot determine priority or illegal priority.
  157.   osPriorityReserved      = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
  158. } osPriority_t;
  159.  
  160. /// Entry point of a thread.
  161. typedef void (*osThreadFunc_t) (void *argument);
  162.  
  163. /// Timer callback function.
  164. typedef void (*osTimerFunc_t) (void *argument);
  165.  
  166. /// Timer type.
  167. typedef enum {
  168.   osTimerOnce               = 0,          ///< One-shot timer.
  169.   osTimerPeriodic           = 1           ///< Repeating timer.
  170. } osTimerType_t;
  171.  
  172. // Timeout value.
  173. #define osWaitForever         0xFFFFFFFFU ///< Wait forever timeout value.
  174.  
  175. // Flags options (\ref osThreadFlagsWait and \ref osEventFlagsWait).
  176. #define osFlagsWaitAny        0x00000000U ///< Wait for any flag (default).
  177. #define osFlagsWaitAll        0x00000001U ///< Wait for all flags.
  178. #define osFlagsNoClear        0x00000002U ///< Do not clear flags which have been specified to wait for.
  179.  
  180. // Flags errors (returned by osThreadFlagsXxxx and osEventFlagsXxxx).
  181. #define osFlagsError          0x80000000U ///< Error indicator.
  182. #define osFlagsErrorUnknown   0xFFFFFFFFU ///< osError (-1).
  183. #define osFlagsErrorTimeout   0xFFFFFFFEU ///< osErrorTimeout (-2).
  184. #define osFlagsErrorResource  0xFFFFFFFDU ///< osErrorResource (-3).
  185. #define osFlagsErrorParameter 0xFFFFFFFCU ///< osErrorParameter (-4).
  186. #define osFlagsErrorISR       0xFFFFFFFAU ///< osErrorISR (-6).
  187.  
  188. // Thread attributes (attr_bits in \ref osThreadAttr_t).
  189. #define osThreadDetached      0x00000000U ///< Thread created in detached mode (default)
  190. #define osThreadJoinable      0x00000001U ///< Thread created in joinable mode
  191.  
  192. // Mutex attributes (attr_bits in \ref osMutexAttr_t).
  193. #define osMutexRecursive      0x00000001U ///< Recursive mutex.
  194. #define osMutexPrioInherit    0x00000002U ///< Priority inherit protocol.
  195. #define osMutexRobust         0x00000008U ///< Robust mutex.
  196.  
  197. /// Status code values returned by CMSIS-RTOS functions.
  198. typedef enum {
  199.   osOK                      =  0,         ///< Operation completed successfully.
  200.   osError                   = -1,         ///< Unspecified RTOS error: run-time error but no other error message fits.
  201.   osErrorTimeout            = -2,         ///< Operation not completed within the timeout period.
  202.   osErrorResource           = -3,         ///< Resource not available.
  203.   osErrorParameter          = -4,         ///< Parameter error.
  204.   osErrorNoMemory           = -5,         ///< System is out of memory: it was impossible to allocate or reserve memory for the operation.
  205.   osErrorISR                = -6,         ///< Not allowed in ISR context: the function cannot be called from interrupt service routines.
  206.   osStatusReserved          = 0x7FFFFFFF  ///< Prevents enum down-size compiler optimization.
  207. } osStatus_t;
  208.  
  209.  
  210. /// \details Thread ID identifies the thread.
  211. typedef void *osThreadId_t;
  212.  
  213. /// \details Timer ID identifies the timer.
  214. typedef void *osTimerId_t;
  215.  
  216. /// \details Event Flags ID identifies the event flags.
  217. typedef void *osEventFlagsId_t;
  218.  
  219. /// \details Mutex ID identifies the mutex.
  220. typedef void *osMutexId_t;
  221.  
  222. /// \details Semaphore ID identifies the semaphore.
  223. typedef void *osSemaphoreId_t;
  224.  
  225. /// \details Memory Pool ID identifies the memory pool.
  226. typedef void *osMemoryPoolId_t;
  227.  
  228. /// \details Message Queue ID identifies the message queue.
  229. typedef void *osMessageQueueId_t;
  230.  
  231.  
  232. #ifndef TZ_MODULEID_T
  233. #define TZ_MODULEID_T
  234. /// \details Data type that identifies secure software modules called by a process.
  235. typedef uint32_t TZ_ModuleId_t;
  236. #endif
  237.  
  238.  
  239. /// Attributes structure for thread.
  240. typedef struct {
  241.   const char                   *name;   ///< name of the thread
  242.   uint32_t                 attr_bits;   ///< attribute bits
  243.   void                      *cb_mem;    ///< memory for control block
  244.   uint32_t                   cb_size;   ///< size of provided memory for control block
  245.   void                   *stack_mem;    ///< memory for stack
  246.   uint32_t                stack_size;   ///< size of stack
  247.   osPriority_t              priority;   ///< initial thread priority (default: osPriorityNormal)
  248.   TZ_ModuleId_t            tz_module;   ///< TrustZone module identifier
  249.   uint32_t                  reserved;   ///< reserved (must be 0)
  250. } osThreadAttr_t;
  251.  
  252. /// Attributes structure for timer.
  253. typedef struct {
  254.   const char                   *name;   ///< name of the timer
  255.   uint32_t                 attr_bits;   ///< attribute bits
  256.   void                      *cb_mem;    ///< memory for control block
  257.   uint32_t                   cb_size;   ///< size of provided memory for control block
  258. } osTimerAttr_t;
  259.  
  260. /// Attributes structure for event flags.
  261. typedef struct {
  262.   const char                   *name;   ///< name of the event flags
  263.   uint32_t                 attr_bits;   ///< attribute bits
  264.   void                      *cb_mem;    ///< memory for control block
  265.   uint32_t                   cb_size;   ///< size of provided memory for control block
  266. } osEventFlagsAttr_t;
  267.  
  268. /// Attributes structure for mutex.
  269. typedef struct {
  270.   const char                   *name;   ///< name of the mutex
  271.   uint32_t                 attr_bits;   ///< attribute bits
  272.   void                      *cb_mem;    ///< memory for control block
  273.   uint32_t                   cb_size;   ///< size of provided memory for control block
  274. } osMutexAttr_t;
  275.  
  276. /// Attributes structure for semaphore.
  277. typedef struct {
  278.   const char                   *name;   ///< name of the semaphore
  279.   uint32_t                 attr_bits;   ///< attribute bits
  280.   void                      *cb_mem;    ///< memory for control block
  281.   uint32_t                   cb_size;   ///< size of provided memory for control block
  282. } osSemaphoreAttr_t;
  283.  
  284. /// Attributes structure for memory pool.
  285. typedef struct {
  286.   const char                   *name;   ///< name of the memory pool
  287.   uint32_t                 attr_bits;   ///< attribute bits
  288.   void                      *cb_mem;    ///< memory for control block
  289.   uint32_t                   cb_size;   ///< size of provided memory for control block
  290.   void                      *mp_mem;    ///< memory for data storage
  291.   uint32_t                   mp_size;   ///< size of provided memory for data storage
  292. } osMemoryPoolAttr_t;
  293.  
  294. /// Attributes structure for message queue.
  295. typedef struct {
  296.   const char                   *name;   ///< name of the message queue
  297.   uint32_t                 attr_bits;   ///< attribute bits
  298.   void                      *cb_mem;    ///< memory for control block
  299.   uint32_t                   cb_size;   ///< size of provided memory for control block
  300.   void                      *mq_mem;    ///< memory for data storage
  301.   uint32_t                   mq_size;   ///< size of provided memory for data storage
  302. } osMessageQueueAttr_t;
  303.  
  304.  
  305. //  ==== Kernel Management Functions ====
  306.  
  307. /// Initialize the RTOS Kernel.
  308. /// \return status code that indicates the execution status of the function.
  309. osStatus_t osKernelInitialize (void);
  310.  
  311. ///  Get RTOS Kernel Information.
  312. /// \param[out]    version       pointer to buffer for retrieving version information.
  313. /// \param[out]    id_buf        pointer to buffer for retrieving kernel identification string.
  314. /// \param[in]     id_size       size of buffer for kernel identification string.
  315. /// \return status code that indicates the execution status of the function.
  316. osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size);
  317.  
  318. /// Get the current RTOS Kernel state.
  319. /// \return current RTOS Kernel state.
  320. osKernelState_t osKernelGetState (void);
  321.  
  322. /// Start the RTOS Kernel scheduler.
  323. /// \return status code that indicates the execution status of the function.
  324. osStatus_t osKernelStart (void);
  325.  
  326. /// Lock the RTOS Kernel scheduler.
  327. /// \return previous lock state (1 - locked, 0 - not locked, error code if negative).
  328. int32_t osKernelLock (void);
  329.  
  330. /// Unlock the RTOS Kernel scheduler.
  331. /// \return previous lock state (1 - locked, 0 - not locked, error code if negative).
  332. int32_t osKernelUnlock (void);
  333.  
  334. /// Restore the RTOS Kernel scheduler lock state.
  335. /// \param[in]     lock          lock state obtained by \ref osKernelLock or \ref osKernelUnlock.
  336. /// \return new lock state (1 - locked, 0 - not locked, error code if negative).
  337. int32_t osKernelRestoreLock (int32_t lock);
  338.  
  339. /// Suspend the RTOS Kernel scheduler.
  340. /// \return time in ticks, for how long the system can sleep or power-down.
  341. uint32_t osKernelSuspend (void);
  342.  
  343. /// Resume the RTOS Kernel scheduler.
  344. /// \param[in]     sleep_ticks   time in ticks for how long the system was in sleep or power-down mode.
  345. void osKernelResume (uint32_t sleep_ticks);
  346.  
  347. /// Get the RTOS kernel tick count.
  348. /// \return RTOS kernel current tick count.
  349. uint32_t osKernelGetTickCount (void);
  350.  
  351. /// Get the RTOS kernel tick frequency.
  352. /// \return frequency of the kernel tick in hertz, i.e. kernel ticks per second.
  353. uint32_t osKernelGetTickFreq (void);
  354.  
  355. /// Get the RTOS kernel system timer count.
  356. /// \return RTOS kernel current system timer count as 32-bit value.
  357. uint32_t osKernelGetSysTimerCount (void);
  358.  
  359. /// Get the RTOS kernel system timer frequency.
  360. /// \return frequency of the system timer in hertz, i.e. timer ticks per second.
  361. uint32_t osKernelGetSysTimerFreq (void);
  362.  
  363.  
  364. //  ==== Thread Management Functions ====
  365.  
  366. /// Create a thread and add it to Active Threads.
  367. /// \param[in]     func          thread function.
  368. /// \param[in]     argument      pointer that is passed to the thread function as start argument.
  369. /// \param[in]     attr          thread attributes; NULL: default values.
  370. /// \return thread ID for reference by other functions or NULL in case of error.
  371. osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);
  372.  
  373. /// Get name of a thread.
  374. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  375. /// \return name as null-terminated string.
  376. const char *osThreadGetName (osThreadId_t thread_id);
  377.  
  378. /// Return the thread ID of the current running thread.
  379. /// \return thread ID for reference by other functions or NULL in case of error.
  380. osThreadId_t osThreadGetId (void);
  381.  
  382. /// Get current thread state of a thread.
  383. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  384. /// \return current thread state of the specified thread.
  385. osThreadState_t osThreadGetState (osThreadId_t thread_id);
  386.  
  387. /// Get stack size of a thread.
  388. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  389. /// \return stack size in bytes.
  390. uint32_t osThreadGetStackSize (osThreadId_t thread_id);
  391.  
  392. /// Get available stack space of a thread based on stack watermark recording during execution.
  393. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  394. /// \return remaining stack space in bytes.
  395. uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
  396.  
  397. /// Change priority of a thread.
  398. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  399. /// \param[in]     priority      new priority value for the thread function.
  400. /// \return status code that indicates the execution status of the function.
  401. osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority);
  402.  
  403. /// Get current priority of a thread.
  404. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  405. /// \return current priority value of the specified thread.
  406. osPriority_t osThreadGetPriority (osThreadId_t thread_id);
  407.  
  408. /// Pass control to next thread that is in state \b READY.
  409. /// \return status code that indicates the execution status of the function.
  410. osStatus_t osThreadYield (void);
  411.  
  412. /// Suspend execution of a thread.
  413. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  414. /// \return status code that indicates the execution status of the function.
  415. osStatus_t osThreadSuspend (osThreadId_t thread_id);
  416.  
  417. /// Resume execution of a thread.
  418. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  419. /// \return status code that indicates the execution status of the function.
  420. osStatus_t osThreadResume (osThreadId_t thread_id);
  421.  
  422. /// Detach a thread (thread storage can be reclaimed when thread terminates).
  423. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  424. /// \return status code that indicates the execution status of the function.
  425. osStatus_t osThreadDetach (osThreadId_t thread_id);
  426.  
  427. /// Wait for specified thread to terminate.
  428. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  429. /// \return status code that indicates the execution status of the function.
  430. osStatus_t osThreadJoin (osThreadId_t thread_id);
  431.  
  432. /// Terminate execution of current running thread.
  433. __NO_RETURN void osThreadExit (void);
  434.  
  435. /// Terminate execution of a thread.
  436. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  437. /// \return status code that indicates the execution status of the function.
  438. osStatus_t osThreadTerminate (osThreadId_t thread_id);
  439.  
  440. /// Get number of active threads.
  441. /// \return number of active threads.
  442. uint32_t osThreadGetCount (void);
  443.  
  444. /// Enumerate active threads.
  445. /// \param[out]    thread_array  pointer to array for retrieving thread IDs.
  446. /// \param[in]     array_items   maximum number of items in array for retrieving thread IDs.
  447. /// \return number of enumerated threads.
  448. uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items);
  449.  
  450.  
  451. //  ==== Thread Flags Functions ====
  452.  
  453. /// Set the specified Thread Flags of a thread.
  454. /// \param[in]     thread_id     thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
  455. /// \param[in]     flags         specifies the flags of the thread that shall be set.
  456. /// \return thread flags after setting or error code if highest bit set.
  457. uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags);
  458.  
  459. /// Clear the specified Thread Flags of current running thread.
  460. /// \param[in]     flags         specifies the flags of the thread that shall be cleared.
  461. /// \return thread flags before clearing or error code if highest bit set.
  462. uint32_t osThreadFlagsClear (uint32_t flags);
  463.  
  464. /// Get the current Thread Flags of current running thread.
  465. /// \return current thread flags.
  466. uint32_t osThreadFlagsGet (void);
  467.  
  468. /// Wait for one or more Thread Flags of the current running thread to become signaled.
  469. /// \param[in]     flags         specifies the flags to wait for.
  470. /// \param[in]     options       specifies flags options (osFlagsXxxx).
  471. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  472. /// \return thread flags before clearing or error code if highest bit set.
  473. uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout);
  474.  
  475.  
  476. //  ==== Generic Wait Functions ====
  477.  
  478. /// Wait for Timeout (Time Delay).
  479. /// \param[in]     ticks         \ref CMSIS_RTOS_TimeOutValue "time ticks" value
  480. /// \return status code that indicates the execution status of the function.
  481. osStatus_t osDelay (uint32_t ticks);
  482.  
  483. /// Wait until specified time.
  484. /// \param[in]     ticks         absolute time in ticks
  485. /// \return status code that indicates the execution status of the function.
  486. osStatus_t osDelayUntil (uint32_t ticks);
  487.  
  488.  
  489. //  ==== Timer Management Functions ====
  490.  
  491. /// Create and Initialize a timer.
  492. /// \param[in]     func          function pointer to callback function.
  493. /// \param[in]     type          \ref osTimerOnce for one-shot or \ref osTimerPeriodic for periodic behavior.
  494. /// \param[in]     argument      argument to the timer callback function.
  495. /// \param[in]     attr          timer attributes; NULL: default values.
  496. /// \return timer ID for reference by other functions or NULL in case of error.
  497. osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr);
  498.  
  499. /// Get name of a timer.
  500. /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
  501. /// \return name as null-terminated string.
  502. const char *osTimerGetName (osTimerId_t timer_id);
  503.  
  504. /// Start or restart a timer.
  505. /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
  506. /// \param[in]     ticks         \ref CMSIS_RTOS_TimeOutValue "time ticks" value of the timer.
  507. /// \return status code that indicates the execution status of the function.
  508. osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks);
  509.  
  510. /// Stop a timer.
  511. /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
  512. /// \return status code that indicates the execution status of the function.
  513. osStatus_t osTimerStop (osTimerId_t timer_id);
  514.  
  515. /// Check if a timer is running.
  516. /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
  517. /// \return 0 not running, 1 running.
  518. uint32_t osTimerIsRunning (osTimerId_t timer_id);
  519.  
  520. /// Delete a timer.
  521. /// \param[in]     timer_id      timer ID obtained by \ref osTimerNew.
  522. /// \return status code that indicates the execution status of the function.
  523. osStatus_t osTimerDelete (osTimerId_t timer_id);
  524.  
  525.  
  526. //  ==== Event Flags Management Functions ====
  527.  
  528. /// Create and Initialize an Event Flags object.
  529. /// \param[in]     attr          event flags attributes; NULL: default values.
  530. /// \return event flags ID for reference by other functions or NULL in case of error.
  531. osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr);
  532.  
  533. /// Get name of an Event Flags object.
  534. /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
  535. /// \return name as null-terminated string.
  536. const char *osEventFlagsGetName (osEventFlagsId_t ef_id);
  537.  
  538. /// Set the specified Event Flags.
  539. /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
  540. /// \param[in]     flags         specifies the flags that shall be set.
  541. /// \return event flags after setting or error code if highest bit set.
  542. uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags);
  543.  
  544. /// Clear the specified Event Flags.
  545. /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
  546. /// \param[in]     flags         specifies the flags that shall be cleared.
  547. /// \return event flags before clearing or error code if highest bit set.
  548. uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags);
  549.  
  550. /// Get the current Event Flags.
  551. /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
  552. /// \return current event flags.
  553. uint32_t osEventFlagsGet (osEventFlagsId_t ef_id);
  554.  
  555. /// Wait for one or more Event Flags to become signaled.
  556. /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
  557. /// \param[in]     flags         specifies the flags to wait for.
  558. /// \param[in]     options       specifies flags options (osFlagsXxxx).
  559. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  560. /// \return event flags before clearing or error code if highest bit set.
  561. uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout);
  562.  
  563. /// Delete an Event Flags object.
  564. /// \param[in]     ef_id         event flags ID obtained by \ref osEventFlagsNew.
  565. /// \return status code that indicates the execution status of the function.
  566. osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id);
  567.  
  568.  
  569. //  ==== Mutex Management Functions ====
  570.  
  571. /// Create and Initialize a Mutex object.
  572. /// \param[in]     attr          mutex attributes; NULL: default values.
  573. /// \return mutex ID for reference by other functions or NULL in case of error.
  574. osMutexId_t osMutexNew (const osMutexAttr_t *attr);
  575.  
  576. /// Get name of a Mutex object.
  577. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
  578. /// \return name as null-terminated string.
  579. const char *osMutexGetName (osMutexId_t mutex_id);
  580.  
  581. /// Acquire a Mutex or timeout if it is locked.
  582. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
  583. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  584. /// \return status code that indicates the execution status of the function.
  585. osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout);
  586.  
  587. /// Release a Mutex that was acquired by \ref osMutexAcquire.
  588. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
  589. /// \return status code that indicates the execution status of the function.
  590. osStatus_t osMutexRelease (osMutexId_t mutex_id);
  591.  
  592. /// Get Thread which owns a Mutex object.
  593. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
  594. /// \return thread ID of owner thread or NULL when mutex was not acquired.
  595. osThreadId_t osMutexGetOwner (osMutexId_t mutex_id);
  596.  
  597. /// Delete a Mutex object.
  598. /// \param[in]     mutex_id      mutex ID obtained by \ref osMutexNew.
  599. /// \return status code that indicates the execution status of the function.
  600. osStatus_t osMutexDelete (osMutexId_t mutex_id);
  601.  
  602.  
  603. //  ==== Semaphore Management Functions ====
  604.  
  605. /// Create and Initialize a Semaphore object.
  606. /// \param[in]     max_count     maximum number of available tokens.
  607. /// \param[in]     initial_count initial number of available tokens.
  608. /// \param[in]     attr          semaphore attributes; NULL: default values.
  609. /// \return semaphore ID for reference by other functions or NULL in case of error.
  610. osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr);
  611.  
  612. /// Get name of a Semaphore object.
  613. /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
  614. /// \return name as null-terminated string.
  615. const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id);
  616.  
  617. /// Acquire a Semaphore token or timeout if no tokens are available.
  618. /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
  619. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  620. /// \return status code that indicates the execution status of the function.
  621. osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout);
  622.  
  623. /// Release a Semaphore token up to the initial maximum count.
  624. /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
  625. /// \return status code that indicates the execution status of the function.
  626. osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id);
  627.  
  628. /// Get current Semaphore token count.
  629. /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
  630. /// \return number of tokens available.
  631. uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id);
  632.  
  633. /// Delete a Semaphore object.
  634. /// \param[in]     semaphore_id  semaphore ID obtained by \ref osSemaphoreNew.
  635. /// \return status code that indicates the execution status of the function.
  636. osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id);
  637.  
  638.  
  639. //  ==== Memory Pool Management Functions ====
  640.  
  641. /// Create and Initialize a Memory Pool object.
  642. /// \param[in]     block_count   maximum number of memory blocks in memory pool.
  643. /// \param[in]     block_size    memory block size in bytes.
  644. /// \param[in]     attr          memory pool attributes; NULL: default values.
  645. /// \return memory pool ID for reference by other functions or NULL in case of error.
  646. osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr);
  647.  
  648. /// Get name of a Memory Pool object.
  649. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  650. /// \return name as null-terminated string.
  651. const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id);
  652.  
  653. /// Allocate a memory block from a Memory Pool.
  654. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  655. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  656. /// \return address of the allocated memory block or NULL in case of no memory is available.
  657. void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout);
  658.  
  659. /// Return an allocated memory block back to a Memory Pool.
  660. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  661. /// \param[in]     block         address of the allocated memory block to be returned to the memory pool.
  662. /// \return status code that indicates the execution status of the function.
  663. osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block);
  664.  
  665. /// Get maximum number of memory blocks in a Memory Pool.
  666. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  667. /// \return maximum number of memory blocks.
  668. uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id);
  669.  
  670. /// Get memory block size in a Memory Pool.
  671. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  672. /// \return memory block size in bytes.
  673. uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id);
  674.  
  675. /// Get number of memory blocks used in a Memory Pool.
  676. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  677. /// \return number of memory blocks used.
  678. uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id);
  679.  
  680. /// Get number of memory blocks available in a Memory Pool.
  681. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  682. /// \return number of memory blocks available.
  683. uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id);
  684.  
  685. /// Delete a Memory Pool object.
  686. /// \param[in]     mp_id         memory pool ID obtained by \ref osMemoryPoolNew.
  687. /// \return status code that indicates the execution status of the function.
  688. osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id);
  689.  
  690.  
  691. //  ==== Message Queue Management Functions ====
  692.  
  693. /// Create and Initialize a Message Queue object.
  694. /// \param[in]     msg_count     maximum number of messages in queue.
  695. /// \param[in]     msg_size      maximum message size in bytes.
  696. /// \param[in]     attr          message queue attributes; NULL: default values.
  697. /// \return message queue ID for reference by other functions or NULL in case of error.
  698. osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr);
  699.  
  700. /// Get name of a Message Queue object.
  701. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  702. /// \return name as null-terminated string.
  703. const char *osMessageQueueGetName (osMessageQueueId_t mq_id);
  704.  
  705. /// Put a Message into a Queue or timeout if Queue is full.
  706. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  707. /// \param[in]     msg_ptr       pointer to buffer with message to put into a queue.
  708. /// \param[in]     msg_prio      message priority.
  709. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  710. /// \return status code that indicates the execution status of the function.
  711. osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
  712.  
  713. /// Get a Message from a Queue or timeout if Queue is empty.
  714. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  715. /// \param[out]    msg_ptr       pointer to buffer for message to get from a queue.
  716. /// \param[out]    msg_prio      pointer to buffer for message priority or NULL.
  717. /// \param[in]     timeout       \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
  718. /// \return status code that indicates the execution status of the function.
  719. osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout);
  720.  
  721. /// Get maximum number of messages in a Message Queue.
  722. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  723. /// \return maximum number of messages.
  724. uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id);
  725.  
  726. /// Get maximum message size in a Memory Pool.
  727. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  728. /// \return maximum message size in bytes.
  729. uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id);
  730.  
  731. /// Get number of queued messages in a Message Queue.
  732. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  733. /// \return number of queued messages.
  734. uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id);
  735.  
  736. /// Get number of available slots for messages in a Message Queue.
  737. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  738. /// \return number of available slots for messages.
  739. uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id);
  740.  
  741. /// Reset a Message Queue to initial empty state.
  742. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  743. /// \return status code that indicates the execution status of the function.
  744. osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id);
  745.  
  746. /// Delete a Message Queue object.
  747. /// \param[in]     mq_id         message queue ID obtained by \ref osMessageQueueNew.
  748. /// \return status code that indicates the execution status of the function.
  749. osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id);
  750.  
  751.  
  752. #ifdef  __cplusplus
  753. }
  754. #endif
  755.  
  756. #endif  // CMSIS_OS2_H_
  757.