Lines Matching full:the
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
55 * This old vSemaphoreCreateBinary() macro is now deprecated in favour of the
57 * the vSemaphoreCreateBinary() macro are created in a state such that the
58 * first call to 'take' the semaphore would pass, whereas binary semaphores
59 * created using xSemaphoreCreateBinary() are created in a state such that the
60 * the semaphore must first be 'given' before it can be 'taken'.
62 * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.
63 * The queue length is 1 as this is a binary semaphore. The data size is 0
64 * as we don't want to actually store any data - we just want to know if the
68 * between an interrupt and a task. The semaphore need not be given back once
69 * obtained, so one task/interrupt can continuously 'give' the semaphore while
70 * another continuously 'takes' the semaphore. For this reason this type of
74 * @param xSemaphore Handle to the created semaphore. Should be of type SemaphoreHandle_t.
83 * // This is a macro so pass the variable in directly.
88 * // The semaphore was created successfully.
89 * // The semaphore can now be used.
113 * Creates a new binary semaphore instance, and returns a handle by which the
120 * Internally, within the FreeRTOS implementation, binary semaphores use a block
121 * of memory, in which the semaphore structure is stored. If a binary semaphore
122 * is created using xSemaphoreCreateBinary() then the required memory is
123 * automatically dynamically allocated inside the xSemaphoreCreateBinary()
125 * is created using xSemaphoreCreateBinaryStatic() then the application writer
126 * must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a
129 * The old vSemaphoreCreateBinary() macro is now deprecated in favour of this
131 * the vSemaphoreCreateBinary() macro are created in a state such that the
132 * first call to 'take' the semaphore would pass, whereas binary semaphores
133 * created using xSemaphoreCreateBinary() are created in a state such that the
134 * the semaphore must first be 'given' before it can be 'taken'.
137 * between an interrupt and a task. The semaphore need not be given back once
138 * obtained, so one task/interrupt can continuously 'give' the semaphore while
139 * another continuously 'takes' the semaphore. For this reason this type of
143 * @return Handle to the created semaphore, or NULL if the memory required to
144 * hold the semaphore's data structures could not be allocated.
153 * // This is a macro so pass the variable in directly.
158 * // The semaphore was created successfully.
159 * // The semaphore can now be used.
176 * Creates a new binary semaphore instance, and returns a handle by which the
183 * Internally, within the FreeRTOS implementation, binary semaphores use a block
184 * of memory, in which the semaphore structure is stored. If a binary semaphore
185 * is created using xSemaphoreCreateBinary() then the required memory is
186 * automatically dynamically allocated inside the xSemaphoreCreateBinary()
188 * is created using xSemaphoreCreateBinaryStatic() then the application writer
189 * must provide the memory. xSemaphoreCreateBinaryStatic() therefore allows a
193 * between an interrupt and a task. The semaphore need not be given back once
194 * obtained, so one task/interrupt can continuously 'give' the semaphore while
195 * another continuously 'takes' the semaphore. For this reason this type of
200 * which will then be used to hold the semaphore's data structure, removing the
201 * need for the memory to be allocated dynamically.
203 * @return If the semaphore is created then a handle to the created semaphore is
214 * // The semaphore's data structures will be placed in the xSemaphoreBuffer
215 * // variable, the address of which is passed into the function. The
216 * // function's parameter is not NULL, so the function will not attempt any
217 * // dynamic memory allocation, and therefore the function will not return
240 * <i>Macro</i> to obtain a semaphore. The semaphore must have previously been
244 * @param xSemaphore A handle to the semaphore being taken - obtained when
245 * the semaphore was created.
247 * @param xBlockTime The time in ticks to wait for the semaphore to become
248 * available. The macro portTICK_PERIOD_MS can be used to convert this to a
249 * real time. A block time of zero can be used to poll the semaphore. A block
253 * @return pdTRUE if the semaphore was obtained. pdFALSE
254 * if xBlockTime expired without the semaphore becoming available.
263 * // Create the semaphore to guard a shared resource.
267 * // A task that uses the semaphore.
274 * // See if we can obtain the semaphore. If the semaphore is not available
278 * // We were able to obtain the semaphore and can now access the
283 * // We have finished accessing the shared resource. Release the
289 * // We could not obtain the semaphore and can therefore not access
290 * // the shared resource safely.
310 * The mutex must have previously been created using a call to
318 * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
319 * doesn't become available again until the owner has called
321 * if a task successfully 'takes' the same mutex 5 times then the mutex will
322 * not be available to any other task until it has also 'given' the mutex back
325 * @param xMutex A handle to the mutex being obtained. This is the
328 * @param xBlockTime The time in ticks to wait for the semaphore to become
329 * available. The macro portTICK_PERIOD_MS can be used to convert this to a
330 * real time. A block time of zero can be used to poll the semaphore. If
331 * the task already owns the semaphore then xSemaphoreTakeRecursive() will
332 * return immediately no matter what the value of xBlockTime.
334 * @return pdTRUE if the semaphore was obtained. pdFALSE if xBlockTime
335 * expired without the semaphore becoming available.
344 * // Create the mutex to guard a shared resource.
348 * // A task that uses the mutex.
355 * // See if we can obtain the mutex. If the mutex is not available
359 * // We were able to obtain the mutex and can now access the
363 * // For some reason due to the nature of the code further calls to
364 * // xSemaphoreTakeRecursive() are made on the same mutex. In real
366 * // no sense. Instead the calls are likely to be buried inside
371 * // The mutex has now been 'taken' three times, so will not be
380 * // Now the mutex can be taken by other tasks.
384 * // We could not obtain the mutex and can therefore not access
385 * // the shared resource safely.
403 * <i>Macro</i> to release a semaphore. The semaphore must have previously been
413 * @param xSemaphore A handle to the semaphore being released. This is the
414 * handle returned when the semaphore was created.
416 * @return pdTRUE if the semaphore was released. pdFALSE if an error occurred.
418 * no space on the queue to post a message - indicating that the
427 * // Create the semaphore to guard a shared resource.
438 * // Obtain the semaphore - don't block if the semaphore is not
442 * // We now have the semaphore and can access the shared resource.
446 * // We have finished accessing the shared resource so can free the
451 * // obtained the semaphore to get here.
469 * The mutex must have previously been created using a call to
477 * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
478 * doesn't become available again until the owner has called
480 * if a task successfully 'takes' the same mutex 5 times then the mutex will
481 * not be available to any other task until it has also 'given' the mutex back
484 * @param xMutex A handle to the mutex being released, or 'given'. This is the
487 * @return pdTRUE if the semaphore was given.
496 * // Create the mutex to guard a shared resource.
500 * // A task that uses the mutex.
507 * // See if we can obtain the mutex. If the mutex is not available
511 * // We were able to obtain the mutex and can now access the
515 * // For some reason due to the nature of the code further calls to
516 * // xSemaphoreTakeRecursive() are made on the same mutex. In real
518 * // no sense. Instead the calls are likely to be buried inside
523 * // The mutex has now been 'taken' three times, so will not be
526 * // these calls sequentially, it would be more likely that the calls
533 * // Now the mutex can be taken by other tasks.
537 * // We could not obtain the mutex and can therefore not access
538 * // the shared resource safely.
559 * <i>Macro</i> to release a semaphore. The semaphore must have previously been
567 * @param xSemaphore A handle to the semaphore being released. This is the
568 * handle returned when the semaphore was created.
571 * *pxHigherPriorityTaskWoken to pdTRUE if giving the semaphore caused a task
572 * to unblock, and the unblocked task has a priority higher than the currently
574 * a context switch should be requested before the interrupt is exited.
576 * @return pdTRUE if the semaphore was successfully given, otherwise errQUEUE_FULL.
589 * // We want this task to run every 10 ticks of a timer. The semaphore
592 * // Block waiting for the semaphore to become available.
599 * // We have finished our task. Return to the top of the loop where
600 * // we will block on the semaphore until it is time to execute
601 * // again. Note when using the semaphore for synchronisation with an
602 * // ISR in this manner there is no need to 'give' the semaphore back.
622 * // Unblock the task by releasing the semaphore.
625 * // Reset the count so we release the semaphore again in 10 ticks time.
632 * // ISR uses port specific syntax. Check the demo task for your port
633 * // to find the syntax required.
651 * <i>Macro</i> to take a semaphore from an ISR. The semaphore must have
661 * pool (when the semaphore count indicates the number of resources available).
663 * @param xSemaphore A handle to the semaphore being taken. This is the
664 * handle returned when the semaphore was created.
667 * *pxHigherPriorityTaskWoken to pdTRUE if taking the semaphore caused a task
668 * to unblock, and the unblocked task has a priority higher than the currently
670 * a context switch should be requested before the interrupt is exited.
672 * @return pdTRUE if the semaphore was successfully taken, otherwise
684 * the new mutex can be referenced.
686 * Internally, within the FreeRTOS implementation, mutex semaphores use a block
687 * of memory, in which the mutex structure is stored. If a mutex is created
688 * using xSemaphoreCreateMutex() then the required memory is automatically
689 * dynamically allocated inside the xSemaphoreCreateMutex() function. (see
691 * xSemaphoreCreateMutexStatic() then the application writer must provided the
695 * Mutexes created using this function can be accessed using the xSemaphoreTake()
696 * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and
700 * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
706 * used for pure synchronisation (where one task or interrupt always 'gives' the
707 * semaphore and another always 'takes' the semaphore) and from within interrupt
710 * @return If the mutex was successfully created then a handle to the created
711 * semaphore is returned. If there was not enough heap to allocate the mutex
721 * // This is a macro so pass the variable in directly.
726 * // The semaphore was created successfully.
727 * // The semaphore can now be used.
745 * the new mutex can be referenced.
747 * Internally, within the FreeRTOS implementation, mutex semaphores use a block
748 * of memory, in which the mutex structure is stored. If a mutex is created
749 * using xSemaphoreCreateMutex() then the required memory is automatically
750 * dynamically allocated inside the xSemaphoreCreateMutex() function. (see
752 * xSemaphoreCreateMutexStatic() then the application writer must provided the
756 * Mutexes created using this function can be accessed using the xSemaphoreTake()
757 * and xSemaphoreGive() macros. The xSemaphoreTakeRecursive() and
761 * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
767 * used for pure synchronisation (where one task or interrupt always 'gives' the
768 * semaphore and another always 'takes' the semaphore) and from within interrupt
772 * which will be used to hold the mutex's data structure, removing the need for
773 * the memory to be allocated dynamically.
775 * @return If the mutex was successfully created then a handle to the created
809 * by which the new recursive mutex can be referenced.
811 * Internally, within the FreeRTOS implementation, recursive mutexes use a block
812 * of memory, in which the mutex structure is stored. If a recursive mutex is
813 * created using xSemaphoreCreateRecursiveMutex() then the required memory is
814 * automatically dynamically allocated inside the
817 * xSemaphoreCreateRecursiveMutexStatic() then the application writer must
818 * provide the memory that will get used by the mutex.
822 * Mutexes created using this macro can be accessed using the
823 * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The
826 * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
827 * doesn't become available again until the owner has called
829 * if a task successfully 'takes' the same mutex 5 times then the mutex will
830 * not be available to any other task until it has also 'given' the mutex back
834 * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
840 * used for pure synchronisation (where one task or interrupt always 'gives' the
841 * semaphore and another always 'takes' the semaphore) and from within interrupt
844 * @return xSemaphore Handle to the created mutex semaphore. Should be of type
854 * // This is a macro so pass the variable in directly.
859 * // The semaphore was created successfully.
860 * // The semaphore can now be used.
878 * by which the new recursive mutex can be referenced.
880 * Internally, within the FreeRTOS implementation, recursive mutexes use a block
881 * of memory, in which the mutex structure is stored. If a recursive mutex is
882 * created using xSemaphoreCreateRecursiveMutex() then the required memory is
883 * automatically dynamically allocated inside the
886 * xSemaphoreCreateRecursiveMutexStatic() then the application writer must
887 * provide the memory that will get used by the mutex.
891 * Mutexes created using this macro can be accessed using the
892 * xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros. The
895 * A mutex used recursively can be 'taken' repeatedly by the owner. The mutex
896 * doesn't become available again until the owner has called
898 * if a task successfully 'takes' the same mutex 5 times then the mutex will
899 * not be available to any other task until it has also 'given' the mutex back
903 * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the
909 * used for pure synchronisation (where one task or interrupt always 'gives' the
910 * semaphore and another always 'takes' the semaphore) and from within interrupt
914 * which will then be used to hold the recursive mutex's data structure,
915 * removing the need for the memory to be allocated dynamically.
917 * @return If the recursive mutex was successfully created then a handle to the
930 * // The address of xMutexBuffer is passed into the function, and will hold
931 * // the mutexes data structures - so no dynamic memory allocation will be
952 * Creates a new counting semaphore instance, and returns a handle by which the
959 * Internally, within the FreeRTOS implementation, counting semaphores use a
960 * block of memory, in which the counting semaphore structure is stored. If a
961 * counting semaphore is created using xSemaphoreCreateCounting() then the
962 * required memory is automatically dynamically allocated inside the
965 * using xSemaphoreCreateCountingStatic() then the application writer can
966 * instead optionally provide the memory that will get used by the counting
975 * an event occurs (incrementing the semaphore count value), and a handler
977 * (decrementing the semaphore count value). The count value is therefore
978 * the difference between the number of events that have occurred and the
979 * number that have been processed. In this case it is desirable for the
984 * In this usage scenario the count value indicates the number of resources
986 * semaphore - decrementing the semaphore count value. When the count value
987 * reaches zero there are no free resources. When a task finishes with the
988 * resource it 'gives' the semaphore back - incrementing the semaphore count
989 * value. In this case it is desirable for the initial count value to be
990 * equal to the maximum count value, indicating that all resources are free.
992 * @param uxMaxCount The maximum count value that can be reached. When the
995 * @param uxInitialCount The count value assigned to the semaphore when it is
998 * @return Handle to the created semaphore. Null if the semaphore could not be
1010 * // The max value to which the semaphore can count should be 10, and the
1011 * // initial value assigned to the count should be 0.
1016 * // The semaphore was created successfully.
1017 * // The semaphore can now be used.
1034 * Creates a new counting semaphore instance, and returns a handle by which the
1041 * Internally, within the FreeRTOS implementation, counting semaphores use a
1042 * block of memory, in which the counting semaphore structure is stored. If a
1043 * counting semaphore is created using xSemaphoreCreateCounting() then the
1044 * required memory is automatically dynamically allocated inside the
1047 * using xSemaphoreCreateCountingStatic() then the application writer must
1048 * provide the memory. xSemaphoreCreateCountingStatic() therefore allows a
1056 * an event occurs (incrementing the semaphore count value), and a handler
1058 * (decrementing the semaphore count value). The count value is therefore
1059 * the difference between the number of events that have occurred and the
1060 * number that have been processed. In this case it is desirable for the
1065 * In this usage scenario the count value indicates the number of resources
1067 * semaphore - decrementing the semaphore count value. When the count value
1068 * reaches zero there are no free resources. When a task finishes with the
1069 * resource it 'gives' the semaphore back - incrementing the semaphore count
1070 * value. In this case it is desirable for the initial count value to be
1071 * equal to the maximum count value, indicating that all resources are free.
1073 * @param uxMaxCount The maximum count value that can be reached. When the
1076 * @param uxInitialCount The count value assigned to the semaphore when it is
1080 * which will then be used to hold the semaphore's data structure, removing the
1081 * need for the memory to be allocated dynamically.
1083 * @return If the counting semaphore was successfully created then a handle to
1084 * the created counting semaphore is returned. If pxSemaphoreBuffer was NULL
1097 * // a counting semaphore using xSemaphoreCreateCountingStatic(). The max
1098 * // value to which the semaphore can count is 10, and the initial value
1099 * // assigned to the count will be 0. The address of xSemaphoreBuffer is
1100 * // passed in and will be used to hold the semaphore structure, so no dynamic
1122 * do not delete a mutex type semaphore if the mutex is held by a task.
1124 * @param xSemaphore A handle to the semaphore to be deleted.
1137 * If xMutex is indeed a mutex type semaphore, return the current mutex holder.
1138 * If xMutex is not a mutex type semaphore, or the mutex is available (not held
1141 * Note: This is a good way of determining if the calling task is the mutex
1142 * holder, but not a good way of determining the identity of the mutex holder as
1143 * the holder may change between the function exiting and the returned value
1156 * If xMutex is indeed a mutex type semaphore, return the current mutex holder.
1157 * If xMutex is not a mutex type semaphore, or the mutex is available (not held
1171 * If the semaphore is a counting semaphore then uxSemaphoreGetCount() returns
1172 * its current count value. If the semaphore is a binary semaphore then
1173 * uxSemaphoreGetCount() returns 1 if the semaphore is available, and 0 if the
1185 * If the semaphore is a counting semaphore then uxSemaphoreGetCountFromISR() returns
1186 * its current count value. If the semaphore is a binary semaphore then
1187 * uxSemaphoreGetCountFromISR() returns 1 if the semaphore is available, and 0 if the
1201 * or mutex semaphore's data structure buffer. This is the same buffer that is
1202 * supplied at the time of creation.
1204 * @param xSemaphore The semaphore for which to retrieve the buffer.
1206 * @param ppxSemaphoreBuffer Used to return a pointer to the semaphore's