David Fletcher / Mbed 2 deprecated cc3100_Test_websock_Camera_CM4F

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   mbed

FreeRTOS/source/include/semphr.h@22:f9b5e0b80bf2, 2015-09-15 (annotated)

Committer:
dflet
Date:
Tue Sep 15 16:45:04 2015 +0000
Revision:
22:f9b5e0b80bf2
Parent:
0:50cedd586816 
Removed some debug.

Who changed what in which revision?

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