semphr.h 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844
  1. /*
  2. FreeRTOS V8.2.3 - Copyright (C) 2015 Real Time Engineers Ltd.
  3. All rights reserved
  4. VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
  5. This file is part of the FreeRTOS distribution.
  6. FreeRTOS is free software; you can redistribute it and/or modify it under
  7. the terms of the GNU General Public License (version 2) as published by the
  8. Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.
  9. ***************************************************************************
  10. >>! NOTE: The modification to the GPL is included to allow you to !<<
  11. >>! distribute a combined work that includes FreeRTOS without being !<<
  12. >>! obliged to provide the source code for proprietary components !<<
  13. >>! outside of the FreeRTOS kernel. !<<
  14. ***************************************************************************
  15. FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
  16. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  17. FOR A PARTICULAR PURPOSE. Full license text is available on the following
  18. link: http://www.freertos.org/a00114.html
  19. ***************************************************************************
  20. * *
  21. * FreeRTOS provides completely free yet professionally developed, *
  22. * robust, strictly quality controlled, supported, and cross *
  23. * platform software that is more than just the market leader, it *
  24. * is the industry's de facto standard. *
  25. * *
  26. * Help yourself get started quickly while simultaneously helping *
  27. * to support the FreeRTOS project by purchasing a FreeRTOS *
  28. * tutorial book, reference manual, or both: *
  29. * http://www.FreeRTOS.org/Documentation *
  30. * *
  31. ***************************************************************************
  32. http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading
  33. the FAQ page "My application does not run, what could be wrong?". Have you
  34. defined configASSERT()?
  35. http://www.FreeRTOS.org/support - In return for receiving this top quality
  36. embedded software for free we request you assist our global community by
  37. participating in the support forum.
  38. http://www.FreeRTOS.org/training - Investing in training allows your team to
  39. be as productive as possible as early as possible. Now you can receive
  40. FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
  41. Ltd, and the world's leading authority on the world's leading RTOS.
  42. http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
  43. including FreeRTOS+Trace - an indispensable productivity tool, a DOS
  44. compatible FAT file system, and our tiny thread aware UDP/IP stack.
  45. http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
  46. Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
  47. http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
  48. Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS
  49. licenses offer ticketed support, indemnification and commercial middleware.
  50. http://www.SafeRTOS.com - High Integrity Systems also provide a safety
  51. engineered and independently SIL3 certified version for use in safety and
  52. mission critical applications that require provable dependability.
  53. 1 tab == 4 spaces!
  54. */
  55. #ifndef SEMAPHORE_H
  56. #define SEMAPHORE_H
  57. #ifndef INC_FREERTOS_H
  58. #error "include FreeRTOS.h" must appear in source files before "include semphr.h"
  59. #endif
  60. #include "queue.h"
  61. typedef QueueHandle_t SemaphoreHandle_t;
  62. #define semBINARY_SEMAPHORE_QUEUE_LENGTH ( ( uint8_t ) 1U )
  63. #define semSEMAPHORE_QUEUE_ITEM_LENGTH ( ( uint8_t ) 0U )
  64. #define semGIVE_BLOCK_TIME ( ( TickType_t ) 0U )
  65. /**
  66. * semphr. h
  67. * <pre>vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore )</pre>
  68. *
  69. * This old vSemaphoreCreateBinary() macro is now deprecated in favour of the
  70. * xSemaphoreCreateBinary() function. Note that binary semaphores created using
  71. * the vSemaphoreCreateBinary() macro are created in a state such that the
  72. * first call to 'take' the semaphore would pass, whereas binary semaphores
  73. * created using xSemaphoreCreateBinary() are created in a state such that the
  74. * the semaphore must first be 'given' before it can be 'taken'.
  75. *
  76. * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.
  77. * The queue length is 1 as this is a binary semaphore. The data size is 0
  78. * as we don't want to actually store any data - we just want to know if the
  79. * queue is empty or full.
  80. *
  81. * This type of semaphore can be used for pure synchronisation between tasks or
  82. * between an interrupt and a task. The semaphore need not be given back once
  83. * obtained, so one task/interrupt can continuously 'give' the semaphore while
  84. * another continuously 'takes' the semaphore. For this reason this type of
  85. * semaphore does not use a priority inheritance mechanism. For an alternative
  86. * that does use priority inheritance see xSemaphoreCreateMutex().
  87. *
  88. * @param xSemaphore Handle to the created semaphore. Should be of type SemaphoreHandle_t.
  89. *
  90. * Example usage:
  91. <pre>
  92. SemaphoreHandle_t xSemaphore = NULL;
  93. void vATask( void * pvParameters )
  94. {
  95. // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().
  96. // This is a macro so pass the variable in directly.
  97. vSemaphoreCreateBinary( xSemaphore );
  98. if( xSemaphore != NULL )
  99. {
  100. // The semaphore was created successfully.
  101. // The semaphore can now be used.
  102. }
  103. }
  104. </pre>
  105. * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary
  106. * \ingroup Semaphores
  107. */
  108. #define vSemaphoreCreateBinary( xSemaphore ) \
  109. { \
  110. ( xSemaphore ) = xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \
  111. if( ( xSemaphore ) != NULL ) \
  112. { \
  113. ( void ) xSemaphoreGive( ( xSemaphore ) ); \
  114. } \
  115. }
  116. /**
  117. * semphr. h
  118. * <pre>SemaphoreHandle_t xSemaphoreCreateBinary( void )</pre>
  119. *
  120. * The old vSemaphoreCreateBinary() macro is now deprecated in favour of this
  121. * xSemaphoreCreateBinary() function. Note that binary semaphores created using
  122. * the vSemaphoreCreateBinary() macro are created in a state such that the
  123. * first call to 'take' the semaphore would pass, whereas binary semaphores
  124. * created using xSemaphoreCreateBinary() are created in a state such that the
  125. * the semaphore must first be 'given' before it can be 'taken'.
  126. *
  127. * Function that creates a semaphore by using the existing queue mechanism.
  128. * The queue length is 1 as this is a binary semaphore. The data size is 0
  129. * as nothing is actually stored - all that is important is whether the queue is
  130. * empty or full (the binary semaphore is available or not).
  131. *
  132. * This type of semaphore can be used for pure synchronisation between tasks or
  133. * between an interrupt and a task. The semaphore need not be given back once
  134. * obtained, so one task/interrupt can continuously 'give' the semaphore while
  135. * another continuously 'takes' the semaphore. For this reason this type of
  136. * semaphore does not use a priority inheritance mechanism. For an alternative
  137. * that does use priority inheritance see xSemaphoreCreateMutex().
  138. *
  139. * @return Handle to the created semaphore.
  140. *
  141. * Example usage:
  142. <pre>
  143. SemaphoreHandle_t xSemaphore = NULL;
  144. void vATask( void * pvParameters )
  145. {
  146. // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().
  147. // This is a macro so pass the variable in directly.
  148. xSemaphore = xSemaphoreCreateBinary();
  149. if( xSemaphore != NULL )
  150. {
  151. // The semaphore was created successfully.
  152. // The semaphore can now be used.
  153. }
  154. }
  155. </pre>
  156. * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary
  157. * \ingroup Semaphores
  158. */
  159. #define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )
  160. /**
  161. * semphr. h
  162. * <pre>xSemaphoreTake(
  163. * SemaphoreHandle_t xSemaphore,
  164. * TickType_t xBlockTime
  165. * )</pre>
  166. *
  167. * <i>Macro</i> to obtain a semaphore. The semaphore must have previously been
  168. * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or
  169. * xSemaphoreCreateCounting().
  170. *
  171. * @param xSemaphore A handle to the semaphore being taken - obtained when
  172. * the semaphore was created.
  173. *
  174. * @param xBlockTime The time in ticks to wait for the semaphore to become
  175. * available. The macro portTICK_PERIOD_MS can be used to convert this to a
  176. * real time. A block time of zero can be used to poll the semaphore. A block
  177. * time of portMAX_DELAY can be used to block indefinitely (provided
  178. * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).
  179. *
  180. * @return pdTRUE if the semaphore was obtained. pdFALSE
  181. * if xBlockTime expired without the semaphore becoming available.
  182. *
  183. * Example usage:
  184. <pre>
  185. SemaphoreHandle_t xSemaphore = NULL;
  186. // A task that creates a semaphore.
  187. void vATask( void * pvParameters )
  188. {
  189. // Create the semaphore to guard a shared resource.
  190. vSemaphoreCreateBinary( xSemaphore );
  191. }
  192. // A task that uses the semaphore.
  193. void vAnotherTask( void * pvParameters )
  194. {
  195. // ... Do other things.
  196. if( xSemaphore != NULL )
  197. {
  198. // See if we can obtain the semaphore. If the semaphore is not available
  199. // wait 10 ticks to see if it becomes free.
  200. if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
  201. {
  202. // We were able to obtain the semaphore and can now access the
  203. // shared resource.
  204. // ...
  205. // We have finished accessing the shared resource. Release the
  206. // semaphore.
  207. xSemaphoreGive( xSemaphore );
  208. }
  209. else
  210. {
  211. // We could not obtain the semaphore and can therefore not access
  212. // the shared resource safely.
  213. }
  214. }
  215. }
  216. </pre>
  217. * \defgroup xSemaphoreTake xSemaphoreTake
  218. * \ingroup Semaphores
  219. */
  220. #define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueGenericReceive( ( QueueHandle_t ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )
  221. /**
  222. * semphr. h
  223. * xSemaphoreTakeRecursive(
  224. * SemaphoreHandle_t xMutex,
  225. * TickType_t xBlockTime
  226. * )
  227. *
  228. * <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore.
  229. * The mutex must have previously been created using a call to
  230. * xSemaphoreCreateRecursiveMutex();
  231. *
  232. * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this
  233. * macro to be available.
  234. *
  235. * This macro must not be used on mutexes created using xSemaphoreCreateMutex().
  236. *
  237. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  238. * doesn't become available again until the owner has called
  239. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  240. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  241. * not be available to any other task until it has also 'given' the mutex back
  242. * exactly five times.
  243. *
  244. * @param xMutex A handle to the mutex being obtained. This is the
  245. * handle returned by xSemaphoreCreateRecursiveMutex();
  246. *
  247. * @param xBlockTime The time in ticks to wait for the semaphore to become
  248. * available. The macro portTICK_PERIOD_MS can be used to convert this to a
  249. * real time. A block time of zero can be used to poll the semaphore. If
  250. * the task already owns the semaphore then xSemaphoreTakeRecursive() will
  251. * return immediately no matter what the value of xBlockTime.
  252. *
  253. * @return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime
  254. * expired without the semaphore becoming available.
  255. *
  256. * Example usage:
  257. <pre>
  258. SemaphoreHandle_t xMutex = NULL;
  259. // A task that creates a mutex.
  260. void vATask( void * pvParameters )
  261. {
  262. // Create the mutex to guard a shared resource.
  263. xMutex = xSemaphoreCreateRecursiveMutex();
  264. }
  265. // A task that uses the mutex.
  266. void vAnotherTask( void * pvParameters )
  267. {
  268. // ... Do other things.
  269. if( xMutex != NULL )
  270. {
  271. // See if we can obtain the mutex. If the mutex is not available
  272. // wait 10 ticks to see if it becomes free.
  273. if( xSemaphoreTakeRecursive( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
  274. {
  275. // We were able to obtain the mutex and can now access the
  276. // shared resource.
  277. // ...
  278. // For some reason due to the nature of the code further calls to
  279. // xSemaphoreTakeRecursive() are made on the same mutex. In real
  280. // code these would not be just sequential calls as this would make
  281. // no sense. Instead the calls are likely to be buried inside
  282. // a more complex call structure.
  283. xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  284. xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  285. // The mutex has now been 'taken' three times, so will not be
  286. // available to another task until it has also been given back
  287. // three times. Again it is unlikely that real code would have
  288. // these calls sequentially, but instead buried in a more complex
  289. // call structure. This is just for illustrative purposes.
  290. xSemaphoreGiveRecursive( xMutex );
  291. xSemaphoreGiveRecursive( xMutex );
  292. xSemaphoreGiveRecursive( xMutex );
  293. // Now the mutex can be taken by other tasks.
  294. }
  295. else
  296. {
  297. // We could not obtain the mutex and can therefore not access
  298. // the shared resource safely.
  299. }
  300. }
  301. }
  302. </pre>
  303. * \defgroup xSemaphoreTakeRecursive xSemaphoreTakeRecursive
  304. * \ingroup Semaphores
  305. */
  306. #define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )
  307. /*
  308. * xSemaphoreAltTake() is an alternative version of xSemaphoreTake().
  309. *
  310. * The source code that implements the alternative (Alt) API is much
  311. * simpler because it executes everything from within a critical section.
  312. * This is the approach taken by many other RTOSes, but FreeRTOS.org has the
  313. * preferred fully featured API too. The fully featured API has more
  314. * complex code that takes longer to execute, but makes much less use of
  315. * critical sections. Therefore the alternative API sacrifices interrupt
  316. * responsiveness to gain execution speed, whereas the fully featured API
  317. * sacrifices execution speed to ensure better interrupt responsiveness.
  318. */
  319. #define xSemaphoreAltTake( xSemaphore, xBlockTime ) xQueueAltGenericReceive( ( QueueHandle_t ) ( xSemaphore ), NULL, ( xBlockTime ), pdFALSE )
  320. /**
  321. * semphr. h
  322. * <pre>xSemaphoreGive( SemaphoreHandle_t xSemaphore )</pre>
  323. *
  324. * <i>Macro</i> to release a semaphore. The semaphore must have previously been
  325. * created with a call to vSemaphoreCreateBinary(), xSemaphoreCreateMutex() or
  326. * xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().
  327. *
  328. * This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for
  329. * an alternative which can be used from an ISR.
  330. *
  331. * This macro must also not be used on semaphores created using
  332. * xSemaphoreCreateRecursiveMutex().
  333. *
  334. * @param xSemaphore A handle to the semaphore being released. This is the
  335. * handle returned when the semaphore was created.
  336. *
  337. * @return pdTRUE if the semaphore was released. pdFALSE if an error occurred.
  338. * Semaphores are implemented using queues. An error can occur if there is
  339. * no space on the queue to post a message - indicating that the
  340. * semaphore was not first obtained correctly.
  341. *
  342. * Example usage:
  343. <pre>
  344. SemaphoreHandle_t xSemaphore = NULL;
  345. void vATask( void * pvParameters )
  346. {
  347. // Create the semaphore to guard a shared resource.
  348. vSemaphoreCreateBinary( xSemaphore );
  349. if( xSemaphore != NULL )
  350. {
  351. if( xSemaphoreGive( xSemaphore ) != pdTRUE )
  352. {
  353. // We would expect this call to fail because we cannot give
  354. // a semaphore without first "taking" it!
  355. }
  356. // Obtain the semaphore - don't block if the semaphore is not
  357. // immediately available.
  358. if( xSemaphoreTake( xSemaphore, ( TickType_t ) 0 ) )
  359. {
  360. // We now have the semaphore and can access the shared resource.
  361. // ...
  362. // We have finished accessing the shared resource so can free the
  363. // semaphore.
  364. if( xSemaphoreGive( xSemaphore ) != pdTRUE )
  365. {
  366. // We would not expect this call to fail because we must have
  367. // obtained the semaphore to get here.
  368. }
  369. }
  370. }
  371. }
  372. </pre>
  373. * \defgroup xSemaphoreGive xSemaphoreGive
  374. * \ingroup Semaphores
  375. */
  376. #define xSemaphoreGive( xSemaphore ) xQueueGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )
  377. /**
  378. * semphr. h
  379. * <pre>xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex )</pre>
  380. *
  381. * <i>Macro</i> to recursively release, or 'give', a mutex type semaphore.
  382. * The mutex must have previously been created using a call to
  383. * xSemaphoreCreateRecursiveMutex();
  384. *
  385. * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this
  386. * macro to be available.
  387. *
  388. * This macro must not be used on mutexes created using xSemaphoreCreateMutex().
  389. *
  390. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  391. * doesn't become available again until the owner has called
  392. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  393. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  394. * not be available to any other task until it has also 'given' the mutex back
  395. * exactly five times.
  396. *
  397. * @param xMutex A handle to the mutex being released, or 'given'. This is the
  398. * handle returned by xSemaphoreCreateMutex();
  399. *
  400. * @return pdTRUE if the semaphore was given.
  401. *
  402. * Example usage:
  403. <pre>
  404. SemaphoreHandle_t xMutex = NULL;
  405. // A task that creates a mutex.
  406. void vATask( void * pvParameters )
  407. {
  408. // Create the mutex to guard a shared resource.
  409. xMutex = xSemaphoreCreateRecursiveMutex();
  410. }
  411. // A task that uses the mutex.
  412. void vAnotherTask( void * pvParameters )
  413. {
  414. // ... Do other things.
  415. if( xMutex != NULL )
  416. {
  417. // See if we can obtain the mutex. If the mutex is not available
  418. // wait 10 ticks to see if it becomes free.
  419. if( xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ) == pdTRUE )
  420. {
  421. // We were able to obtain the mutex and can now access the
  422. // shared resource.
  423. // ...
  424. // For some reason due to the nature of the code further calls to
  425. // xSemaphoreTakeRecursive() are made on the same mutex. In real
  426. // code these would not be just sequential calls as this would make
  427. // no sense. Instead the calls are likely to be buried inside
  428. // a more complex call structure.
  429. xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  430. xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  431. // The mutex has now been 'taken' three times, so will not be
  432. // available to another task until it has also been given back
  433. // three times. Again it is unlikely that real code would have
  434. // these calls sequentially, it would be more likely that the calls
  435. // to xSemaphoreGiveRecursive() would be called as a call stack
  436. // unwound. This is just for demonstrative purposes.
  437. xSemaphoreGiveRecursive( xMutex );
  438. xSemaphoreGiveRecursive( xMutex );
  439. xSemaphoreGiveRecursive( xMutex );
  440. // Now the mutex can be taken by other tasks.
  441. }
  442. else
  443. {
  444. // We could not obtain the mutex and can therefore not access
  445. // the shared resource safely.
  446. }
  447. }
  448. }
  449. </pre>
  450. * \defgroup xSemaphoreGiveRecursive xSemaphoreGiveRecursive
  451. * \ingroup Semaphores
  452. */
  453. #define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) )
  454. /*
  455. * xSemaphoreAltGive() is an alternative version of xSemaphoreGive().
  456. *
  457. * The source code that implements the alternative (Alt) API is much
  458. * simpler because it executes everything from within a critical section.
  459. * This is the approach taken by many other RTOSes, but FreeRTOS.org has the
  460. * preferred fully featured API too. The fully featured API has more
  461. * complex code that takes longer to execute, but makes much less use of
  462. * critical sections. Therefore the alternative API sacrifices interrupt
  463. * responsiveness to gain execution speed, whereas the fully featured API
  464. * sacrifices execution speed to ensure better interrupt responsiveness.
  465. */
  466. #define xSemaphoreAltGive( xSemaphore ) xQueueAltGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )
  467. /**
  468. * semphr. h
  469. * <pre>
  470. xSemaphoreGiveFromISR(
  471. SemaphoreHandle_t xSemaphore,
  472. BaseType_t *pxHigherPriorityTaskWoken
  473. )</pre>
  474. *
  475. * <i>Macro</i> to release a semaphore. The semaphore must have previously been
  476. * created with a call to vSemaphoreCreateBinary() or xSemaphoreCreateCounting().
  477. *
  478. * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())
  479. * must not be used with this macro.
  480. *
  481. * This macro can be used from an ISR.
  482. *
  483. * @param xSemaphore A handle to the semaphore being released. This is the
  484. * handle returned when the semaphore was created.
  485. *
  486. * @param pxHigherPriorityTaskWoken xSemaphoreGiveFromISR() will set
  487. * *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task
  488. * to unblock, and the unblocked task has a priority higher than the currently
  489. * running task. If xSemaphoreGiveFromISR() sets this value to pdTRUE then
  490. * a context switch should be requested before the interrupt is exited.
  491. *
  492. * @return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.
  493. *
  494. * Example usage:
  495. <pre>
  496. \#define LONG_TIME 0xffff
  497. \#define TICKS_TO_WAIT 10
  498. SemaphoreHandle_t xSemaphore = NULL;
  499. // Repetitive task.
  500. void vATask( void * pvParameters )
  501. {
  502. for( ;; )
  503. {
  504. // We want this task to run every 10 ticks of a timer. The semaphore
  505. // was created before this task was started.
  506. // Block waiting for the semaphore to become available.
  507. if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )
  508. {
  509. // It is time to execute.
  510. // ...
  511. // We have finished our task. Return to the top of the loop where
  512. // we will block on the semaphore until it is time to execute
  513. // again. Note when using the semaphore for synchronisation with an
  514. // ISR in this manner there is no need to 'give' the semaphore back.
  515. }
  516. }
  517. }
  518. // Timer ISR
  519. void vTimerISR( void * pvParameters )
  520. {
  521. static uint8_t ucLocalTickCount = 0;
  522. static BaseType_t xHigherPriorityTaskWoken;
  523. // A timer tick has occurred.
  524. // ... Do other time functions.
  525. // Is it time for vATask () to run?
  526. xHigherPriorityTaskWoken = pdFALSE;
  527. ucLocalTickCount++;
  528. if( ucLocalTickCount >= TICKS_TO_WAIT )
  529. {
  530. // Unblock the task by releasing the semaphore.
  531. xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );
  532. // Reset the count so we release the semaphore again in 10 ticks time.
  533. ucLocalTickCount = 0;
  534. }
  535. if( xHigherPriorityTaskWoken != pdFALSE )
  536. {
  537. // We can force a context switch here. Context switching from an
  538. // ISR uses port specific syntax. Check the demo task for your port
  539. // to find the syntax required.
  540. }
  541. }
  542. </pre>
  543. * \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR
  544. * \ingroup Semaphores
  545. */
  546. #define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) )
  547. /**
  548. * semphr. h
  549. * <pre>
  550. xSemaphoreTakeFromISR(
  551. SemaphoreHandle_t xSemaphore,
  552. BaseType_t *pxHigherPriorityTaskWoken
  553. )</pre>
  554. *
  555. * <i>Macro</i> to take a semaphore from an ISR. The semaphore must have
  556. * previously been created with a call to vSemaphoreCreateBinary() or
  557. * xSemaphoreCreateCounting().
  558. *
  559. * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())
  560. * must not be used with this macro.
  561. *
  562. * This macro can be used from an ISR, however taking a semaphore from an ISR
  563. * is not a common operation. It is likely to only be useful when taking a
  564. * counting semaphore when an interrupt is obtaining an object from a resource
  565. * pool (when the semaphore count indicates the number of resources available).
  566. *
  567. * @param xSemaphore A handle to the semaphore being taken. This is the
  568. * handle returned when the semaphore was created.
  569. *
  570. * @param pxHigherPriorityTaskWoken xSemaphoreTakeFromISR() will set
  571. * *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task
  572. * to unblock, and the unblocked task has a priority higher than the currently
  573. * running task. If xSemaphoreTakeFromISR() sets this value to pdTRUE then
  574. * a context switch should be requested before the interrupt is exited.
  575. *
  576. * @return pdTRUE if the semaphore was successfully taken, otherwise
  577. * pdFALSE
  578. */
  579. #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( QueueHandle_t ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )
  580. /**
  581. * semphr. h
  582. * <pre>SemaphoreHandle_t xSemaphoreCreateMutex( void )</pre>
  583. *
  584. * <i>Macro</i> that implements a mutex semaphore by using the existing queue
  585. * mechanism.
  586. *
  587. * Mutexes created using this macro can be accessed using the xSemaphoreTake()
  588. * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and
  589. * xSemaphoreGiveRecursive() macros should not be used.
  590. *
  591. * This type of semaphore uses a priority inheritance mechanism so a task
  592. * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
  593. * semaphore it is no longer required.
  594. *
  595. * Mutex type semaphores cannot be used from within interrupt service routines.
  596. *
  597. * See vSemaphoreCreateBinary() for an alternative implementation that can be
  598. * used for pure synchronisation (where one task or interrupt always 'gives' the
  599. * semaphore and another always 'takes' the semaphore) and from within interrupt
  600. * service routines.
  601. *
  602. * @return xSemaphore Handle to the created mutex semaphore. Should be of type
  603. * SemaphoreHandle_t.
  604. *
  605. * Example usage:
  606. <pre>
  607. SemaphoreHandle_t xSemaphore;
  608. void vATask( void * pvParameters )
  609. {
  610. // Semaphore cannot be used before a call to xSemaphoreCreateMutex().
  611. // This is a macro so pass the variable in directly.
  612. xSemaphore = xSemaphoreCreateMutex();
  613. if( xSemaphore != NULL )
  614. {
  615. // The semaphore was created successfully.
  616. // The semaphore can now be used.
  617. }
  618. }
  619. </pre>
  620. * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex
  621. * \ingroup Semaphores
  622. */
  623. #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )
  624. /**
  625. * semphr. h
  626. * <pre>SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void )</pre>
  627. *
  628. * <i>Macro</i> that implements a recursive mutex by using the existing queue
  629. * mechanism.
  630. *
  631. * Mutexes created using this macro can be accessed using the
  632. * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The
  633. * xSemaphoreTake() and xSemaphoreGive() macros should not be used.
  634. *
  635. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  636. * doesn't become available again until the owner has called
  637. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  638. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  639. * not be available to any other task until it has also 'given' the mutex back
  640. * exactly five times.
  641. *
  642. * This type of semaphore uses a priority inheritance mechanism so a task
  643. * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
  644. * semaphore it is no longer required.
  645. *
  646. * Mutex type semaphores cannot be used from within interrupt service routines.
  647. *
  648. * See vSemaphoreCreateBinary() for an alternative implementation that can be
  649. * used for pure synchronisation (where one task or interrupt always 'gives' the
  650. * semaphore and another always 'takes' the semaphore) and from within interrupt
  651. * service routines.
  652. *
  653. * @return xSemaphore Handle to the created mutex semaphore. Should be of type
  654. * SemaphoreHandle_t.
  655. *
  656. * Example usage:
  657. <pre>
  658. SemaphoreHandle_t xSemaphore;
  659. void vATask( void * pvParameters )
  660. {
  661. // Semaphore cannot be used before a call to xSemaphoreCreateMutex().
  662. // This is a macro so pass the variable in directly.
  663. xSemaphore = xSemaphoreCreateRecursiveMutex();
  664. if( xSemaphore != NULL )
  665. {
  666. // The semaphore was created successfully.
  667. // The semaphore can now be used.
  668. }
  669. }
  670. </pre>
  671. * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex
  672. * \ingroup Semaphores
  673. */
  674. #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )
  675. /**
  676. * semphr. h
  677. * <pre>SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount )</pre>
  678. *
  679. * <i>Macro</i> that creates a counting semaphore by using the existing
  680. * queue mechanism.
  681. *
  682. * Counting semaphores are typically used for two things:
  683. *
  684. * 1) Counting events.
  685. *
  686. * In this usage scenario an event handler will 'give' a semaphore each time
  687. * an event occurs (incrementing the semaphore count value), and a handler
  688. * task will 'take' a semaphore each time it processes an event
  689. * (decrementing the semaphore count value). The count value is therefore
  690. * the difference between the number of events that have occurred and the
  691. * number that have been processed. In this case it is desirable for the
  692. * initial count value to be zero.
  693. *
  694. * 2) Resource management.
  695. *
  696. * In this usage scenario the count value indicates the number of resources
  697. * available. To obtain control of a resource a task must first obtain a
  698. * semaphore - decrementing the semaphore count value. When the count value
  699. * reaches zero there are no free resources. When a task finishes with the
  700. * resource it 'gives' the semaphore back - incrementing the semaphore count
  701. * value. In this case it is desirable for the initial count value to be
  702. * equal to the maximum count value, indicating that all resources are free.
  703. *
  704. * @param uxMaxCount The maximum count value that can be reached. When the
  705. * semaphore reaches this value it can no longer be 'given'.
  706. *
  707. * @param uxInitialCount The count value assigned to the semaphore when it is
  708. * created.
  709. *
  710. * @return Handle to the created semaphore. Null if the semaphore could not be
  711. * created.
  712. *
  713. * Example usage:
  714. <pre>
  715. SemaphoreHandle_t xSemaphore;
  716. void vATask( void * pvParameters )
  717. {
  718. SemaphoreHandle_t xSemaphore = NULL;
  719. // Semaphore cannot be used before a call to xSemaphoreCreateCounting().
  720. // The max value to which the semaphore can count should be 10, and the
  721. // initial value assigned to the count should be 0.
  722. xSemaphore = xSemaphoreCreateCounting( 10, 0 );
  723. if( xSemaphore != NULL )
  724. {
  725. // The semaphore was created successfully.
  726. // The semaphore can now be used.
  727. }
  728. }
  729. </pre>
  730. * \defgroup xSemaphoreCreateCounting xSemaphoreCreateCounting
  731. * \ingroup Semaphores
  732. */
  733. #define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )
  734. /**
  735. * semphr. h
  736. * <pre>void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );</pre>
  737. *
  738. * Delete a semaphore. This function must be used with care. For example,
  739. * do not delete a mutex type semaphore if the mutex is held by a task.
  740. *
  741. * @param xSemaphore A handle to the semaphore to be deleted.
  742. *
  743. * \defgroup vSemaphoreDelete vSemaphoreDelete
  744. * \ingroup Semaphores
  745. */
  746. #define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( QueueHandle_t ) ( xSemaphore ) )
  747. /**
  748. * semphr.h
  749. * <pre>TaskHandle_t xSemaphoreGetMutexHolder( SemaphoreHandle_t xMutex );</pre>
  750. *
  751. * If xMutex is indeed a mutex type semaphore, return the current mutex holder.
  752. * If xMutex is not a mutex type semaphore, or the mutex is available (not held
  753. * by a task), return NULL.
  754. *
  755. * Note: This is a good way of determining if the calling task is the mutex
  756. * holder, but not a good way of determining the identity of the mutex holder as
  757. * the holder may change between the function exiting and the returned value
  758. * being tested.
  759. */
  760. #define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )
  761. #endif /* SEMAPHORE_H */