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.
39 /* The following bit fields convey control information in a task's event list
40 * item value. It is important they don't clash with the
68 * the status of various CAN bus related events in which bit 0 might mean "A CAN
69 * message has been received and is ready for processing", bit 1 might mean "The
70 * application has queued a message that is ready for sending onto the CAN
71 * network", and bit 2 might mean "It is time to send a SYNC message onto the
72 * CAN network" etc. A task can then test the bit values to see which events
73 * are active, and optionally enter the Blocked state to wait for a specified
74 * bit or a group of specified bits to be active. To continue the CAN bus
75 * example, a CAN controlling task can enter the Blocked state (and therefore
77 * active, at which time the bit that was actually active would inform the task
81 * The event groups implementation contains intelligence to avoid race
83 * variable for the same purpose. This is particularly important with respect
85 * be set and then tested atomically - as is the case where event groups are
106 * The type that holds event bits always matches TickType_t - therefore the
123 * Internally, within the FreeRTOS implementation, event groups use a [small]
124 * block of memory, in which the event group's structure is stored. If an event
125 * groups is created using xEventGroupCreate() then the required memory is
126 * automatically dynamically allocated inside the xEventGroupCreate() function.
128 * using xEventGroupCreateStatic() then the application writer must instead
129 * provide the memory that will get used by the event group.
134 * reasons the number of bits available for use in an event group is dependent
135 * on the configTICK_TYPE_WIDTH_IN_BITS setting in FreeRTOSConfig.h. If
139 * each event group has 56 usable bits (bit 0 to bit 53). The EventBits_t type
142 * @return If the event group was created then a handle to the event group is
143 * returned. If there was insufficient FreeRTOS heap available to create the
148 * // Declare a variable to hold the created event group.
151 * // Attempt to create the event group.
154 * // Was the event group created successfully?
157 * // The event group was not created because there was insufficient
162 * // The event group was created.
180 * Internally, within the FreeRTOS implementation, event groups use a [small]
181 * block of memory, in which the event group's structure is stored. If an event
182 * groups is created using xEventGroupCreate() then the required memory is
183 * automatically dynamically allocated inside the xEventGroupCreate() function.
185 * using xEventGroupCreateStatic() then the application writer must instead
186 * provide the memory that will get used by the event group.
191 * reasons the number of bits available for use in an event group is dependent
192 * on the configTICK_TYPE_WIDTH_IN_BITS setting in FreeRTOSConfig.h. If
196 * each event group has 56 usable bits (bit 0 to bit 53). The EventBits_t type
200 * StaticEventGroup_t, which will be then be used to hold the event group's data
201 * structures, removing the need for the memory to be allocated dynamically.
203 * @return If the event group was created then a handle to the event group is
208 * // StaticEventGroup_t is a publicly accessible structure that has the same
209 * // size and alignment requirements as the real event group structure. It is
210 * // provided as a mechanism for applications to know the size of the event
211 * // group (which is dependent on the architecture and configuration file
212 * // settings) without breaking the strict data hiding policy by exposing the
214 * // into the xSemaphoreCreateEventGroupStatic() function and is used to store
215 * // the event group's data structures
218 * // Create the event group without dynamically allocating any memory.
241 * @param xEventGroup The event group in which the bits are being tested. The
245 * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
246 * inside the event group. For example, to wait for bit 0 and/or bit 2 set
251 * uxBitsToWaitFor that are set within the event group will be cleared before
252 * xEventGroupWaitBits() returns if the wait condition was met (if the function
254 * pdFALSE then the bits set in the event group are not altered when the call to
258 * xEventGroupWaitBits() will return when either all the bits in uxBitsToWaitFor
259 * are set or the specified block time expires. If xWaitForAllBits is set to
260 * pdFALSE then xEventGroupWaitBits() will return when any one of the bits set
261 * in uxBitsToWaitFor is set or the specified block time expires. The block
262 * time is specified by the xTicksToWait parameter.
264 * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
265 * for one/all (depending on the xWaitForAllBits value) of the bits specified by
269 * @return The value of the event group at the time either the bits being waited
270 * for became set, or the block time expired. Test the return value to know
272 * expired then not all the bits being waited for will be set. If
273 * xEventGroupWaitBits() returned because the bits it was waiting for were set
274 * then the returned value is the event group value before any bits were
275 * automatically cleared in the case that xClearOnExit parameter was set to
289 * // the event group. Clear the bits before exiting.
291 * xEventGroup, // The event group being tested.
292 * BIT_0 | BIT_4, // The bits within the event group to wait for.
334 * @param xEventGroup The event group in which the bits are to be cleared.
336 * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear
337 * in the event group. For example, to clear bit 3 only, set uxBitsToClear to
340 * @return The value of the event group before the specified bits were cleared.
353 * xEventGroup, // The event group being updated.
354 * BIT_0 | BIT_4 );// The bits being cleared.
373 * // Neither bit 0 nor bit 4 were set in the first place.
392 * are an unknown number of tasks that may be waiting for the bit or bits being
395 * from tasks by suspending the scheduler rather than disabling interrupts. As
397 * routine. Therefore xEventGroupClearBitsFromISR() sends a message to the
398 * timer task to have the clear operation performed in the context of the timer
401 * @note If this function returns pdPASS then the timer task is ready to run
402 * and a portYIELD_FROM_ISR(pdTRUE) should be executed to perform the needed
403 * clear on the event group. This behavior is different from
404 * xEventGroupSetBitsFromISR because the parameter xHigherPriorityTaskWoken is
407 * @param xEventGroup The event group in which the bits are to be cleared.
409 * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear.
413 * @return If the request to execute the function was posted successfully then
415 * if the timer service queue was full.
430 * xEventGroup, // The event group being updated.
431 * BIT_0 | BIT_4 ); // The bits being set.
435 * // The message was posted successfully.
462 * blocked waiting for the bits.
464 * @param xEventGroup The event group in which the bits are to be set.
466 * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
470 * @return The value of the event group at the time the call to
471 * xEventGroupSetBits() returns. There are two reasons why the returned value
472 * might have the bits specified by the uxBitsToSet parameter cleared. First,
473 * if setting a bit results in a task that was waiting for the bit leaving the
474 * blocked state then it is possible the bit will be cleared automatically
475 * (see the xClearBitOnExit parameter of xEventGroupWaitBits()). Second, any
477 * the task that called xEventGroupSetBits() will execute and may change the
478 * event group value before the call to xEventGroupSetBits() returns.
491 * xEventGroup, // The event group being updated.
492 * BIT_0 | BIT_4 );// The bits being set.
496 * // Both bit 0 and bit 4 remained set when the function returned.
500 * // Bit 0 remained set when the function returned, but bit 4 was
502 * // task that was waiting for bit 4 was removed from the Blocked
507 * // Bit 4 remained set when the function returned, but bit 0 was
509 * // task that was waiting for bit 0 was removed from the Blocked
515 * // was waiting for both of the bits to be set, and the bits were
516 * // cleared as the task left the Blocked state.
535 * are an unknown number of tasks that may be waiting for the bit or bits being
538 * sends a message to the timer task to have the set operation performed in the
539 * context of the timer task - where a scheduler lock is used in place of a
542 * @param xEventGroup The event group in which the bits are to be set.
544 * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
549 * will result in a message being sent to the timer daemon task. If the
550 * priority of the timer daemon task is higher than the priority of the
551 * currently running task (the task the interrupt interrupted) then
554 * requested before the interrupt exits. For that reason
555 * *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the
558 * @return If the request to execute the function was posted successfully then
560 * if the timer service queue was full.
580 * xEventGroup, // The event group being updated.
581 * BIT_0 | BIT_4 // The bits being set.
584 * // Was the message posted successfully?
588 * // switch should be requested. The macro used is port specific and
590 * // refer to the documentation page for the port being used.
617 * bits to be set within the same event group. This functionality is typically
618 * used to synchronise multiple tasks, where each task has to wait for the other
623 * The function will return before its block time expires if the bits specified
624 * by the uxBitsToWait parameter are set, or become set within that time. In
625 * this case all the bits specified by uxBitsToWait will be automatically
626 * cleared before the function returns.
628 * @param xEventGroup The event group in which the bits are being tested. The
632 * @param uxBitsToSet The bits to set in the event group before determining
633 * if, and possibly waiting for, all the bits specified by the uxBitsToWait
636 * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
637 * inside the event group. For example, to wait for bit 0 and bit 2 set
641 * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
642 * for all of the bits specified by uxBitsToWaitFor to become set.
644 * @return The value of the event group at the time either the bits being waited
645 * for became set, or the block time expired. Test the return value to know
647 * expired then not all the bits being waited for will be set. If
648 * xEventGroupSync() returned because all the bits it was waiting for were
649 * set then the returned value is the event group value before any bits were
654 * // Bits used by the three tasks.
674 * // Set bit 0 in the event flag to note this task has reached the
675 * // sync point. The other two tasks will set the other two bits defined
676 * // by ALL_SYNC_BITS. All three tasks have reached the synchronisation
677 * // point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms
683 * // All three tasks reached the synchronisation point before the call
695 * // Set bit 1 in the event flag to note this task has reached the
696 * // synchronisation point. The other two tasks will set the other two
697 * // bits defined by ALL_SYNC_BITS. All three tasks have reached the
698 * // synchronisation point when all the ALL_SYNC_BITS are set. Wait
703 * // this task will only reach here if the synchronisation was made by all
704 * // three tasks, so there is no need to test the return value.
714 * // Set bit 2 in the event flag to note this task has reached the
715 * // synchronisation point. The other two tasks will set the other two
716 * // bits defined by ALL_SYNC_BITS. All three tasks have reached the
717 * // synchronisation point when all the ALL_SYNC_BITS are set. Wait
722 * // this task will only reach here if the synchronisation was made by all
723 * // three tasks, so there is no need to test the return value.
743 * Returns the current value of the bits in an event group. This function
746 * @param xEventGroup The event group being queried.
748 * @return The event group bits at the time xEventGroupGetBits() was called.
763 * @param xEventGroup The event group being queried.
765 * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
779 * xEventGroupCreate(). Tasks that are blocked on the event group will be
780 * unblocked and obtain 0 as the event group's value.
782 * @param xEventGroup The event group being deleted.
794 * buffer. It is the same buffer that is supplied at the time of creation.
796 * @param xEventGroup The event group for which to retrieve the buffer.
798 * @param ppxEventGroupBuffer Used to return a pointer to the event groups's
801 * @return pdTRUE if the buffer was retrieved, pdFALSE otherwise.