Subversion Repositories AFRtranscoder

Rev

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