semphr.h 47 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175
  1. /*
  2. * FreeRTOS Kernel V10.4.4
  3. * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  4. *
  5. * SPDX-License-Identifier: MIT
  6. *
  7. * Permission is hereby granted, free of charge, to any person obtaining a copy of
  8. * this software and associated documentation files (the "Software"), to deal in
  9. * the Software without restriction, including without limitation the rights to
  10. * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  11. * the Software, and to permit persons to whom the Software is furnished to do so,
  12. * subject to the following conditions:
  13. *
  14. * The above copyright notice and this permission notice shall be included in all
  15. * copies or substantial portions of the Software.
  16. *
  17. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  19. * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  20. * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  21. * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22. * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23. *
  24. * https://www.FreeRTOS.org
  25. * https://github.com/FreeRTOS
  26. *
  27. */
  28. #ifndef SEMAPHORE_H
  29. #define SEMAPHORE_H
  30. #ifndef INC_FREERTOS_H
  31. #error "include FreeRTOS.h" must appear in source files before "include semphr.h"
  32. #endif
  33. #include "queue.h"
  34. typedef QueueHandle_t SemaphoreHandle_t;
  35. #define semBINARY_SEMAPHORE_QUEUE_LENGTH ( ( uint8_t ) 1U )
  36. #define semSEMAPHORE_QUEUE_ITEM_LENGTH ( ( uint8_t ) 0U )
  37. #define semGIVE_BLOCK_TIME ( ( TickType_t ) 0U )
  38. /**
  39. * semphr. h
  40. * <pre>
  41. * vSemaphoreCreateBinary( SemaphoreHandle_t xSemaphore );
  42. * </pre>
  43. *
  44. * In many usage scenarios it is faster and more memory efficient to use a
  45. * direct to task notification in place of a binary semaphore!
  46. * https://www.FreeRTOS.org/RTOS-task-notifications.html
  47. *
  48. * This old vSemaphoreCreateBinary() macro is now deprecated in favour of the
  49. * xSemaphoreCreateBinary() function. Note that binary semaphores created using
  50. * the vSemaphoreCreateBinary() macro are created in a state such that the
  51. * first call to 'take' the semaphore would pass, whereas binary semaphores
  52. * created using xSemaphoreCreateBinary() are created in a state such that the
  53. * the semaphore must first be 'given' before it can be 'taken'.
  54. *
  55. * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.
  56. * The queue length is 1 as this is a binary semaphore. The data size is 0
  57. * as we don't want to actually store any data - we just want to know if the
  58. * queue is empty or full.
  59. *
  60. * This type of semaphore can be used for pure synchronisation between tasks or
  61. * between an interrupt and a task. The semaphore need not be given back once
  62. * obtained, so one task/interrupt can continuously 'give' the semaphore while
  63. * another continuously 'takes' the semaphore. For this reason this type of
  64. * semaphore does not use a priority inheritance mechanism. For an alternative
  65. * that does use priority inheritance see xSemaphoreCreateMutex().
  66. *
  67. * @param xSemaphore Handle to the created semaphore. Should be of type SemaphoreHandle_t.
  68. *
  69. * Example usage:
  70. * <pre>
  71. * SemaphoreHandle_t xSemaphore = NULL;
  72. *
  73. * void vATask( void * pvParameters )
  74. * {
  75. * // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().
  76. * // This is a macro so pass the variable in directly.
  77. * vSemaphoreCreateBinary( xSemaphore );
  78. *
  79. * if( xSemaphore != NULL )
  80. * {
  81. * // The semaphore was created successfully.
  82. * // The semaphore can now be used.
  83. * }
  84. * }
  85. * </pre>
  86. * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary
  87. * \ingroup Semaphores
  88. */
  89. #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
  90. #define vSemaphoreCreateBinary( xSemaphore ) \
  91. { \
  92. ( xSemaphore ) = xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE ); \
  93. if( ( xSemaphore ) != NULL ) \
  94. { \
  95. ( void ) xSemaphoreGive( ( xSemaphore ) ); \
  96. } \
  97. }
  98. #endif
  99. /**
  100. * semphr. h
  101. * <pre>
  102. * SemaphoreHandle_t xSemaphoreCreateBinary( void );
  103. * </pre>
  104. *
  105. * Creates a new binary semaphore instance, and returns a handle by which the
  106. * new semaphore can be referenced.
  107. *
  108. * In many usage scenarios it is faster and more memory efficient to use a
  109. * direct to task notification in place of a binary semaphore!
  110. * https://www.FreeRTOS.org/RTOS-task-notifications.html
  111. *
  112. * Internally, within the FreeRTOS implementation, binary semaphores use a block
  113. * of memory, in which the semaphore structure is stored. If a binary semaphore
  114. * is created using xSemaphoreCreateBinary() then the required memory is
  115. * automatically dynamically allocated inside the xSemaphoreCreateBinary()
  116. * function. (see https://www.FreeRTOS.org/a00111.html). If a binary semaphore
  117. * is created using xSemaphoreCreateBinaryStatic() then the application writer
  118. * must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a
  119. * binary semaphore to be created without using any dynamic memory allocation.
  120. *
  121. * The old vSemaphoreCreateBinary() macro is now deprecated in favour of this
  122. * xSemaphoreCreateBinary() function. Note that binary semaphores created using
  123. * the vSemaphoreCreateBinary() macro are created in a state such that the
  124. * first call to 'take' the semaphore would pass, whereas binary semaphores
  125. * created using xSemaphoreCreateBinary() are created in a state such that the
  126. * the semaphore must first be 'given' before it can be 'taken'.
  127. *
  128. * This type of semaphore can be used for pure synchronisation between tasks or
  129. * between an interrupt and a task. The semaphore need not be given back once
  130. * obtained, so one task/interrupt can continuously 'give' the semaphore while
  131. * another continuously 'takes' the semaphore. For this reason this type of
  132. * semaphore does not use a priority inheritance mechanism. For an alternative
  133. * that does use priority inheritance see xSemaphoreCreateMutex().
  134. *
  135. * @return Handle to the created semaphore, or NULL if the memory required to
  136. * hold the semaphore's data structures could not be allocated.
  137. *
  138. * Example usage:
  139. * <pre>
  140. * SemaphoreHandle_t xSemaphore = NULL;
  141. *
  142. * void vATask( void * pvParameters )
  143. * {
  144. * // Semaphore cannot be used before a call to xSemaphoreCreateBinary().
  145. * // This is a macro so pass the variable in directly.
  146. * xSemaphore = xSemaphoreCreateBinary();
  147. *
  148. * if( xSemaphore != NULL )
  149. * {
  150. * // The semaphore was created successfully.
  151. * // The semaphore can now be used.
  152. * }
  153. * }
  154. * </pre>
  155. * \defgroup xSemaphoreCreateBinary xSemaphoreCreateBinary
  156. * \ingroup Semaphores
  157. */
  158. #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
  159. #define xSemaphoreCreateBinary() xQueueGenericCreate( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_BINARY_SEMAPHORE )
  160. #endif
  161. /**
  162. * semphr. h
  163. * <pre>
  164. * SemaphoreHandle_t xSemaphoreCreateBinaryStatic( StaticSemaphore_t *pxSemaphoreBuffer );
  165. * </pre>
  166. *
  167. * Creates a new binary semaphore instance, and returns a handle by which the
  168. * new semaphore can be referenced.
  169. *
  170. * NOTE: In many usage scenarios it is faster and more memory efficient to use a
  171. * direct to task notification in place of a binary semaphore!
  172. * https://www.FreeRTOS.org/RTOS-task-notifications.html
  173. *
  174. * Internally, within the FreeRTOS implementation, binary semaphores use a block
  175. * of memory, in which the semaphore structure is stored. If a binary semaphore
  176. * is created using xSemaphoreCreateBinary() then the required memory is
  177. * automatically dynamically allocated inside the xSemaphoreCreateBinary()
  178. * function. (see https://www.FreeRTOS.org/a00111.html). If a binary semaphore
  179. * is created using xSemaphoreCreateBinaryStatic() then the application writer
  180. * must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a
  181. * binary semaphore to be created without using any dynamic memory allocation.
  182. *
  183. * This type of semaphore can be used for pure synchronisation between tasks or
  184. * between an interrupt and a task. The semaphore need not be given back once
  185. * obtained, so one task/interrupt can continuously 'give' the semaphore while
  186. * another continuously 'takes' the semaphore. For this reason this type of
  187. * semaphore does not use a priority inheritance mechanism. For an alternative
  188. * that does use priority inheritance see xSemaphoreCreateMutex().
  189. *
  190. * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t,
  191. * which will then be used to hold the semaphore's data structure, removing the
  192. * need for the memory to be allocated dynamically.
  193. *
  194. * @return If the semaphore is created then a handle to the created semaphore is
  195. * returned. If pxSemaphoreBuffer is NULL then NULL is returned.
  196. *
  197. * Example usage:
  198. * <pre>
  199. * SemaphoreHandle_t xSemaphore = NULL;
  200. * StaticSemaphore_t xSemaphoreBuffer;
  201. *
  202. * void vATask( void * pvParameters )
  203. * {
  204. * // Semaphore cannot be used before a call to xSemaphoreCreateBinary().
  205. * // The semaphore's data structures will be placed in the xSemaphoreBuffer
  206. * // variable, the address of which is passed into the function. The
  207. * // function's parameter is not NULL, so the function will not attempt any
  208. * // dynamic memory allocation, and therefore the function will not return
  209. * // return NULL.
  210. * xSemaphore = xSemaphoreCreateBinary( &xSemaphoreBuffer );
  211. *
  212. * // Rest of task code goes here.
  213. * }
  214. * </pre>
  215. * \defgroup xSemaphoreCreateBinaryStatic xSemaphoreCreateBinaryStatic
  216. * \ingroup Semaphores
  217. */
  218. #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
  219. #define xSemaphoreCreateBinaryStatic( pxStaticSemaphore ) xQueueGenericCreateStatic( ( UBaseType_t ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticSemaphore, queueQUEUE_TYPE_BINARY_SEMAPHORE )
  220. #endif /* configSUPPORT_STATIC_ALLOCATION */
  221. /**
  222. * semphr. h
  223. * <pre>
  224. * xSemaphoreTake(
  225. * SemaphoreHandle_t xSemaphore,
  226. * TickType_t xBlockTime
  227. * );
  228. * </pre>
  229. *
  230. * <i>Macro</i> to obtain a semaphore. The semaphore must have previously been
  231. * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or
  232. * xSemaphoreCreateCounting().
  233. *
  234. * @param xSemaphore A handle to the semaphore being taken - obtained when
  235. * the semaphore was created.
  236. *
  237. * @param xBlockTime The time in ticks to wait for the semaphore to become
  238. * available. The macro portTICK_PERIOD_MS can be used to convert this to a
  239. * real time. A block time of zero can be used to poll the semaphore. A block
  240. * time of portMAX_DELAY can be used to block indefinitely (provided
  241. * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h).
  242. *
  243. * @return pdTRUE if the semaphore was obtained. pdFALSE
  244. * if xBlockTime expired without the semaphore becoming available.
  245. *
  246. * Example usage:
  247. * <pre>
  248. * SemaphoreHandle_t xSemaphore = NULL;
  249. *
  250. * // A task that creates a semaphore.
  251. * void vATask( void * pvParameters )
  252. * {
  253. * // Create the semaphore to guard a shared resource.
  254. * xSemaphore = xSemaphoreCreateBinary();
  255. * }
  256. *
  257. * // A task that uses the semaphore.
  258. * void vAnotherTask( void * pvParameters )
  259. * {
  260. * // ... Do other things.
  261. *
  262. * if( xSemaphore != NULL )
  263. * {
  264. * // See if we can obtain the semaphore. If the semaphore is not available
  265. * // wait 10 ticks to see if it becomes free.
  266. * if( xSemaphoreTake( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
  267. * {
  268. * // We were able to obtain the semaphore and can now access the
  269. * // shared resource.
  270. *
  271. * // ...
  272. *
  273. * // We have finished accessing the shared resource. Release the
  274. * // semaphore.
  275. * xSemaphoreGive( xSemaphore );
  276. * }
  277. * else
  278. * {
  279. * // We could not obtain the semaphore and can therefore not access
  280. * // the shared resource safely.
  281. * }
  282. * }
  283. * }
  284. * </pre>
  285. * \defgroup xSemaphoreTake xSemaphoreTake
  286. * \ingroup Semaphores
  287. */
  288. #define xSemaphoreTake( xSemaphore, xBlockTime ) xQueueSemaphoreTake( ( xSemaphore ), ( xBlockTime ) )
  289. /**
  290. * semphr. h
  291. * <pre>
  292. * xSemaphoreTakeRecursive(
  293. * SemaphoreHandle_t xMutex,
  294. * TickType_t xBlockTime
  295. * );
  296. * </pre>
  297. *
  298. * <i>Macro</i> to recursively obtain, or 'take', a mutex type semaphore.
  299. * The mutex must have previously been created using a call to
  300. * xSemaphoreCreateRecursiveMutex();
  301. *
  302. * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this
  303. * macro to be available.
  304. *
  305. * This macro must not be used on mutexes created using xSemaphoreCreateMutex().
  306. *
  307. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  308. * doesn't become available again until the owner has called
  309. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  310. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  311. * not be available to any other task until it has also 'given' the mutex back
  312. * exactly five times.
  313. *
  314. * @param xMutex A handle to the mutex being obtained. This is the
  315. * handle returned by xSemaphoreCreateRecursiveMutex();
  316. *
  317. * @param xBlockTime The time in ticks to wait for the semaphore to become
  318. * available. The macro portTICK_PERIOD_MS can be used to convert this to a
  319. * real time. A block time of zero can be used to poll the semaphore. If
  320. * the task already owns the semaphore then xSemaphoreTakeRecursive() will
  321. * return immediately no matter what the value of xBlockTime.
  322. *
  323. * @return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime
  324. * expired without the semaphore becoming available.
  325. *
  326. * Example usage:
  327. * <pre>
  328. * SemaphoreHandle_t xMutex = NULL;
  329. *
  330. * // A task that creates a mutex.
  331. * void vATask( void * pvParameters )
  332. * {
  333. * // Create the mutex to guard a shared resource.
  334. * xMutex = xSemaphoreCreateRecursiveMutex();
  335. * }
  336. *
  337. * // A task that uses the mutex.
  338. * void vAnotherTask( void * pvParameters )
  339. * {
  340. * // ... Do other things.
  341. *
  342. * if( xMutex != NULL )
  343. * {
  344. * // See if we can obtain the mutex. If the mutex is not available
  345. * // wait 10 ticks to see if it becomes free.
  346. * if( xSemaphoreTakeRecursive( xSemaphore, ( TickType_t ) 10 ) == pdTRUE )
  347. * {
  348. * // We were able to obtain the mutex and can now access the
  349. * // shared resource.
  350. *
  351. * // ...
  352. * // For some reason due to the nature of the code further calls to
  353. * // xSemaphoreTakeRecursive() are made on the same mutex. In real
  354. * // code these would not be just sequential calls as this would make
  355. * // no sense. Instead the calls are likely to be buried inside
  356. * // a more complex call structure.
  357. * xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  358. * xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  359. *
  360. * // The mutex has now been 'taken' three times, so will not be
  361. * // available to another task until it has also been given back
  362. * // three times. Again it is unlikely that real code would have
  363. * // these calls sequentially, but instead buried in a more complex
  364. * // call structure. This is just for illustrative purposes.
  365. * xSemaphoreGiveRecursive( xMutex );
  366. * xSemaphoreGiveRecursive( xMutex );
  367. * xSemaphoreGiveRecursive( xMutex );
  368. *
  369. * // Now the mutex can be taken by other tasks.
  370. * }
  371. * else
  372. * {
  373. * // We could not obtain the mutex and can therefore not access
  374. * // the shared resource safely.
  375. * }
  376. * }
  377. * }
  378. * </pre>
  379. * \defgroup xSemaphoreTakeRecursive xSemaphoreTakeRecursive
  380. * \ingroup Semaphores
  381. */
  382. #if ( configUSE_RECURSIVE_MUTEXES == 1 )
  383. #define xSemaphoreTakeRecursive( xMutex, xBlockTime ) xQueueTakeMutexRecursive( ( xMutex ), ( xBlockTime ) )
  384. #endif
  385. /**
  386. * semphr. h
  387. * <pre>
  388. * xSemaphoreGive( SemaphoreHandle_t xSemaphore );
  389. * </pre>
  390. *
  391. * <i>Macro</i> to release a semaphore. The semaphore must have previously been
  392. * created with a call to xSemaphoreCreateBinary(), xSemaphoreCreateMutex() or
  393. * xSemaphoreCreateCounting(). and obtained using sSemaphoreTake().
  394. *
  395. * This macro must not be used from an ISR. See xSemaphoreGiveFromISR () for
  396. * an alternative which can be used from an ISR.
  397. *
  398. * This macro must also not be used on semaphores created using
  399. * xSemaphoreCreateRecursiveMutex().
  400. *
  401. * @param xSemaphore A handle to the semaphore being released. This is the
  402. * handle returned when the semaphore was created.
  403. *
  404. * @return pdTRUE if the semaphore was released. pdFALSE if an error occurred.
  405. * Semaphores are implemented using queues. An error can occur if there is
  406. * no space on the queue to post a message - indicating that the
  407. * semaphore was not first obtained correctly.
  408. *
  409. * Example usage:
  410. * <pre>
  411. * SemaphoreHandle_t xSemaphore = NULL;
  412. *
  413. * void vATask( void * pvParameters )
  414. * {
  415. * // Create the semaphore to guard a shared resource.
  416. * xSemaphore = vSemaphoreCreateBinary();
  417. *
  418. * if( xSemaphore != NULL )
  419. * {
  420. * if( xSemaphoreGive( xSemaphore ) != pdTRUE )
  421. * {
  422. * // We would expect this call to fail because we cannot give
  423. * // a semaphore without first "taking" it!
  424. * }
  425. *
  426. * // Obtain the semaphore - don't block if the semaphore is not
  427. * // immediately available.
  428. * if( xSemaphoreTake( xSemaphore, ( TickType_t ) 0 ) )
  429. * {
  430. * // We now have the semaphore and can access the shared resource.
  431. *
  432. * // ...
  433. *
  434. * // We have finished accessing the shared resource so can free the
  435. * // semaphore.
  436. * if( xSemaphoreGive( xSemaphore ) != pdTRUE )
  437. * {
  438. * // We would not expect this call to fail because we must have
  439. * // obtained the semaphore to get here.
  440. * }
  441. * }
  442. * }
  443. * }
  444. * </pre>
  445. * \defgroup xSemaphoreGive xSemaphoreGive
  446. * \ingroup Semaphores
  447. */
  448. #define xSemaphoreGive( xSemaphore ) xQueueGenericSend( ( QueueHandle_t ) ( xSemaphore ), NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )
  449. /**
  450. * semphr. h
  451. * <pre>
  452. * xSemaphoreGiveRecursive( SemaphoreHandle_t xMutex );
  453. * </pre>
  454. *
  455. * <i>Macro</i> to recursively release, or 'give', a mutex type semaphore.
  456. * The mutex must have previously been created using a call to
  457. * xSemaphoreCreateRecursiveMutex();
  458. *
  459. * configUSE_RECURSIVE_MUTEXES must be set to 1 in FreeRTOSConfig.h for this
  460. * macro to be available.
  461. *
  462. * This macro must not be used on mutexes created using xSemaphoreCreateMutex().
  463. *
  464. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  465. * doesn't become available again until the owner has called
  466. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  467. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  468. * not be available to any other task until it has also 'given' the mutex back
  469. * exactly five times.
  470. *
  471. * @param xMutex A handle to the mutex being released, or 'given'. This is the
  472. * handle returned by xSemaphoreCreateMutex();
  473. *
  474. * @return pdTRUE if the semaphore was given.
  475. *
  476. * Example usage:
  477. * <pre>
  478. * SemaphoreHandle_t xMutex = NULL;
  479. *
  480. * // A task that creates a mutex.
  481. * void vATask( void * pvParameters )
  482. * {
  483. * // Create the mutex to guard a shared resource.
  484. * xMutex = xSemaphoreCreateRecursiveMutex();
  485. * }
  486. *
  487. * // A task that uses the mutex.
  488. * void vAnotherTask( void * pvParameters )
  489. * {
  490. * // ... Do other things.
  491. *
  492. * if( xMutex != NULL )
  493. * {
  494. * // See if we can obtain the mutex. If the mutex is not available
  495. * // wait 10 ticks to see if it becomes free.
  496. * if( xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 ) == pdTRUE )
  497. * {
  498. * // We were able to obtain the mutex and can now access the
  499. * // shared resource.
  500. *
  501. * // ...
  502. * // For some reason due to the nature of the code further calls to
  503. * // xSemaphoreTakeRecursive() are made on the same mutex. In real
  504. * // code these would not be just sequential calls as this would make
  505. * // no sense. Instead the calls are likely to be buried inside
  506. * // a more complex call structure.
  507. * xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  508. * xSemaphoreTakeRecursive( xMutex, ( TickType_t ) 10 );
  509. *
  510. * // The mutex has now been 'taken' three times, so will not be
  511. * // available to another task until it has also been given back
  512. * // three times. Again it is unlikely that real code would have
  513. * // these calls sequentially, it would be more likely that the calls
  514. * // to xSemaphoreGiveRecursive() would be called as a call stack
  515. * // unwound. This is just for demonstrative purposes.
  516. * xSemaphoreGiveRecursive( xMutex );
  517. * xSemaphoreGiveRecursive( xMutex );
  518. * xSemaphoreGiveRecursive( xMutex );
  519. *
  520. * // Now the mutex can be taken by other tasks.
  521. * }
  522. * else
  523. * {
  524. * // We could not obtain the mutex and can therefore not access
  525. * // the shared resource safely.
  526. * }
  527. * }
  528. * }
  529. * </pre>
  530. * \defgroup xSemaphoreGiveRecursive xSemaphoreGiveRecursive
  531. * \ingroup Semaphores
  532. */
  533. #if ( configUSE_RECURSIVE_MUTEXES == 1 )
  534. #define xSemaphoreGiveRecursive( xMutex ) xQueueGiveMutexRecursive( ( xMutex ) )
  535. #endif
  536. /**
  537. * semphr. h
  538. * <pre>
  539. * xSemaphoreGiveFromISR(
  540. * SemaphoreHandle_t xSemaphore,
  541. * BaseType_t *pxHigherPriorityTaskWoken
  542. * );
  543. * </pre>
  544. *
  545. * <i>Macro</i> to release a semaphore. The semaphore must have previously been
  546. * created with a call to xSemaphoreCreateBinary() or xSemaphoreCreateCounting().
  547. *
  548. * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())
  549. * must not be used with this macro.
  550. *
  551. * This macro can be used from an ISR.
  552. *
  553. * @param xSemaphore A handle to the semaphore being released. This is the
  554. * handle returned when the semaphore was created.
  555. *
  556. * @param pxHigherPriorityTaskWoken xSemaphoreGiveFromISR() will set
  557. * *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task
  558. * to unblock, and the unblocked task has a priority higher than the currently
  559. * running task. If xSemaphoreGiveFromISR() sets this value to pdTRUE then
  560. * a context switch should be requested before the interrupt is exited.
  561. *
  562. * @return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.
  563. *
  564. * Example usage:
  565. * <pre>
  566. \#define LONG_TIME 0xffff
  567. \#define TICKS_TO_WAIT 10
  568. * SemaphoreHandle_t xSemaphore = NULL;
  569. *
  570. * // Repetitive task.
  571. * void vATask( void * pvParameters )
  572. * {
  573. * for( ;; )
  574. * {
  575. * // We want this task to run every 10 ticks of a timer. The semaphore
  576. * // was created before this task was started.
  577. *
  578. * // Block waiting for the semaphore to become available.
  579. * if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )
  580. * {
  581. * // It is time to execute.
  582. *
  583. * // ...
  584. *
  585. * // We have finished our task. Return to the top of the loop where
  586. * // we will block on the semaphore until it is time to execute
  587. * // again. Note when using the semaphore for synchronisation with an
  588. * // ISR in this manner there is no need to 'give' the semaphore back.
  589. * }
  590. * }
  591. * }
  592. *
  593. * // Timer ISR
  594. * void vTimerISR( void * pvParameters )
  595. * {
  596. * static uint8_t ucLocalTickCount = 0;
  597. * static BaseType_t xHigherPriorityTaskWoken;
  598. *
  599. * // A timer tick has occurred.
  600. *
  601. * // ... Do other time functions.
  602. *
  603. * // Is it time for vATask () to run?
  604. * xHigherPriorityTaskWoken = pdFALSE;
  605. * ucLocalTickCount++;
  606. * if( ucLocalTickCount >= TICKS_TO_WAIT )
  607. * {
  608. * // Unblock the task by releasing the semaphore.
  609. * xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );
  610. *
  611. * // Reset the count so we release the semaphore again in 10 ticks time.
  612. * ucLocalTickCount = 0;
  613. * }
  614. *
  615. * if( xHigherPriorityTaskWoken != pdFALSE )
  616. * {
  617. * // We can force a context switch here. Context switching from an
  618. * // ISR uses port specific syntax. Check the demo task for your port
  619. * // to find the syntax required.
  620. * }
  621. * }
  622. * </pre>
  623. * \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR
  624. * \ingroup Semaphores
  625. */
  626. #define xSemaphoreGiveFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueGiveFromISR( ( QueueHandle_t ) ( xSemaphore ), ( pxHigherPriorityTaskWoken ) )
  627. /**
  628. * semphr. h
  629. * <pre>
  630. * xSemaphoreTakeFromISR(
  631. * SemaphoreHandle_t xSemaphore,
  632. * BaseType_t *pxHigherPriorityTaskWoken
  633. * );
  634. * </pre>
  635. *
  636. * <i>Macro</i> to take a semaphore from an ISR. The semaphore must have
  637. * previously been created with a call to xSemaphoreCreateBinary() or
  638. * xSemaphoreCreateCounting().
  639. *
  640. * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())
  641. * must not be used with this macro.
  642. *
  643. * This macro can be used from an ISR, however taking a semaphore from an ISR
  644. * is not a common operation. It is likely to only be useful when taking a
  645. * counting semaphore when an interrupt is obtaining an object from a resource
  646. * pool (when the semaphore count indicates the number of resources available).
  647. *
  648. * @param xSemaphore A handle to the semaphore being taken. This is the
  649. * handle returned when the semaphore was created.
  650. *
  651. * @param pxHigherPriorityTaskWoken xSemaphoreTakeFromISR() will set
  652. * *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task
  653. * to unblock, and the unblocked task has a priority higher than the currently
  654. * running task. If xSemaphoreTakeFromISR() sets this value to pdTRUE then
  655. * a context switch should be requested before the interrupt is exited.
  656. *
  657. * @return pdTRUE if the semaphore was successfully taken, otherwise
  658. * pdFALSE
  659. */
  660. #define xSemaphoreTakeFromISR( xSemaphore, pxHigherPriorityTaskWoken ) xQueueReceiveFromISR( ( QueueHandle_t ) ( xSemaphore ), NULL, ( pxHigherPriorityTaskWoken ) )
  661. /**
  662. * semphr. h
  663. * <pre>
  664. * SemaphoreHandle_t xSemaphoreCreateMutex( void );
  665. * </pre>
  666. *
  667. * Creates a new mutex type semaphore instance, and returns a handle by which
  668. * the new mutex can be referenced.
  669. *
  670. * Internally, within the FreeRTOS implementation, mutex semaphores use a block
  671. * of memory, in which the mutex structure is stored. If a mutex is created
  672. * using xSemaphoreCreateMutex() then the required memory is automatically
  673. * dynamically allocated inside the xSemaphoreCreateMutex() function. (see
  674. * https://www.FreeRTOS.org/a00111.html). If a mutex is created using
  675. * xSemaphoreCreateMutexStatic() then the application writer must provided the
  676. * memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to be created
  677. * without using any dynamic memory allocation.
  678. *
  679. * Mutexes created using this function can be accessed using the xSemaphoreTake()
  680. * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and
  681. * xSemaphoreGiveRecursive() macros must not be used.
  682. *
  683. * This type of semaphore uses a priority inheritance mechanism so a task
  684. * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
  685. * semaphore it is no longer required.
  686. *
  687. * Mutex type semaphores cannot be used from within interrupt service routines.
  688. *
  689. * See xSemaphoreCreateBinary() for an alternative implementation that can be
  690. * used for pure synchronisation (where one task or interrupt always 'gives' the
  691. * semaphore and another always 'takes' the semaphore) and from within interrupt
  692. * service routines.
  693. *
  694. * @return If the mutex was successfully created then a handle to the created
  695. * semaphore is returned. If there was not enough heap to allocate the mutex
  696. * data structures then NULL is returned.
  697. *
  698. * Example usage:
  699. * <pre>
  700. * SemaphoreHandle_t xSemaphore;
  701. *
  702. * void vATask( void * pvParameters )
  703. * {
  704. * // Semaphore cannot be used before a call to xSemaphoreCreateMutex().
  705. * // This is a macro so pass the variable in directly.
  706. * xSemaphore = xSemaphoreCreateMutex();
  707. *
  708. * if( xSemaphore != NULL )
  709. * {
  710. * // The semaphore was created successfully.
  711. * // The semaphore can now be used.
  712. * }
  713. * }
  714. * </pre>
  715. * \defgroup xSemaphoreCreateMutex xSemaphoreCreateMutex
  716. * \ingroup Semaphores
  717. */
  718. #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
  719. #define xSemaphoreCreateMutex() xQueueCreateMutex( queueQUEUE_TYPE_MUTEX )
  720. #endif
  721. /**
  722. * semphr. h
  723. * <pre>
  724. * SemaphoreHandle_t xSemaphoreCreateMutexStatic( StaticSemaphore_t *pxMutexBuffer );
  725. * </pre>
  726. *
  727. * Creates a new mutex type semaphore instance, and returns a handle by which
  728. * the new mutex can be referenced.
  729. *
  730. * Internally, within the FreeRTOS implementation, mutex semaphores use a block
  731. * of memory, in which the mutex structure is stored. If a mutex is created
  732. * using xSemaphoreCreateMutex() then the required memory is automatically
  733. * dynamically allocated inside the xSemaphoreCreateMutex() function. (see
  734. * https://www.FreeRTOS.org/a00111.html). If a mutex is created using
  735. * xSemaphoreCreateMutexStatic() then the application writer must provided the
  736. * memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to be created
  737. * without using any dynamic memory allocation.
  738. *
  739. * Mutexes created using this function can be accessed using the xSemaphoreTake()
  740. * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and
  741. * xSemaphoreGiveRecursive() macros must not be used.
  742. *
  743. * This type of semaphore uses a priority inheritance mechanism so a task
  744. * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
  745. * semaphore it is no longer required.
  746. *
  747. * Mutex type semaphores cannot be used from within interrupt service routines.
  748. *
  749. * See xSemaphoreCreateBinary() for an alternative implementation that can be
  750. * used for pure synchronisation (where one task or interrupt always 'gives' the
  751. * semaphore and another always 'takes' the semaphore) and from within interrupt
  752. * service routines.
  753. *
  754. * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t,
  755. * which will be used to hold the mutex's data structure, removing the need for
  756. * the memory to be allocated dynamically.
  757. *
  758. * @return If the mutex was successfully created then a handle to the created
  759. * mutex is returned. If pxMutexBuffer was NULL then NULL is returned.
  760. *
  761. * Example usage:
  762. * <pre>
  763. * SemaphoreHandle_t xSemaphore;
  764. * StaticSemaphore_t xMutexBuffer;
  765. *
  766. * void vATask( void * pvParameters )
  767. * {
  768. * // A mutex cannot be used before it has been created. xMutexBuffer is
  769. * // into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is
  770. * // attempted.
  771. * xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );
  772. *
  773. * // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
  774. * // so there is no need to check it.
  775. * }
  776. * </pre>
  777. * \defgroup xSemaphoreCreateMutexStatic xSemaphoreCreateMutexStatic
  778. * \ingroup Semaphores
  779. */
  780. #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
  781. #define xSemaphoreCreateMutexStatic( pxMutexBuffer ) xQueueCreateMutexStatic( queueQUEUE_TYPE_MUTEX, ( pxMutexBuffer ) )
  782. #endif /* configSUPPORT_STATIC_ALLOCATION */
  783. /**
  784. * semphr. h
  785. * <pre>
  786. * SemaphoreHandle_t xSemaphoreCreateRecursiveMutex( void );
  787. * </pre>
  788. *
  789. * Creates a new recursive mutex type semaphore instance, and returns a handle
  790. * by which the new recursive mutex can be referenced.
  791. *
  792. * Internally, within the FreeRTOS implementation, recursive mutexs use a block
  793. * of memory, in which the mutex structure is stored. If a recursive mutex is
  794. * created using xSemaphoreCreateRecursiveMutex() then the required memory is
  795. * automatically dynamically allocated inside the
  796. * xSemaphoreCreateRecursiveMutex() function. (see
  797. * https://www.FreeRTOS.org/a00111.html). If a recursive mutex is created using
  798. * xSemaphoreCreateRecursiveMutexStatic() then the application writer must
  799. * provide the memory that will get used by the mutex.
  800. * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to
  801. * be created without using any dynamic memory allocation.
  802. *
  803. * Mutexes created using this macro can be accessed using the
  804. * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The
  805. * xSemaphoreTake() and xSemaphoreGive() macros must not be used.
  806. *
  807. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  808. * doesn't become available again until the owner has called
  809. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  810. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  811. * not be available to any other task until it has also 'given' the mutex back
  812. * exactly five times.
  813. *
  814. * This type of semaphore uses a priority inheritance mechanism so a task
  815. * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
  816. * semaphore it is no longer required.
  817. *
  818. * Mutex type semaphores cannot be used from within interrupt service routines.
  819. *
  820. * See xSemaphoreCreateBinary() for an alternative implementation that can be
  821. * used for pure synchronisation (where one task or interrupt always 'gives' the
  822. * semaphore and another always 'takes' the semaphore) and from within interrupt
  823. * service routines.
  824. *
  825. * @return xSemaphore Handle to the created mutex semaphore. Should be of type
  826. * SemaphoreHandle_t.
  827. *
  828. * Example usage:
  829. * <pre>
  830. * SemaphoreHandle_t xSemaphore;
  831. *
  832. * void vATask( void * pvParameters )
  833. * {
  834. * // Semaphore cannot be used before a call to xSemaphoreCreateMutex().
  835. * // This is a macro so pass the variable in directly.
  836. * xSemaphore = xSemaphoreCreateRecursiveMutex();
  837. *
  838. * if( xSemaphore != NULL )
  839. * {
  840. * // The semaphore was created successfully.
  841. * // The semaphore can now be used.
  842. * }
  843. * }
  844. * </pre>
  845. * \defgroup xSemaphoreCreateRecursiveMutex xSemaphoreCreateRecursiveMutex
  846. * \ingroup Semaphores
  847. */
  848. #if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) )
  849. #define xSemaphoreCreateRecursiveMutex() xQueueCreateMutex( queueQUEUE_TYPE_RECURSIVE_MUTEX )
  850. #endif
  851. /**
  852. * semphr. h
  853. * <pre>
  854. * SemaphoreHandle_t xSemaphoreCreateRecursiveMutexStatic( StaticSemaphore_t *pxMutexBuffer );
  855. * </pre>
  856. *
  857. * Creates a new recursive mutex type semaphore instance, and returns a handle
  858. * by which the new recursive mutex can be referenced.
  859. *
  860. * Internally, within the FreeRTOS implementation, recursive mutexs use a block
  861. * of memory, in which the mutex structure is stored. If a recursive mutex is
  862. * created using xSemaphoreCreateRecursiveMutex() then the required memory is
  863. * automatically dynamically allocated inside the
  864. * xSemaphoreCreateRecursiveMutex() function. (see
  865. * https://www.FreeRTOS.org/a00111.html). If a recursive mutex is created using
  866. * xSemaphoreCreateRecursiveMutexStatic() then the application writer must
  867. * provide the memory that will get used by the mutex.
  868. * xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to
  869. * be created without using any dynamic memory allocation.
  870. *
  871. * Mutexes created using this macro can be accessed using the
  872. * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The
  873. * xSemaphoreTake() and xSemaphoreGive() macros must not be used.
  874. *
  875. * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
  876. * doesn't become available again until the owner has called
  877. * xSemaphoreGiveRecursive() for each successful 'take' request. For example,
  878. * if a task successfully 'takes' the same mutex 5 times then the mutex will
  879. * not be available to any other task until it has also 'given' the mutex back
  880. * exactly five times.
  881. *
  882. * This type of semaphore uses a priority inheritance mechanism so a task
  883. * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
  884. * semaphore it is no longer required.
  885. *
  886. * Mutex type semaphores cannot be used from within interrupt service routines.
  887. *
  888. * See xSemaphoreCreateBinary() for an alternative implementation that can be
  889. * used for pure synchronisation (where one task or interrupt always 'gives' the
  890. * semaphore and another always 'takes' the semaphore) and from within interrupt
  891. * service routines.
  892. *
  893. * @param pxMutexBuffer Must point to a variable of type StaticSemaphore_t,
  894. * which will then be used to hold the recursive mutex's data structure,
  895. * removing the need for the memory to be allocated dynamically.
  896. *
  897. * @return If the recursive mutex was successfully created then a handle to the
  898. * created recursive mutex is returned. If pxMutexBuffer was NULL then NULL is
  899. * returned.
  900. *
  901. * Example usage:
  902. * <pre>
  903. * SemaphoreHandle_t xSemaphore;
  904. * StaticSemaphore_t xMutexBuffer;
  905. *
  906. * void vATask( void * pvParameters )
  907. * {
  908. * // A recursive semaphore cannot be used before it is created. Here a
  909. * // recursive mutex is created using xSemaphoreCreateRecursiveMutexStatic().
  910. * // The address of xMutexBuffer is passed into the function, and will hold
  911. * // the mutexes data structures - so no dynamic memory allocation will be
  912. * // attempted.
  913. * xSemaphore = xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );
  914. *
  915. * // As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
  916. * // so there is no need to check it.
  917. * }
  918. * </pre>
  919. * \defgroup xSemaphoreCreateRecursiveMutexStatic xSemaphoreCreateRecursiveMutexStatic
  920. * \ingroup Semaphores
  921. */
  922. #if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configUSE_RECURSIVE_MUTEXES == 1 ) )
  923. #define xSemaphoreCreateRecursiveMutexStatic( pxStaticSemaphore ) xQueueCreateMutexStatic( queueQUEUE_TYPE_RECURSIVE_MUTEX, pxStaticSemaphore )
  924. #endif /* configSUPPORT_STATIC_ALLOCATION */
  925. /**
  926. * semphr. h
  927. * <pre>
  928. * SemaphoreHandle_t xSemaphoreCreateCounting( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount );
  929. * </pre>
  930. *
  931. * Creates a new counting semaphore instance, and returns a handle by which the
  932. * new counting semaphore can be referenced.
  933. *
  934. * In many usage scenarios it is faster and more memory efficient to use a
  935. * direct to task notification in place of a counting semaphore!
  936. * https://www.FreeRTOS.org/RTOS-task-notifications.html
  937. *
  938. * Internally, within the FreeRTOS implementation, counting semaphores use a
  939. * block of memory, in which the counting semaphore structure is stored. If a
  940. * counting semaphore is created using xSemaphoreCreateCounting() then the
  941. * required memory is automatically dynamically allocated inside the
  942. * xSemaphoreCreateCounting() function. (see
  943. * https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created
  944. * using xSemaphoreCreateCountingStatic() then the application writer can
  945. * instead optionally provide the memory that will get used by the counting
  946. * semaphore. xSemaphoreCreateCountingStatic() therefore allows a counting
  947. * semaphore to be created without using any dynamic memory allocation.
  948. *
  949. * Counting semaphores are typically used for two things:
  950. *
  951. * 1) Counting events.
  952. *
  953. * In this usage scenario an event handler will 'give' a semaphore each time
  954. * an event occurs (incrementing the semaphore count value), and a handler
  955. * task will 'take' a semaphore each time it processes an event
  956. * (decrementing the semaphore count value). The count value is therefore
  957. * the difference between the number of events that have occurred and the
  958. * number that have been processed. In this case it is desirable for the
  959. * initial count value to be zero.
  960. *
  961. * 2) Resource management.
  962. *
  963. * In this usage scenario the count value indicates the number of resources
  964. * available. To obtain control of a resource a task must first obtain a
  965. * semaphore - decrementing the semaphore count value. When the count value
  966. * reaches zero there are no free resources. When a task finishes with the
  967. * resource it 'gives' the semaphore back - incrementing the semaphore count
  968. * value. In this case it is desirable for the initial count value to be
  969. * equal to the maximum count value, indicating that all resources are free.
  970. *
  971. * @param uxMaxCount The maximum count value that can be reached. When the
  972. * semaphore reaches this value it can no longer be 'given'.
  973. *
  974. * @param uxInitialCount The count value assigned to the semaphore when it is
  975. * created.
  976. *
  977. * @return Handle to the created semaphore. Null if the semaphore could not be
  978. * created.
  979. *
  980. * Example usage:
  981. * <pre>
  982. * SemaphoreHandle_t xSemaphore;
  983. *
  984. * void vATask( void * pvParameters )
  985. * {
  986. * SemaphoreHandle_t xSemaphore = NULL;
  987. *
  988. * // Semaphore cannot be used before a call to xSemaphoreCreateCounting().
  989. * // The max value to which the semaphore can count should be 10, and the
  990. * // initial value assigned to the count should be 0.
  991. * xSemaphore = xSemaphoreCreateCounting( 10, 0 );
  992. *
  993. * if( xSemaphore != NULL )
  994. * {
  995. * // The semaphore was created successfully.
  996. * // The semaphore can now be used.
  997. * }
  998. * }
  999. * </pre>
  1000. * \defgroup xSemaphoreCreateCounting xSemaphoreCreateCounting
  1001. * \ingroup Semaphores
  1002. */
  1003. #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
  1004. #define xSemaphoreCreateCounting( uxMaxCount, uxInitialCount ) xQueueCreateCountingSemaphore( ( uxMaxCount ), ( uxInitialCount ) )
  1005. #endif
  1006. /**
  1007. * semphr. h
  1008. * <pre>
  1009. * SemaphoreHandle_t xSemaphoreCreateCountingStatic( UBaseType_t uxMaxCount, UBaseType_t uxInitialCount, StaticSemaphore_t *pxSemaphoreBuffer );
  1010. * </pre>
  1011. *
  1012. * Creates a new counting semaphore instance, and returns a handle by which the
  1013. * new counting semaphore can be referenced.
  1014. *
  1015. * In many usage scenarios it is faster and more memory efficient to use a
  1016. * direct to task notification in place of a counting semaphore!
  1017. * https://www.FreeRTOS.org/RTOS-task-notifications.html
  1018. *
  1019. * Internally, within the FreeRTOS implementation, counting semaphores use a
  1020. * block of memory, in which the counting semaphore structure is stored. If a
  1021. * counting semaphore is created using xSemaphoreCreateCounting() then the
  1022. * required memory is automatically dynamically allocated inside the
  1023. * xSemaphoreCreateCounting() function. (see
  1024. * https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created
  1025. * using xSemaphoreCreateCountingStatic() then the application writer must
  1026. * provide the memory. xSemaphoreCreateCountingStatic() therefore allows a
  1027. * counting semaphore to be created without using any dynamic memory allocation.
  1028. *
  1029. * Counting semaphores are typically used for two things:
  1030. *
  1031. * 1) Counting events.
  1032. *
  1033. * In this usage scenario an event handler will 'give' a semaphore each time
  1034. * an event occurs (incrementing the semaphore count value), and a handler
  1035. * task will 'take' a semaphore each time it processes an event
  1036. * (decrementing the semaphore count value). The count value is therefore
  1037. * the difference between the number of events that have occurred and the
  1038. * number that have been processed. In this case it is desirable for the
  1039. * initial count value to be zero.
  1040. *
  1041. * 2) Resource management.
  1042. *
  1043. * In this usage scenario the count value indicates the number of resources
  1044. * available. To obtain control of a resource a task must first obtain a
  1045. * semaphore - decrementing the semaphore count value. When the count value
  1046. * reaches zero there are no free resources. When a task finishes with the
  1047. * resource it 'gives' the semaphore back - incrementing the semaphore count
  1048. * value. In this case it is desirable for the initial count value to be
  1049. * equal to the maximum count value, indicating that all resources are free.
  1050. *
  1051. * @param uxMaxCount The maximum count value that can be reached. When the
  1052. * semaphore reaches this value it can no longer be 'given'.
  1053. *
  1054. * @param uxInitialCount The count value assigned to the semaphore when it is
  1055. * created.
  1056. *
  1057. * @param pxSemaphoreBuffer Must point to a variable of type StaticSemaphore_t,
  1058. * which will then be used to hold the semaphore's data structure, removing the
  1059. * need for the memory to be allocated dynamically.
  1060. *
  1061. * @return If the counting semaphore was successfully created then a handle to
  1062. * the created counting semaphore is returned. If pxSemaphoreBuffer was NULL
  1063. * then NULL is returned.
  1064. *
  1065. * Example usage:
  1066. * <pre>
  1067. * SemaphoreHandle_t xSemaphore;
  1068. * StaticSemaphore_t xSemaphoreBuffer;
  1069. *
  1070. * void vATask( void * pvParameters )
  1071. * {
  1072. * SemaphoreHandle_t xSemaphore = NULL;
  1073. *
  1074. * // Counting semaphore cannot be used before they have been created. Create
  1075. * // a counting semaphore using xSemaphoreCreateCountingStatic(). The max
  1076. * // value to which the semaphore can count is 10, and the initial value
  1077. * // assigned to the count will be 0. The address of xSemaphoreBuffer is
  1078. * // passed in and will be used to hold the semaphore structure, so no dynamic
  1079. * // memory allocation will be used.
  1080. * xSemaphore = xSemaphoreCreateCounting( 10, 0, &xSemaphoreBuffer );
  1081. *
  1082. * // No memory allocation was attempted so xSemaphore cannot be NULL, so there
  1083. * // is no need to check its value.
  1084. * }
  1085. * </pre>
  1086. * \defgroup xSemaphoreCreateCountingStatic xSemaphoreCreateCountingStatic
  1087. * \ingroup Semaphores
  1088. */
  1089. #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
  1090. #define xSemaphoreCreateCountingStatic( uxMaxCount, uxInitialCount, pxSemaphoreBuffer ) xQueueCreateCountingSemaphoreStatic( ( uxMaxCount ), ( uxInitialCount ), ( pxSemaphoreBuffer ) )
  1091. #endif /* configSUPPORT_STATIC_ALLOCATION */
  1092. /**
  1093. * semphr. h
  1094. * <pre>
  1095. * void vSemaphoreDelete( SemaphoreHandle_t xSemaphore );
  1096. * </pre>
  1097. *
  1098. * Delete a semaphore. This function must be used with care. For example,
  1099. * do not delete a mutex type semaphore if the mutex is held by a task.
  1100. *
  1101. * @param xSemaphore A handle to the semaphore to be deleted.
  1102. *
  1103. * \defgroup vSemaphoreDelete vSemaphoreDelete
  1104. * \ingroup Semaphores
  1105. */
  1106. #define vSemaphoreDelete( xSemaphore ) vQueueDelete( ( QueueHandle_t ) ( xSemaphore ) )
  1107. /**
  1108. * semphr.h
  1109. * <pre>
  1110. * TaskHandle_t xSemaphoreGetMutexHolder( SemaphoreHandle_t xMutex );
  1111. * </pre>
  1112. *
  1113. * If xMutex is indeed a mutex type semaphore, return the current mutex holder.
  1114. * If xMutex is not a mutex type semaphore, or the mutex is available (not held
  1115. * by a task), return NULL.
  1116. *
  1117. * Note: This is a good way of determining if the calling task is the mutex
  1118. * holder, but not a good way of determining the identity of the mutex holder as
  1119. * the holder may change between the function exiting and the returned value
  1120. * being tested.
  1121. */
  1122. #define xSemaphoreGetMutexHolder( xSemaphore ) xQueueGetMutexHolder( ( xSemaphore ) )
  1123. /**
  1124. * semphr.h
  1125. * <pre>
  1126. * TaskHandle_t xSemaphoreGetMutexHolderFromISR( SemaphoreHandle_t xMutex );
  1127. * </pre>
  1128. *
  1129. * If xMutex is indeed a mutex type semaphore, return the current mutex holder.
  1130. * If xMutex is not a mutex type semaphore, or the mutex is available (not held
  1131. * by a task), return NULL.
  1132. *
  1133. */
  1134. #define xSemaphoreGetMutexHolderFromISR( xSemaphore ) xQueueGetMutexHolderFromISR( ( xSemaphore ) )
  1135. /**
  1136. * semphr.h
  1137. * <pre>
  1138. * UBaseType_t uxSemaphoreGetCount( SemaphoreHandle_t xSemaphore );
  1139. * </pre>
  1140. *
  1141. * If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns
  1142. * its current count value. If the semaphore is a binary semaphore then
  1143. * uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0 if the
  1144. * semaphore is not available.
  1145. *
  1146. */
  1147. #define uxSemaphoreGetCount( xSemaphore ) uxQueueMessagesWaiting( ( QueueHandle_t ) ( xSemaphore ) )
  1148. #endif /* SEMAPHORE_H */