João Jardim / FreeRTOS_V8_2_1_LPC1768

Dependents:   frtos_v_8_bluetooth frtos_v_8_pololu frtos_v_8_Final

source/include/semphr.h@0:91ad48ad5687, 2015-06-06 (annotated)

Committer:
dflet
Date:
Sat Jun 06 13:27:43 2015 +0000
Revision:
0:91ad48ad5687
Setup for LPC CM3 but may work with LPC CM4

Who changed what in which revision?

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