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