blob: 3a80d78564b01f954e0ca1a422b164509d7562bc [file] [log] [blame]
alfred gedeon9a1ebfe2020-08-17 16:16:11 -07001/*
Gaurav-Aggarwal-AWS2b0fdf22021-10-13 18:38:24 -07002 * FreeRTOS SMP Kernel V202110.00
alfred gedeon9a1ebfe2020-08-17 16:16:11 -07003 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 *
alfred gedeon0b0a2062020-08-20 14:59:28 -070022 * https://www.FreeRTOS.org
23 * https://github.com/FreeRTOS
alfred gedeon9a1ebfe2020-08-17 16:16:11 -070024 *
25 */
26
27#ifndef EVENT_GROUPS_H
28#define EVENT_GROUPS_H
29
30#ifndef INC_FREERTOS_H
31 #error "include FreeRTOS.h" must appear in source files before "include event_groups.h"
32#endif
33
34/* FreeRTOS includes. */
35#include "timers.h"
36
37/* *INDENT-OFF* */
38#ifdef __cplusplus
39 extern "C" {
40#endif
41/* *INDENT-ON* */
42
43/**
44 * An event group is a collection of bits to which an application can assign a
45 * meaning. For example, an application may create an event group to convey
46 * the status of various CAN bus related events in which bit 0 might mean "A CAN
47 * message has been received and is ready for processing", bit 1 might mean "The
48 * application has queued a message that is ready for sending onto the CAN
49 * network", and bit 2 might mean "It is time to send a SYNC message onto the
50 * CAN network" etc. A task can then test the bit values to see which events
51 * are active, and optionally enter the Blocked state to wait for a specified
52 * bit or a group of specified bits to be active. To continue the CAN bus
53 * example, a CAN controlling task can enter the Blocked state (and therefore
54 * not consume any processing time) until either bit 0, bit 1 or bit 2 are
55 * active, at which time the bit that was actually active would inform the task
56 * which action it had to take (process a received message, send a message, or
57 * send a SYNC).
58 *
59 * The event groups implementation contains intelligence to avoid race
60 * conditions that would otherwise occur were an application to use a simple
61 * variable for the same purpose. This is particularly important with respect
62 * to when a bit within an event group is to be cleared, and when bits have to
63 * be set and then tested atomically - as is the case where event groups are
64 * used to create a synchronisation point between multiple tasks (a
65 * 'rendezvous').
66 *
67 * \defgroup EventGroup
68 */
69
70
71
72/**
73 * event_groups.h
74 *
75 * Type by which event groups are referenced. For example, a call to
76 * xEventGroupCreate() returns an EventGroupHandle_t variable that can then
77 * be used as a parameter to other event group functions.
78 *
79 * \defgroup EventGroupHandle_t EventGroupHandle_t
80 * \ingroup EventGroup
81 */
82struct EventGroupDef_t;
83typedef struct EventGroupDef_t * EventGroupHandle_t;
84
85/*
86 * The type that holds event bits always matches TickType_t - therefore the
87 * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1,
88 * 32 bits if set to 0.
89 *
90 * \defgroup EventBits_t EventBits_t
91 * \ingroup EventGroup
92 */
93typedef TickType_t EventBits_t;
94
95/**
96 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -070097 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -070098 * EventGroupHandle_t xEventGroupCreate( void );
99 * </pre>
100 *
101 * Create a new event group.
102 *
103 * Internally, within the FreeRTOS implementation, event groups use a [small]
104 * block of memory, in which the event group's structure is stored. If an event
105 * groups is created using xEventGropuCreate() then the required memory is
106 * automatically dynamically allocated inside the xEventGroupCreate() function.
alfred gedeona0381462020-08-21 11:30:39 -0700107 * (see https://www.FreeRTOS.org/a00111.html). If an event group is created
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700108 * using xEventGropuCreateStatic() then the application writer must instead
109 * provide the memory that will get used by the event group.
110 * xEventGroupCreateStatic() therefore allows an event group to be created
111 * without using any dynamic memory allocation.
112 *
113 * Although event groups are not related to ticks, for internal implementation
114 * reasons the number of bits available for use in an event group is dependent
115 * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h. If
116 * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
117 * 0 to bit 7). If configUSE_16_BIT_TICKS is set to 0 then each event group has
118 * 24 usable bits (bit 0 to bit 23). The EventBits_t type is used to store
119 * event bits within an event group.
120 *
121 * @return If the event group was created then a handle to the event group is
122 * returned. If there was insufficient FreeRTOS heap available to create the
alfred gedeona0381462020-08-21 11:30:39 -0700123 * event group then NULL is returned. See https://www.FreeRTOS.org/a00111.html
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700124 *
125 * Example usage:
126 * <pre>
127 * // Declare a variable to hold the created event group.
128 * EventGroupHandle_t xCreatedEventGroup;
129 *
130 * // Attempt to create the event group.
131 * xCreatedEventGroup = xEventGroupCreate();
132 *
133 * // Was the event group created successfully?
134 * if( xCreatedEventGroup == NULL )
135 * {
136 * // The event group was not created because there was insufficient
137 * // FreeRTOS heap available.
138 * }
139 * else
140 * {
141 * // The event group was created.
142 * }
143 * </pre>
144 * \defgroup xEventGroupCreate xEventGroupCreate
145 * \ingroup EventGroup
146 */
147#if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
148 EventGroupHandle_t xEventGroupCreate( void ) PRIVILEGED_FUNCTION;
149#endif
150
151/**
152 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700153 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700154 * EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer );
155 * </pre>
156 *
157 * Create a new event group.
158 *
159 * Internally, within the FreeRTOS implementation, event groups use a [small]
160 * block of memory, in which the event group's structure is stored. If an event
161 * groups is created using xEventGropuCreate() then the required memory is
162 * automatically dynamically allocated inside the xEventGroupCreate() function.
alfred gedeona0381462020-08-21 11:30:39 -0700163 * (see https://www.FreeRTOS.org/a00111.html). If an event group is created
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700164 * using xEventGropuCreateStatic() then the application writer must instead
165 * provide the memory that will get used by the event group.
166 * xEventGroupCreateStatic() therefore allows an event group to be created
167 * without using any dynamic memory allocation.
168 *
169 * Although event groups are not related to ticks, for internal implementation
170 * reasons the number of bits available for use in an event group is dependent
171 * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h. If
172 * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
173 * 0 to bit 7). If configUSE_16_BIT_TICKS is set to 0 then each event group has
174 * 24 usable bits (bit 0 to bit 23). The EventBits_t type is used to store
175 * event bits within an event group.
176 *
177 * @param pxEventGroupBuffer pxEventGroupBuffer must point to a variable of type
178 * StaticEventGroup_t, which will be then be used to hold the event group's data
179 * structures, removing the need for the memory to be allocated dynamically.
180 *
181 * @return If the event group was created then a handle to the event group is
182 * returned. If pxEventGroupBuffer was NULL then NULL is returned.
183 *
184 * Example usage:
185 * <pre>
186 * // StaticEventGroup_t is a publicly accessible structure that has the same
187 * // size and alignment requirements as the real event group structure. It is
188 * // provided as a mechanism for applications to know the size of the event
189 * // group (which is dependent on the architecture and configuration file
190 * // settings) without breaking the strict data hiding policy by exposing the
191 * // real event group internals. This StaticEventGroup_t variable is passed
192 * // into the xSemaphoreCreateEventGroupStatic() function and is used to store
193 * // the event group's data structures
194 * StaticEventGroup_t xEventGroupBuffer;
195 *
196 * // Create the event group without dynamically allocating any memory.
197 * xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
198 * </pre>
199 */
200#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
201 EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t * pxEventGroupBuffer ) PRIVILEGED_FUNCTION;
202#endif
203
204/**
205 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700206 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700207 * EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
208 * const EventBits_t uxBitsToWaitFor,
209 * const BaseType_t xClearOnExit,
210 * const BaseType_t xWaitForAllBits,
211 * const TickType_t xTicksToWait );
212 * </pre>
213 *
214 * [Potentially] block to wait for one or more bits to be set within a
215 * previously created event group.
216 *
217 * This function cannot be called from an interrupt.
218 *
219 * @param xEventGroup The event group in which the bits are being tested. The
220 * event group must have previously been created using a call to
221 * xEventGroupCreate().
222 *
223 * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
224 * inside the event group. For example, to wait for bit 0 and/or bit 2 set
225 * uxBitsToWaitFor to 0x05. To wait for bits 0 and/or bit 1 and/or bit 2 set
226 * uxBitsToWaitFor to 0x07. Etc.
227 *
228 * @param xClearOnExit If xClearOnExit is set to pdTRUE then any bits within
229 * uxBitsToWaitFor that are set within the event group will be cleared before
230 * xEventGroupWaitBits() returns if the wait condition was met (if the function
231 * returns for a reason other than a timeout). If xClearOnExit is set to
232 * pdFALSE then the bits set in the event group are not altered when the call to
233 * xEventGroupWaitBits() returns.
234 *
235 * @param xWaitForAllBits If xWaitForAllBits is set to pdTRUE then
236 * xEventGroupWaitBits() will return when either all the bits in uxBitsToWaitFor
237 * are set or the specified block time expires. If xWaitForAllBits is set to
238 * pdFALSE then xEventGroupWaitBits() will return when any one of the bits set
239 * in uxBitsToWaitFor is set or the specified block time expires. The block
240 * time is specified by the xTicksToWait parameter.
241 *
242 * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
243 * for one/all (depending on the xWaitForAllBits value) of the bits specified by
244 * uxBitsToWaitFor to become set.
245 *
246 * @return The value of the event group at the time either the bits being waited
247 * for became set, or the block time expired. Test the return value to know
248 * which bits were set. If xEventGroupWaitBits() returned because its timeout
249 * expired then not all the bits being waited for will be set. If
250 * xEventGroupWaitBits() returned because the bits it was waiting for were set
251 * then the returned value is the event group value before any bits were
252 * automatically cleared in the case that xClearOnExit parameter was set to
253 * pdTRUE.
254 *
255 * Example usage:
256 * <pre>
257 #define BIT_0 ( 1 << 0 )
258 #define BIT_4 ( 1 << 4 )
259 *
260 * void aFunction( EventGroupHandle_t xEventGroup )
261 * {
262 * EventBits_t uxBits;
263 * const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
264 *
265 * // Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
266 * // the event group. Clear the bits before exiting.
267 * uxBits = xEventGroupWaitBits(
268 * xEventGroup, // The event group being tested.
269 * BIT_0 | BIT_4, // The bits within the event group to wait for.
270 * pdTRUE, // BIT_0 and BIT_4 should be cleared before returning.
271 * pdFALSE, // Don't wait for both bits, either bit will do.
272 * xTicksToWait ); // Wait a maximum of 100ms for either bit to be set.
273 *
274 * if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
275 * {
276 * // xEventGroupWaitBits() returned because both bits were set.
277 * }
278 * else if( ( uxBits & BIT_0 ) != 0 )
279 * {
280 * // xEventGroupWaitBits() returned because just BIT_0 was set.
281 * }
282 * else if( ( uxBits & BIT_4 ) != 0 )
283 * {
284 * // xEventGroupWaitBits() returned because just BIT_4 was set.
285 * }
286 * else
287 * {
288 * // xEventGroupWaitBits() returned because xTicksToWait ticks passed
289 * // without either BIT_0 or BIT_4 becoming set.
290 * }
291 * }
292 * </pre>
293 * \defgroup xEventGroupWaitBits xEventGroupWaitBits
294 * \ingroup EventGroup
295 */
296EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
297 const EventBits_t uxBitsToWaitFor,
298 const BaseType_t xClearOnExit,
299 const BaseType_t xWaitForAllBits,
300 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
301
302/**
303 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700304 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700305 * EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
306 * </pre>
307 *
308 * Clear bits within an event group. This function cannot be called from an
309 * interrupt.
310 *
311 * @param xEventGroup The event group in which the bits are to be cleared.
312 *
313 * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear
314 * in the event group. For example, to clear bit 3 only, set uxBitsToClear to
315 * 0x08. To clear bit 3 and bit 0 set uxBitsToClear to 0x09.
316 *
317 * @return The value of the event group before the specified bits were cleared.
318 *
319 * Example usage:
320 * <pre>
321 #define BIT_0 ( 1 << 0 )
322 #define BIT_4 ( 1 << 4 )
323 *
324 * void aFunction( EventGroupHandle_t xEventGroup )
325 * {
326 * EventBits_t uxBits;
327 *
328 * // Clear bit 0 and bit 4 in xEventGroup.
329 * uxBits = xEventGroupClearBits(
330 * xEventGroup, // The event group being updated.
331 * BIT_0 | BIT_4 );// The bits being cleared.
332 *
333 * if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
334 * {
335 * // Both bit 0 and bit 4 were set before xEventGroupClearBits() was
336 * // called. Both will now be clear (not set).
337 * }
338 * else if( ( uxBits & BIT_0 ) != 0 )
339 * {
340 * // Bit 0 was set before xEventGroupClearBits() was called. It will
341 * // now be clear.
342 * }
343 * else if( ( uxBits & BIT_4 ) != 0 )
344 * {
345 * // Bit 4 was set before xEventGroupClearBits() was called. It will
346 * // now be clear.
347 * }
348 * else
349 * {
350 * // Neither bit 0 nor bit 4 were set in the first place.
351 * }
352 * }
353 * </pre>
354 * \defgroup xEventGroupClearBits xEventGroupClearBits
355 * \ingroup EventGroup
356 */
357EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
358 const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
359
360/**
361 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700362 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700363 * BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
364 * </pre>
365 *
366 * A version of xEventGroupClearBits() that can be called from an interrupt.
367 *
368 * Setting bits in an event group is not a deterministic operation because there
369 * are an unknown number of tasks that may be waiting for the bit or bits being
370 * set. FreeRTOS does not allow nondeterministic operations to be performed
371 * while interrupts are disabled, so protects event groups that are accessed
372 * from tasks by suspending the scheduler rather than disabling interrupts. As
373 * a result event groups cannot be accessed directly from an interrupt service
374 * routine. Therefore xEventGroupClearBitsFromISR() sends a message to the
375 * timer task to have the clear operation performed in the context of the timer
376 * task.
377 *
378 * @param xEventGroup The event group in which the bits are to be cleared.
379 *
380 * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear.
381 * For example, to clear bit 3 only, set uxBitsToClear to 0x08. To clear bit 3
382 * and bit 0 set uxBitsToClear to 0x09.
383 *
384 * @return If the request to execute the function was posted successfully then
385 * pdPASS is returned, otherwise pdFALSE is returned. pdFALSE will be returned
386 * if the timer service queue was full.
387 *
388 * Example usage:
389 * <pre>
390 #define BIT_0 ( 1 << 0 )
391 #define BIT_4 ( 1 << 4 )
392 *
393 * // An event group which it is assumed has already been created by a call to
394 * // xEventGroupCreate().
395 * EventGroupHandle_t xEventGroup;
396 *
397 * void anInterruptHandler( void )
398 * {
399 * // Clear bit 0 and bit 4 in xEventGroup.
400 * xResult = xEventGroupClearBitsFromISR(
401 * xEventGroup, // The event group being updated.
402 * BIT_0 | BIT_4 ); // The bits being set.
403 *
404 * if( xResult == pdPASS )
405 * {
406 * // The message was posted successfully.
407 * }
408 * }
409 * </pre>
410 * \defgroup xEventGroupClearBitsFromISR xEventGroupClearBitsFromISR
411 * \ingroup EventGroup
412 */
413#if ( configUSE_TRACE_FACILITY == 1 )
414 BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup,
415 const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
416#else
417 #define xEventGroupClearBitsFromISR( xEventGroup, uxBitsToClear ) \
418 xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL )
419#endif
420
421/**
422 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700423 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700424 * EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
425 * </pre>
426 *
427 * Set bits within an event group.
428 * This function cannot be called from an interrupt. xEventGroupSetBitsFromISR()
429 * is a version that can be called from an interrupt.
430 *
431 * Setting bits in an event group will automatically unblock tasks that are
432 * blocked waiting for the bits.
433 *
434 * @param xEventGroup The event group in which the bits are to be set.
435 *
436 * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
437 * For example, to set bit 3 only, set uxBitsToSet to 0x08. To set bit 3
438 * and bit 0 set uxBitsToSet to 0x09.
439 *
440 * @return The value of the event group at the time the call to
441 * xEventGroupSetBits() returns. There are two reasons why the returned value
442 * might have the bits specified by the uxBitsToSet parameter cleared. First,
443 * if setting a bit results in a task that was waiting for the bit leaving the
444 * blocked state then it is possible the bit will be cleared automatically
445 * (see the xClearBitOnExit parameter of xEventGroupWaitBits()). Second, any
446 * unblocked (or otherwise Ready state) task that has a priority above that of
447 * the task that called xEventGroupSetBits() will execute and may change the
448 * event group value before the call to xEventGroupSetBits() returns.
449 *
450 * Example usage:
451 * <pre>
452 #define BIT_0 ( 1 << 0 )
453 #define BIT_4 ( 1 << 4 )
454 *
455 * void aFunction( EventGroupHandle_t xEventGroup )
456 * {
457 * EventBits_t uxBits;
458 *
459 * // Set bit 0 and bit 4 in xEventGroup.
460 * uxBits = xEventGroupSetBits(
461 * xEventGroup, // The event group being updated.
462 * BIT_0 | BIT_4 );// The bits being set.
463 *
464 * if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
465 * {
466 * // Both bit 0 and bit 4 remained set when the function returned.
467 * }
468 * else if( ( uxBits & BIT_0 ) != 0 )
469 * {
470 * // Bit 0 remained set when the function returned, but bit 4 was
471 * // cleared. It might be that bit 4 was cleared automatically as a
472 * // task that was waiting for bit 4 was removed from the Blocked
473 * // state.
474 * }
475 * else if( ( uxBits & BIT_4 ) != 0 )
476 * {
477 * // Bit 4 remained set when the function returned, but bit 0 was
478 * // cleared. It might be that bit 0 was cleared automatically as a
479 * // task that was waiting for bit 0 was removed from the Blocked
480 * // state.
481 * }
482 * else
483 * {
484 * // Neither bit 0 nor bit 4 remained set. It might be that a task
485 * // was waiting for both of the bits to be set, and the bits were
486 * // cleared as the task left the Blocked state.
487 * }
488 * }
489 * </pre>
490 * \defgroup xEventGroupSetBits xEventGroupSetBits
491 * \ingroup EventGroup
492 */
493EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
494 const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION;
495
496/**
497 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700498 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700499 * BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken );
500 * </pre>
501 *
502 * A version of xEventGroupSetBits() that can be called from an interrupt.
503 *
504 * Setting bits in an event group is not a deterministic operation because there
505 * are an unknown number of tasks that may be waiting for the bit or bits being
506 * set. FreeRTOS does not allow nondeterministic operations to be performed in
507 * interrupts or from critical sections. Therefore xEventGroupSetBitsFromISR()
508 * sends a message to the timer task to have the set operation performed in the
509 * context of the timer task - where a scheduler lock is used in place of a
510 * critical section.
511 *
512 * @param xEventGroup The event group in which the bits are to be set.
513 *
514 * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
515 * For example, to set bit 3 only, set uxBitsToSet to 0x08. To set bit 3
516 * and bit 0 set uxBitsToSet to 0x09.
517 *
518 * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
519 * will result in a message being sent to the timer daemon task. If the
520 * priority of the timer daemon task is higher than the priority of the
521 * currently running task (the task the interrupt interrupted) then
522 * *pxHigherPriorityTaskWoken will be set to pdTRUE by
523 * xEventGroupSetBitsFromISR(), indicating that a context switch should be
524 * requested before the interrupt exits. For that reason
525 * *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the
526 * example code below.
527 *
528 * @return If the request to execute the function was posted successfully then
529 * pdPASS is returned, otherwise pdFALSE is returned. pdFALSE will be returned
530 * if the timer service queue was full.
531 *
532 * Example usage:
533 * <pre>
534 #define BIT_0 ( 1 << 0 )
535 #define BIT_4 ( 1 << 4 )
536 *
537 * // An event group which it is assumed has already been created by a call to
538 * // xEventGroupCreate().
539 * EventGroupHandle_t xEventGroup;
540 *
541 * void anInterruptHandler( void )
542 * {
543 * BaseType_t xHigherPriorityTaskWoken, xResult;
544 *
545 * // xHigherPriorityTaskWoken must be initialised to pdFALSE.
546 * xHigherPriorityTaskWoken = pdFALSE;
547 *
548 * // Set bit 0 and bit 4 in xEventGroup.
549 * xResult = xEventGroupSetBitsFromISR(
550 * xEventGroup, // The event group being updated.
551 * BIT_0 | BIT_4 // The bits being set.
552 * &xHigherPriorityTaskWoken );
553 *
554 * // Was the message posted successfully?
555 * if( xResult == pdPASS )
556 * {
557 * // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
558 * // switch should be requested. The macro used is port specific and
559 * // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
560 * // refer to the documentation page for the port being used.
561 * portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
562 * }
563 * }
564 * </pre>
565 * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
566 * \ingroup EventGroup
567 */
568#if ( configUSE_TRACE_FACILITY == 1 )
569 BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
570 const EventBits_t uxBitsToSet,
571 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
572#else
573 #define xEventGroupSetBitsFromISR( xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken ) \
574 xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken )
575#endif
576
577/**
578 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700579 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700580 * EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
581 * const EventBits_t uxBitsToSet,
582 * const EventBits_t uxBitsToWaitFor,
583 * TickType_t xTicksToWait );
584 * </pre>
585 *
586 * Atomically set bits within an event group, then wait for a combination of
587 * bits to be set within the same event group. This functionality is typically
588 * used to synchronise multiple tasks, where each task has to wait for the other
589 * tasks to reach a synchronisation point before proceeding.
590 *
591 * This function cannot be used from an interrupt.
592 *
593 * The function will return before its block time expires if the bits specified
594 * by the uxBitsToWait parameter are set, or become set within that time. In
595 * this case all the bits specified by uxBitsToWait will be automatically
596 * cleared before the function returns.
597 *
598 * @param xEventGroup The event group in which the bits are being tested. The
599 * event group must have previously been created using a call to
600 * xEventGroupCreate().
601 *
602 * @param uxBitsToSet The bits to set in the event group before determining
603 * if, and possibly waiting for, all the bits specified by the uxBitsToWait
604 * parameter are set.
605 *
606 * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
607 * inside the event group. For example, to wait for bit 0 and bit 2 set
608 * uxBitsToWaitFor to 0x05. To wait for bits 0 and bit 1 and bit 2 set
609 * uxBitsToWaitFor to 0x07. Etc.
610 *
611 * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
612 * for all of the bits specified by uxBitsToWaitFor to become set.
613 *
614 * @return The value of the event group at the time either the bits being waited
615 * for became set, or the block time expired. Test the return value to know
616 * which bits were set. If xEventGroupSync() returned because its timeout
617 * expired then not all the bits being waited for will be set. If
618 * xEventGroupSync() returned because all the bits it was waiting for were
619 * set then the returned value is the event group value before any bits were
620 * automatically cleared.
621 *
622 * Example usage:
623 * <pre>
624 * // Bits used by the three tasks.
625 #define TASK_0_BIT ( 1 << 0 )
626 #define TASK_1_BIT ( 1 << 1 )
627 #define TASK_2_BIT ( 1 << 2 )
628 *
629 #define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
630 *
631 * // Use an event group to synchronise three tasks. It is assumed this event
632 * // group has already been created elsewhere.
633 * EventGroupHandle_t xEventBits;
634 *
635 * void vTask0( void *pvParameters )
636 * {
637 * EventBits_t uxReturn;
638 * TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
639 *
640 * for( ;; )
641 * {
642 * // Perform task functionality here.
643 *
644 * // Set bit 0 in the event flag to note this task has reached the
645 * // sync point. The other two tasks will set the other two bits defined
646 * // by ALL_SYNC_BITS. All three tasks have reached the synchronisation
647 * // point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms
648 * // for this to happen.
649 * uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );
650 *
651 * if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )
652 * {
653 * // All three tasks reached the synchronisation point before the call
654 * // to xEventGroupSync() timed out.
655 * }
656 * }
657 * }
658 *
659 * void vTask1( void *pvParameters )
660 * {
661 * for( ;; )
662 * {
663 * // Perform task functionality here.
664 *
665 * // Set bit 1 in the event flag to note this task has reached the
666 * // synchronisation point. The other two tasks will set the other two
667 * // bits defined by ALL_SYNC_BITS. All three tasks have reached the
668 * // synchronisation point when all the ALL_SYNC_BITS are set. Wait
669 * // indefinitely for this to happen.
670 * xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
671 *
672 * // xEventGroupSync() was called with an indefinite block time, so
Carl Lundinacee77b2020-09-16 11:17:39 -0700673 * // this task will only reach here if the synchronisation was made by all
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700674 * // three tasks, so there is no need to test the return value.
675 * }
676 * }
677 *
678 * void vTask2( void *pvParameters )
679 * {
680 * for( ;; )
681 * {
682 * // Perform task functionality here.
683 *
684 * // Set bit 2 in the event flag to note this task has reached the
685 * // synchronisation point. The other two tasks will set the other two
686 * // bits defined by ALL_SYNC_BITS. All three tasks have reached the
687 * // synchronisation point when all the ALL_SYNC_BITS are set. Wait
688 * // indefinitely for this to happen.
689 * xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
690 *
691 * // xEventGroupSync() was called with an indefinite block time, so
Carl Lundinacee77b2020-09-16 11:17:39 -0700692 * // this task will only reach here if the synchronisation was made by all
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700693 * // three tasks, so there is no need to test the return value.
694 * }
695 * }
696 *
697 * </pre>
698 * \defgroup xEventGroupSync xEventGroupSync
699 * \ingroup EventGroup
700 */
701EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
702 const EventBits_t uxBitsToSet,
703 const EventBits_t uxBitsToWaitFor,
704 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
705
706
707/**
708 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700709 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700710 * EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );
711 * </pre>
712 *
713 * Returns the current value of the bits in an event group. This function
714 * cannot be used from an interrupt.
715 *
716 * @param xEventGroup The event group being queried.
717 *
718 * @return The event group bits at the time xEventGroupGetBits() was called.
719 *
720 * \defgroup xEventGroupGetBits xEventGroupGetBits
721 * \ingroup EventGroup
722 */
723#define xEventGroupGetBits( xEventGroup ) xEventGroupClearBits( xEventGroup, 0 )
724
725/**
726 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700727 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700728 * EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
729 * </pre>
730 *
731 * A version of xEventGroupGetBits() that can be called from an ISR.
732 *
733 * @param xEventGroup The event group being queried.
734 *
735 * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
736 *
737 * \defgroup xEventGroupGetBitsFromISR xEventGroupGetBitsFromISR
738 * \ingroup EventGroup
739 */
740EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
741
742/**
743 * event_groups.h
David Chalcoebda4932020-08-18 16:28:02 -0700744 * <pre>
alfred gedeon9a1ebfe2020-08-17 16:16:11 -0700745 * void xEventGroupDelete( EventGroupHandle_t xEventGroup );
746 * </pre>
747 *
748 * Delete an event group that was previously created by a call to
749 * xEventGroupCreate(). Tasks that are blocked on the event group will be
750 * unblocked and obtain 0 as the event group's value.
751 *
752 * @param xEventGroup The event group being deleted.
753 */
754void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
755
756/* For internal use only. */
757void vEventGroupSetBitsCallback( void * pvEventGroup,
758 const uint32_t ulBitsToSet ) PRIVILEGED_FUNCTION;
759void vEventGroupClearBitsCallback( void * pvEventGroup,
760 const uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION;
761
762
763#if ( configUSE_TRACE_FACILITY == 1 )
764 UBaseType_t uxEventGroupGetNumber( void * xEventGroup ) PRIVILEGED_FUNCTION;
765 void vEventGroupSetNumber( void * xEventGroup,
766 UBaseType_t uxEventGroupNumber ) PRIVILEGED_FUNCTION;
767#endif
768
769/* *INDENT-OFF* */
770#ifdef __cplusplus
771 }
772#endif
773/* *INDENT-ON* */
774
775#endif /* EVENT_GROUPS_H */