Francisco Paez / freertos

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.

Dependents:   frdm_k64f_freertos_lib

src/include/event_groups.h@0:62cd296ba2a7, 2017-05-31 (annotated)

Committer:
fep
Date:
Wed May 31 02:27:10 2017 +0000
Revision:
0:62cd296ba2a7
FreeRTOS v9.0.0 for Cortex-M4F (FRDM-K64F and others...)

Who changed what in which revision?

UserRevisionLine numberNew contents of line
fep 0:62cd296ba2a7 1 /*
fep 0:62cd296ba2a7 2 FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd.
fep 0:62cd296ba2a7 3 All rights reserved
fep 0:62cd296ba2a7 4
fep 0:62cd296ba2a7 5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
fep 0:62cd296ba2a7 6
fep 0:62cd296ba2a7 7 This file is part of the FreeRTOS distribution.
fep 0:62cd296ba2a7 8
fep 0:62cd296ba2a7 9 FreeRTOS is free software; you can redistribute it and/or modify it under
fep 0:62cd296ba2a7 10 the terms of the GNU General Public License (version 2) as published by the
fep 0:62cd296ba2a7 11 Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.
fep 0:62cd296ba2a7 12
fep 0:62cd296ba2a7 13 ***************************************************************************
fep 0:62cd296ba2a7 14 >>! NOTE: The modification to the GPL is included to allow you to !<<
fep 0:62cd296ba2a7 15 >>! distribute a combined work that includes FreeRTOS without being !<<
fep 0:62cd296ba2a7 16 >>! obliged to provide the source code for proprietary components !<<
fep 0:62cd296ba2a7 17 >>! outside of the FreeRTOS kernel. !<<
fep 0:62cd296ba2a7 18 ***************************************************************************
fep 0:62cd296ba2a7 19
fep 0:62cd296ba2a7 20 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
fep 0:62cd296ba2a7 21 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
fep 0:62cd296ba2a7 22 FOR A PARTICULAR PURPOSE. Full license text is available on the following
fep 0:62cd296ba2a7 23 link: http://www.freertos.org/a00114.html
fep 0:62cd296ba2a7 24
fep 0:62cd296ba2a7 25 ***************************************************************************
fep 0:62cd296ba2a7 26 * *
fep 0:62cd296ba2a7 27 * FreeRTOS provides completely free yet professionally developed, *
fep 0:62cd296ba2a7 28 * robust, strictly quality controlled, supported, and cross *
fep 0:62cd296ba2a7 29 * platform software that is more than just the market leader, it *
fep 0:62cd296ba2a7 30 * is the industry's de facto standard. *
fep 0:62cd296ba2a7 31 * *
fep 0:62cd296ba2a7 32 * Help yourself get started quickly while simultaneously helping *
fep 0:62cd296ba2a7 33 * to support the FreeRTOS project by purchasing a FreeRTOS *
fep 0:62cd296ba2a7 34 * tutorial book, reference manual, or both: *
fep 0:62cd296ba2a7 35 * http://www.FreeRTOS.org/Documentation *
fep 0:62cd296ba2a7 36 * *
fep 0:62cd296ba2a7 37 ***************************************************************************
fep 0:62cd296ba2a7 38
fep 0:62cd296ba2a7 39 http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading
fep 0:62cd296ba2a7 40 the FAQ page "My application does not run, what could be wrong?". Have you
fep 0:62cd296ba2a7 41 defined configASSERT()?
fep 0:62cd296ba2a7 42
fep 0:62cd296ba2a7 43 http://www.FreeRTOS.org/support - In return for receiving this top quality
fep 0:62cd296ba2a7 44 embedded software for free we request you assist our global community by
fep 0:62cd296ba2a7 45 participating in the support forum.
fep 0:62cd296ba2a7 46
fep 0:62cd296ba2a7 47 http://www.FreeRTOS.org/training - Investing in training allows your team to
fep 0:62cd296ba2a7 48 be as productive as possible as early as possible. Now you can receive
fep 0:62cd296ba2a7 49 FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
fep 0:62cd296ba2a7 50 Ltd, and the world's leading authority on the world's leading RTOS.
fep 0:62cd296ba2a7 51
fep 0:62cd296ba2a7 52 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
fep 0:62cd296ba2a7 53 including FreeRTOS+Trace - an indispensable productivity tool, a DOS
fep 0:62cd296ba2a7 54 compatible FAT file system, and our tiny thread aware UDP/IP stack.
fep 0:62cd296ba2a7 55
fep 0:62cd296ba2a7 56 http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
fep 0:62cd296ba2a7 57 Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
fep 0:62cd296ba2a7 58
fep 0:62cd296ba2a7 59 http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
fep 0:62cd296ba2a7 60 Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS
fep 0:62cd296ba2a7 61 licenses offer ticketed support, indemnification and commercial middleware.
fep 0:62cd296ba2a7 62
fep 0:62cd296ba2a7 63 http://www.SafeRTOS.com - High Integrity Systems also provide a safety
fep 0:62cd296ba2a7 64 engineered and independently SIL3 certified version for use in safety and
fep 0:62cd296ba2a7 65 mission critical applications that require provable dependability.
fep 0:62cd296ba2a7 66
fep 0:62cd296ba2a7 67 1 tab == 4 spaces!
fep 0:62cd296ba2a7 68 */
fep 0:62cd296ba2a7 69
fep 0:62cd296ba2a7 70 #ifndef EVENT_GROUPS_H
fep 0:62cd296ba2a7 71 #define EVENT_GROUPS_H
fep 0:62cd296ba2a7 72
fep 0:62cd296ba2a7 73 #ifndef INC_FREERTOS_H
fep 0:62cd296ba2a7 74 #error "include FreeRTOS.h" must appear in source files before "include event_groups.h"
fep 0:62cd296ba2a7 75 #endif
fep 0:62cd296ba2a7 76
fep 0:62cd296ba2a7 77 /* FreeRTOS includes. */
fep 0:62cd296ba2a7 78 #include "timers.h"
fep 0:62cd296ba2a7 79
fep 0:62cd296ba2a7 80 #ifdef __cplusplus
fep 0:62cd296ba2a7 81 extern "C" {
fep 0:62cd296ba2a7 82 #endif
fep 0:62cd296ba2a7 83
fep 0:62cd296ba2a7 84 /**
fep 0:62cd296ba2a7 85 * An event group is a collection of bits to which an application can assign a
fep 0:62cd296ba2a7 86 * meaning. For example, an application may create an event group to convey
fep 0:62cd296ba2a7 87 * the status of various CAN bus related events in which bit 0 might mean "A CAN
fep 0:62cd296ba2a7 88 * message has been received and is ready for processing", bit 1 might mean "The
fep 0:62cd296ba2a7 89 * application has queued a message that is ready for sending onto the CAN
fep 0:62cd296ba2a7 90 * network", and bit 2 might mean "It is time to send a SYNC message onto the
fep 0:62cd296ba2a7 91 * CAN network" etc. A task can then test the bit values to see which events
fep 0:62cd296ba2a7 92 * are active, and optionally enter the Blocked state to wait for a specified
fep 0:62cd296ba2a7 93 * bit or a group of specified bits to be active. To continue the CAN bus
fep 0:62cd296ba2a7 94 * example, a CAN controlling task can enter the Blocked state (and therefore
fep 0:62cd296ba2a7 95 * not consume any processing time) until either bit 0, bit 1 or bit 2 are
fep 0:62cd296ba2a7 96 * active, at which time the bit that was actually active would inform the task
fep 0:62cd296ba2a7 97 * which action it had to take (process a received message, send a message, or
fep 0:62cd296ba2a7 98 * send a SYNC).
fep 0:62cd296ba2a7 99 *
fep 0:62cd296ba2a7 100 * The event groups implementation contains intelligence to avoid race
fep 0:62cd296ba2a7 101 * conditions that would otherwise occur were an application to use a simple
fep 0:62cd296ba2a7 102 * variable for the same purpose. This is particularly important with respect
fep 0:62cd296ba2a7 103 * to when a bit within an event group is to be cleared, and when bits have to
fep 0:62cd296ba2a7 104 * be set and then tested atomically - as is the case where event groups are
fep 0:62cd296ba2a7 105 * used to create a synchronisation point between multiple tasks (a
fep 0:62cd296ba2a7 106 * 'rendezvous').
fep 0:62cd296ba2a7 107 *
fep 0:62cd296ba2a7 108 * \defgroup EventGroup
fep 0:62cd296ba2a7 109 */
fep 0:62cd296ba2a7 110
fep 0:62cd296ba2a7 111
fep 0:62cd296ba2a7 112
fep 0:62cd296ba2a7 113 /**
fep 0:62cd296ba2a7 114 * event_groups.h
fep 0:62cd296ba2a7 115 *
fep 0:62cd296ba2a7 116 * Type by which event groups are referenced. For example, a call to
fep 0:62cd296ba2a7 117 * xEventGroupCreate() returns an EventGroupHandle_t variable that can then
fep 0:62cd296ba2a7 118 * be used as a parameter to other event group functions.
fep 0:62cd296ba2a7 119 *
fep 0:62cd296ba2a7 120 * \defgroup EventGroupHandle_t EventGroupHandle_t
fep 0:62cd296ba2a7 121 * \ingroup EventGroup
fep 0:62cd296ba2a7 122 */
fep 0:62cd296ba2a7 123 typedef void * EventGroupHandle_t;
fep 0:62cd296ba2a7 124
fep 0:62cd296ba2a7 125 /*
fep 0:62cd296ba2a7 126 * The type that holds event bits always matches TickType_t - therefore the
fep 0:62cd296ba2a7 127 * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1,
fep 0:62cd296ba2a7 128 * 32 bits if set to 0.
fep 0:62cd296ba2a7 129 *
fep 0:62cd296ba2a7 130 * \defgroup EventBits_t EventBits_t
fep 0:62cd296ba2a7 131 * \ingroup EventGroup
fep 0:62cd296ba2a7 132 */
fep 0:62cd296ba2a7 133 typedef TickType_t EventBits_t;
fep 0:62cd296ba2a7 134
fep 0:62cd296ba2a7 135 /**
fep 0:62cd296ba2a7 136 * event_groups.h
fep 0:62cd296ba2a7 137 *<pre>
fep 0:62cd296ba2a7 138 EventGroupHandle_t xEventGroupCreate( void );
fep 0:62cd296ba2a7 139 </pre>
fep 0:62cd296ba2a7 140 *
fep 0:62cd296ba2a7 141 * Create a new event group.
fep 0:62cd296ba2a7 142 *
fep 0:62cd296ba2a7 143 * Internally, within the FreeRTOS implementation, event groups use a [small]
fep 0:62cd296ba2a7 144 * block of memory, in which the event group's structure is stored. If an event
fep 0:62cd296ba2a7 145 * groups is created using xEventGropuCreate() then the required memory is
fep 0:62cd296ba2a7 146 * automatically dynamically allocated inside the xEventGroupCreate() function.
fep 0:62cd296ba2a7 147 * (see http://www.freertos.org/a00111.html). If an event group is created
fep 0:62cd296ba2a7 148 * using xEventGropuCreateStatic() then the application writer must instead
fep 0:62cd296ba2a7 149 * provide the memory that will get used by the event group.
fep 0:62cd296ba2a7 150 * xEventGroupCreateStatic() therefore allows an event group to be created
fep 0:62cd296ba2a7 151 * without using any dynamic memory allocation.
fep 0:62cd296ba2a7 152 *
fep 0:62cd296ba2a7 153 * Although event groups are not related to ticks, for internal implementation
fep 0:62cd296ba2a7 154 * reasons the number of bits available for use in an event group is dependent
fep 0:62cd296ba2a7 155 * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h. If
fep 0:62cd296ba2a7 156 * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
fep 0:62cd296ba2a7 157 * 0 to bit 7). If configUSE_16_BIT_TICKS is set to 0 then each event group has
fep 0:62cd296ba2a7 158 * 24 usable bits (bit 0 to bit 23). The EventBits_t type is used to store
fep 0:62cd296ba2a7 159 * event bits within an event group.
fep 0:62cd296ba2a7 160 *
fep 0:62cd296ba2a7 161 * @return If the event group was created then a handle to the event group is
fep 0:62cd296ba2a7 162 * returned. If there was insufficient FreeRTOS heap available to create the
fep 0:62cd296ba2a7 163 * event group then NULL is returned. See http://www.freertos.org/a00111.html
fep 0:62cd296ba2a7 164 *
fep 0:62cd296ba2a7 165 * Example usage:
fep 0:62cd296ba2a7 166 <pre>
fep 0:62cd296ba2a7 167 // Declare a variable to hold the created event group.
fep 0:62cd296ba2a7 168 EventGroupHandle_t xCreatedEventGroup;
fep 0:62cd296ba2a7 169
fep 0:62cd296ba2a7 170 // Attempt to create the event group.
fep 0:62cd296ba2a7 171 xCreatedEventGroup = xEventGroupCreate();
fep 0:62cd296ba2a7 172
fep 0:62cd296ba2a7 173 // Was the event group created successfully?
fep 0:62cd296ba2a7 174 if( xCreatedEventGroup == NULL )
fep 0:62cd296ba2a7 175 {
fep 0:62cd296ba2a7 176 // The event group was not created because there was insufficient
fep 0:62cd296ba2a7 177 // FreeRTOS heap available.
fep 0:62cd296ba2a7 178 }
fep 0:62cd296ba2a7 179 else
fep 0:62cd296ba2a7 180 {
fep 0:62cd296ba2a7 181 // The event group was created.
fep 0:62cd296ba2a7 182 }
fep 0:62cd296ba2a7 183 </pre>
fep 0:62cd296ba2a7 184 * \defgroup xEventGroupCreate xEventGroupCreate
fep 0:62cd296ba2a7 185 * \ingroup EventGroup
fep 0:62cd296ba2a7 186 */
fep 0:62cd296ba2a7 187 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
fep 0:62cd296ba2a7 188 EventGroupHandle_t xEventGroupCreate( void ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 189 #endif
fep 0:62cd296ba2a7 190
fep 0:62cd296ba2a7 191 /**
fep 0:62cd296ba2a7 192 * event_groups.h
fep 0:62cd296ba2a7 193 *<pre>
fep 0:62cd296ba2a7 194 EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer );
fep 0:62cd296ba2a7 195 </pre>
fep 0:62cd296ba2a7 196 *
fep 0:62cd296ba2a7 197 * Create a new event group.
fep 0:62cd296ba2a7 198 *
fep 0:62cd296ba2a7 199 * Internally, within the FreeRTOS implementation, event groups use a [small]
fep 0:62cd296ba2a7 200 * block of memory, in which the event group's structure is stored. If an event
fep 0:62cd296ba2a7 201 * groups is created using xEventGropuCreate() then the required memory is
fep 0:62cd296ba2a7 202 * automatically dynamically allocated inside the xEventGroupCreate() function.
fep 0:62cd296ba2a7 203 * (see http://www.freertos.org/a00111.html). If an event group is created
fep 0:62cd296ba2a7 204 * using xEventGropuCreateStatic() then the application writer must instead
fep 0:62cd296ba2a7 205 * provide the memory that will get used by the event group.
fep 0:62cd296ba2a7 206 * xEventGroupCreateStatic() therefore allows an event group to be created
fep 0:62cd296ba2a7 207 * without using any dynamic memory allocation.
fep 0:62cd296ba2a7 208 *
fep 0:62cd296ba2a7 209 * Although event groups are not related to ticks, for internal implementation
fep 0:62cd296ba2a7 210 * reasons the number of bits available for use in an event group is dependent
fep 0:62cd296ba2a7 211 * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h. If
fep 0:62cd296ba2a7 212 * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
fep 0:62cd296ba2a7 213 * 0 to bit 7). If configUSE_16_BIT_TICKS is set to 0 then each event group has
fep 0:62cd296ba2a7 214 * 24 usable bits (bit 0 to bit 23). The EventBits_t type is used to store
fep 0:62cd296ba2a7 215 * event bits within an event group.
fep 0:62cd296ba2a7 216 *
fep 0:62cd296ba2a7 217 * @param pxEventGroupBuffer pxEventGroupBuffer must point to a variable of type
fep 0:62cd296ba2a7 218 * StaticEventGroup_t, which will be then be used to hold the event group's data
fep 0:62cd296ba2a7 219 * structures, removing the need for the memory to be allocated dynamically.
fep 0:62cd296ba2a7 220 *
fep 0:62cd296ba2a7 221 * @return If the event group was created then a handle to the event group is
fep 0:62cd296ba2a7 222 * returned. If pxEventGroupBuffer was NULL then NULL is returned.
fep 0:62cd296ba2a7 223 *
fep 0:62cd296ba2a7 224 * Example usage:
fep 0:62cd296ba2a7 225 <pre>
fep 0:62cd296ba2a7 226 // StaticEventGroup_t is a publicly accessible structure that has the same
fep 0:62cd296ba2a7 227 // size and alignment requirements as the real event group structure. It is
fep 0:62cd296ba2a7 228 // provided as a mechanism for applications to know the size of the event
fep 0:62cd296ba2a7 229 // group (which is dependent on the architecture and configuration file
fep 0:62cd296ba2a7 230 // settings) without breaking the strict data hiding policy by exposing the
fep 0:62cd296ba2a7 231 // real event group internals. This StaticEventGroup_t variable is passed
fep 0:62cd296ba2a7 232 // into the xSemaphoreCreateEventGroupStatic() function and is used to store
fep 0:62cd296ba2a7 233 // the event group's data structures
fep 0:62cd296ba2a7 234 StaticEventGroup_t xEventGroupBuffer;
fep 0:62cd296ba2a7 235
fep 0:62cd296ba2a7 236 // Create the event group without dynamically allocating any memory.
fep 0:62cd296ba2a7 237 xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
fep 0:62cd296ba2a7 238 </pre>
fep 0:62cd296ba2a7 239 */
fep 0:62cd296ba2a7 240 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
fep 0:62cd296ba2a7 241 EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t *pxEventGroupBuffer ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 242 #endif
fep 0:62cd296ba2a7 243
fep 0:62cd296ba2a7 244 /**
fep 0:62cd296ba2a7 245 * event_groups.h
fep 0:62cd296ba2a7 246 *<pre>
fep 0:62cd296ba2a7 247 EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
fep 0:62cd296ba2a7 248 const EventBits_t uxBitsToWaitFor,
fep 0:62cd296ba2a7 249 const BaseType_t xClearOnExit,
fep 0:62cd296ba2a7 250 const BaseType_t xWaitForAllBits,
fep 0:62cd296ba2a7 251 const TickType_t xTicksToWait );
fep 0:62cd296ba2a7 252 </pre>
fep 0:62cd296ba2a7 253 *
fep 0:62cd296ba2a7 254 * [Potentially] block to wait for one or more bits to be set within a
fep 0:62cd296ba2a7 255 * previously created event group.
fep 0:62cd296ba2a7 256 *
fep 0:62cd296ba2a7 257 * This function cannot be called from an interrupt.
fep 0:62cd296ba2a7 258 *
fep 0:62cd296ba2a7 259 * @param xEventGroup The event group in which the bits are being tested. The
fep 0:62cd296ba2a7 260 * event group must have previously been created using a call to
fep 0:62cd296ba2a7 261 * xEventGroupCreate().
fep 0:62cd296ba2a7 262 *
fep 0:62cd296ba2a7 263 * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
fep 0:62cd296ba2a7 264 * inside the event group. For example, to wait for bit 0 and/or bit 2 set
fep 0:62cd296ba2a7 265 * uxBitsToWaitFor to 0x05. To wait for bits 0 and/or bit 1 and/or bit 2 set
fep 0:62cd296ba2a7 266 * uxBitsToWaitFor to 0x07. Etc.
fep 0:62cd296ba2a7 267 *
fep 0:62cd296ba2a7 268 * @param xClearOnExit If xClearOnExit is set to pdTRUE then any bits within
fep 0:62cd296ba2a7 269 * uxBitsToWaitFor that are set within the event group will be cleared before
fep 0:62cd296ba2a7 270 * xEventGroupWaitBits() returns if the wait condition was met (if the function
fep 0:62cd296ba2a7 271 * returns for a reason other than a timeout). If xClearOnExit is set to
fep 0:62cd296ba2a7 272 * pdFALSE then the bits set in the event group are not altered when the call to
fep 0:62cd296ba2a7 273 * xEventGroupWaitBits() returns.
fep 0:62cd296ba2a7 274 *
fep 0:62cd296ba2a7 275 * @param xWaitForAllBits If xWaitForAllBits is set to pdTRUE then
fep 0:62cd296ba2a7 276 * xEventGroupWaitBits() will return when either all the bits in uxBitsToWaitFor
fep 0:62cd296ba2a7 277 * are set or the specified block time expires. If xWaitForAllBits is set to
fep 0:62cd296ba2a7 278 * pdFALSE then xEventGroupWaitBits() will return when any one of the bits set
fep 0:62cd296ba2a7 279 * in uxBitsToWaitFor is set or the specified block time expires. The block
fep 0:62cd296ba2a7 280 * time is specified by the xTicksToWait parameter.
fep 0:62cd296ba2a7 281 *
fep 0:62cd296ba2a7 282 * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
fep 0:62cd296ba2a7 283 * for one/all (depending on the xWaitForAllBits value) of the bits specified by
fep 0:62cd296ba2a7 284 * uxBitsToWaitFor to become set.
fep 0:62cd296ba2a7 285 *
fep 0:62cd296ba2a7 286 * @return The value of the event group at the time either the bits being waited
fep 0:62cd296ba2a7 287 * for became set, or the block time expired. Test the return value to know
fep 0:62cd296ba2a7 288 * which bits were set. If xEventGroupWaitBits() returned because its timeout
fep 0:62cd296ba2a7 289 * expired then not all the bits being waited for will be set. If
fep 0:62cd296ba2a7 290 * xEventGroupWaitBits() returned because the bits it was waiting for were set
fep 0:62cd296ba2a7 291 * then the returned value is the event group value before any bits were
fep 0:62cd296ba2a7 292 * automatically cleared in the case that xClearOnExit parameter was set to
fep 0:62cd296ba2a7 293 * pdTRUE.
fep 0:62cd296ba2a7 294 *
fep 0:62cd296ba2a7 295 * Example usage:
fep 0:62cd296ba2a7 296 <pre>
fep 0:62cd296ba2a7 297 #define BIT_0 ( 1 << 0 )
fep 0:62cd296ba2a7 298 #define BIT_4 ( 1 << 4 )
fep 0:62cd296ba2a7 299
fep 0:62cd296ba2a7 300 void aFunction( EventGroupHandle_t xEventGroup )
fep 0:62cd296ba2a7 301 {
fep 0:62cd296ba2a7 302 EventBits_t uxBits;
fep 0:62cd296ba2a7 303 const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
fep 0:62cd296ba2a7 304
fep 0:62cd296ba2a7 305 // Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
fep 0:62cd296ba2a7 306 // the event group. Clear the bits before exiting.
fep 0:62cd296ba2a7 307 uxBits = xEventGroupWaitBits(
fep 0:62cd296ba2a7 308 xEventGroup, // The event group being tested.
fep 0:62cd296ba2a7 309 BIT_0 | BIT_4, // The bits within the event group to wait for.
fep 0:62cd296ba2a7 310 pdTRUE, // BIT_0 and BIT_4 should be cleared before returning.
fep 0:62cd296ba2a7 311 pdFALSE, // Don't wait for both bits, either bit will do.
fep 0:62cd296ba2a7 312 xTicksToWait ); // Wait a maximum of 100ms for either bit to be set.
fep 0:62cd296ba2a7 313
fep 0:62cd296ba2a7 314 if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
fep 0:62cd296ba2a7 315 {
fep 0:62cd296ba2a7 316 // xEventGroupWaitBits() returned because both bits were set.
fep 0:62cd296ba2a7 317 }
fep 0:62cd296ba2a7 318 else if( ( uxBits & BIT_0 ) != 0 )
fep 0:62cd296ba2a7 319 {
fep 0:62cd296ba2a7 320 // xEventGroupWaitBits() returned because just BIT_0 was set.
fep 0:62cd296ba2a7 321 }
fep 0:62cd296ba2a7 322 else if( ( uxBits & BIT_4 ) != 0 )
fep 0:62cd296ba2a7 323 {
fep 0:62cd296ba2a7 324 // xEventGroupWaitBits() returned because just BIT_4 was set.
fep 0:62cd296ba2a7 325 }
fep 0:62cd296ba2a7 326 else
fep 0:62cd296ba2a7 327 {
fep 0:62cd296ba2a7 328 // xEventGroupWaitBits() returned because xTicksToWait ticks passed
fep 0:62cd296ba2a7 329 // without either BIT_0 or BIT_4 becoming set.
fep 0:62cd296ba2a7 330 }
fep 0:62cd296ba2a7 331 }
fep 0:62cd296ba2a7 332 </pre>
fep 0:62cd296ba2a7 333 * \defgroup xEventGroupWaitBits xEventGroupWaitBits
fep 0:62cd296ba2a7 334 * \ingroup EventGroup
fep 0:62cd296ba2a7 335 */
fep 0:62cd296ba2a7 336 EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 337
fep 0:62cd296ba2a7 338 /**
fep 0:62cd296ba2a7 339 * event_groups.h
fep 0:62cd296ba2a7 340 *<pre>
fep 0:62cd296ba2a7 341 EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
fep 0:62cd296ba2a7 342 </pre>
fep 0:62cd296ba2a7 343 *
fep 0:62cd296ba2a7 344 * Clear bits within an event group. This function cannot be called from an
fep 0:62cd296ba2a7 345 * interrupt.
fep 0:62cd296ba2a7 346 *
fep 0:62cd296ba2a7 347 * @param xEventGroup The event group in which the bits are to be cleared.
fep 0:62cd296ba2a7 348 *
fep 0:62cd296ba2a7 349 * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear
fep 0:62cd296ba2a7 350 * in the event group. For example, to clear bit 3 only, set uxBitsToClear to
fep 0:62cd296ba2a7 351 * 0x08. To clear bit 3 and bit 0 set uxBitsToClear to 0x09.
fep 0:62cd296ba2a7 352 *
fep 0:62cd296ba2a7 353 * @return The value of the event group before the specified bits were cleared.
fep 0:62cd296ba2a7 354 *
fep 0:62cd296ba2a7 355 * Example usage:
fep 0:62cd296ba2a7 356 <pre>
fep 0:62cd296ba2a7 357 #define BIT_0 ( 1 << 0 )
fep 0:62cd296ba2a7 358 #define BIT_4 ( 1 << 4 )
fep 0:62cd296ba2a7 359
fep 0:62cd296ba2a7 360 void aFunction( EventGroupHandle_t xEventGroup )
fep 0:62cd296ba2a7 361 {
fep 0:62cd296ba2a7 362 EventBits_t uxBits;
fep 0:62cd296ba2a7 363
fep 0:62cd296ba2a7 364 // Clear bit 0 and bit 4 in xEventGroup.
fep 0:62cd296ba2a7 365 uxBits = xEventGroupClearBits(
fep 0:62cd296ba2a7 366 xEventGroup, // The event group being updated.
fep 0:62cd296ba2a7 367 BIT_0 | BIT_4 );// The bits being cleared.
fep 0:62cd296ba2a7 368
fep 0:62cd296ba2a7 369 if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
fep 0:62cd296ba2a7 370 {
fep 0:62cd296ba2a7 371 // Both bit 0 and bit 4 were set before xEventGroupClearBits() was
fep 0:62cd296ba2a7 372 // called. Both will now be clear (not set).
fep 0:62cd296ba2a7 373 }
fep 0:62cd296ba2a7 374 else if( ( uxBits & BIT_0 ) != 0 )
fep 0:62cd296ba2a7 375 {
fep 0:62cd296ba2a7 376 // Bit 0 was set before xEventGroupClearBits() was called. It will
fep 0:62cd296ba2a7 377 // now be clear.
fep 0:62cd296ba2a7 378 }
fep 0:62cd296ba2a7 379 else if( ( uxBits & BIT_4 ) != 0 )
fep 0:62cd296ba2a7 380 {
fep 0:62cd296ba2a7 381 // Bit 4 was set before xEventGroupClearBits() was called. It will
fep 0:62cd296ba2a7 382 // now be clear.
fep 0:62cd296ba2a7 383 }
fep 0:62cd296ba2a7 384 else
fep 0:62cd296ba2a7 385 {
fep 0:62cd296ba2a7 386 // Neither bit 0 nor bit 4 were set in the first place.
fep 0:62cd296ba2a7 387 }
fep 0:62cd296ba2a7 388 }
fep 0:62cd296ba2a7 389 </pre>
fep 0:62cd296ba2a7 390 * \defgroup xEventGroupClearBits xEventGroupClearBits
fep 0:62cd296ba2a7 391 * \ingroup EventGroup
fep 0:62cd296ba2a7 392 */
fep 0:62cd296ba2a7 393 EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 394
fep 0:62cd296ba2a7 395 /**
fep 0:62cd296ba2a7 396 * event_groups.h
fep 0:62cd296ba2a7 397 *<pre>
fep 0:62cd296ba2a7 398 BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
fep 0:62cd296ba2a7 399 </pre>
fep 0:62cd296ba2a7 400 *
fep 0:62cd296ba2a7 401 * A version of xEventGroupClearBits() that can be called from an interrupt.
fep 0:62cd296ba2a7 402 *
fep 0:62cd296ba2a7 403 * Setting bits in an event group is not a deterministic operation because there
fep 0:62cd296ba2a7 404 * are an unknown number of tasks that may be waiting for the bit or bits being
fep 0:62cd296ba2a7 405 * set. FreeRTOS does not allow nondeterministic operations to be performed
fep 0:62cd296ba2a7 406 * while interrupts are disabled, so protects event groups that are accessed
fep 0:62cd296ba2a7 407 * from tasks by suspending the scheduler rather than disabling interrupts. As
fep 0:62cd296ba2a7 408 * a result event groups cannot be accessed directly from an interrupt service
fep 0:62cd296ba2a7 409 * routine. Therefore xEventGroupClearBitsFromISR() sends a message to the
fep 0:62cd296ba2a7 410 * timer task to have the clear operation performed in the context of the timer
fep 0:62cd296ba2a7 411 * task.
fep 0:62cd296ba2a7 412 *
fep 0:62cd296ba2a7 413 * @param xEventGroup The event group in which the bits are to be cleared.
fep 0:62cd296ba2a7 414 *
fep 0:62cd296ba2a7 415 * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear.
fep 0:62cd296ba2a7 416 * For example, to clear bit 3 only, set uxBitsToClear to 0x08. To clear bit 3
fep 0:62cd296ba2a7 417 * and bit 0 set uxBitsToClear to 0x09.
fep 0:62cd296ba2a7 418 *
fep 0:62cd296ba2a7 419 * @return If the request to execute the function was posted successfully then
fep 0:62cd296ba2a7 420 * pdPASS is returned, otherwise pdFALSE is returned. pdFALSE will be returned
fep 0:62cd296ba2a7 421 * if the timer service queue was full.
fep 0:62cd296ba2a7 422 *
fep 0:62cd296ba2a7 423 * Example usage:
fep 0:62cd296ba2a7 424 <pre>
fep 0:62cd296ba2a7 425 #define BIT_0 ( 1 << 0 )
fep 0:62cd296ba2a7 426 #define BIT_4 ( 1 << 4 )
fep 0:62cd296ba2a7 427
fep 0:62cd296ba2a7 428 // An event group which it is assumed has already been created by a call to
fep 0:62cd296ba2a7 429 // xEventGroupCreate().
fep 0:62cd296ba2a7 430 EventGroupHandle_t xEventGroup;
fep 0:62cd296ba2a7 431
fep 0:62cd296ba2a7 432 void anInterruptHandler( void )
fep 0:62cd296ba2a7 433 {
fep 0:62cd296ba2a7 434 // Clear bit 0 and bit 4 in xEventGroup.
fep 0:62cd296ba2a7 435 xResult = xEventGroupClearBitsFromISR(
fep 0:62cd296ba2a7 436 xEventGroup, // The event group being updated.
fep 0:62cd296ba2a7 437 BIT_0 | BIT_4 ); // The bits being set.
fep 0:62cd296ba2a7 438
fep 0:62cd296ba2a7 439 if( xResult == pdPASS )
fep 0:62cd296ba2a7 440 {
fep 0:62cd296ba2a7 441 // The message was posted successfully.
fep 0:62cd296ba2a7 442 }
fep 0:62cd296ba2a7 443 }
fep 0:62cd296ba2a7 444 </pre>
fep 0:62cd296ba2a7 445 * \defgroup xEventGroupClearBitsFromISR xEventGroupClearBitsFromISR
fep 0:62cd296ba2a7 446 * \ingroup EventGroup
fep 0:62cd296ba2a7 447 */
fep 0:62cd296ba2a7 448 #if( configUSE_TRACE_FACILITY == 1 )
fep 0:62cd296ba2a7 449 BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 450 #else
fep 0:62cd296ba2a7 451 #define xEventGroupClearBitsFromISR( xEventGroup, uxBitsToClear ) xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL )
fep 0:62cd296ba2a7 452 #endif
fep 0:62cd296ba2a7 453
fep 0:62cd296ba2a7 454 /**
fep 0:62cd296ba2a7 455 * event_groups.h
fep 0:62cd296ba2a7 456 *<pre>
fep 0:62cd296ba2a7 457 EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
fep 0:62cd296ba2a7 458 </pre>
fep 0:62cd296ba2a7 459 *
fep 0:62cd296ba2a7 460 * Set bits within an event group.
fep 0:62cd296ba2a7 461 * This function cannot be called from an interrupt. xEventGroupSetBitsFromISR()
fep 0:62cd296ba2a7 462 * is a version that can be called from an interrupt.
fep 0:62cd296ba2a7 463 *
fep 0:62cd296ba2a7 464 * Setting bits in an event group will automatically unblock tasks that are
fep 0:62cd296ba2a7 465 * blocked waiting for the bits.
fep 0:62cd296ba2a7 466 *
fep 0:62cd296ba2a7 467 * @param xEventGroup The event group in which the bits are to be set.
fep 0:62cd296ba2a7 468 *
fep 0:62cd296ba2a7 469 * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
fep 0:62cd296ba2a7 470 * For example, to set bit 3 only, set uxBitsToSet to 0x08. To set bit 3
fep 0:62cd296ba2a7 471 * and bit 0 set uxBitsToSet to 0x09.
fep 0:62cd296ba2a7 472 *
fep 0:62cd296ba2a7 473 * @return The value of the event group at the time the call to
fep 0:62cd296ba2a7 474 * xEventGroupSetBits() returns. There are two reasons why the returned value
fep 0:62cd296ba2a7 475 * might have the bits specified by the uxBitsToSet parameter cleared. First,
fep 0:62cd296ba2a7 476 * if setting a bit results in a task that was waiting for the bit leaving the
fep 0:62cd296ba2a7 477 * blocked state then it is possible the bit will be cleared automatically
fep 0:62cd296ba2a7 478 * (see the xClearBitOnExit parameter of xEventGroupWaitBits()). Second, any
fep 0:62cd296ba2a7 479 * unblocked (or otherwise Ready state) task that has a priority above that of
fep 0:62cd296ba2a7 480 * the task that called xEventGroupSetBits() will execute and may change the
fep 0:62cd296ba2a7 481 * event group value before the call to xEventGroupSetBits() returns.
fep 0:62cd296ba2a7 482 *
fep 0:62cd296ba2a7 483 * Example usage:
fep 0:62cd296ba2a7 484 <pre>
fep 0:62cd296ba2a7 485 #define BIT_0 ( 1 << 0 )
fep 0:62cd296ba2a7 486 #define BIT_4 ( 1 << 4 )
fep 0:62cd296ba2a7 487
fep 0:62cd296ba2a7 488 void aFunction( EventGroupHandle_t xEventGroup )
fep 0:62cd296ba2a7 489 {
fep 0:62cd296ba2a7 490 EventBits_t uxBits;
fep 0:62cd296ba2a7 491
fep 0:62cd296ba2a7 492 // Set bit 0 and bit 4 in xEventGroup.
fep 0:62cd296ba2a7 493 uxBits = xEventGroupSetBits(
fep 0:62cd296ba2a7 494 xEventGroup, // The event group being updated.
fep 0:62cd296ba2a7 495 BIT_0 | BIT_4 );// The bits being set.
fep 0:62cd296ba2a7 496
fep 0:62cd296ba2a7 497 if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
fep 0:62cd296ba2a7 498 {
fep 0:62cd296ba2a7 499 // Both bit 0 and bit 4 remained set when the function returned.
fep 0:62cd296ba2a7 500 }
fep 0:62cd296ba2a7 501 else if( ( uxBits & BIT_0 ) != 0 )
fep 0:62cd296ba2a7 502 {
fep 0:62cd296ba2a7 503 // Bit 0 remained set when the function returned, but bit 4 was
fep 0:62cd296ba2a7 504 // cleared. It might be that bit 4 was cleared automatically as a
fep 0:62cd296ba2a7 505 // task that was waiting for bit 4 was removed from the Blocked
fep 0:62cd296ba2a7 506 // state.
fep 0:62cd296ba2a7 507 }
fep 0:62cd296ba2a7 508 else if( ( uxBits & BIT_4 ) != 0 )
fep 0:62cd296ba2a7 509 {
fep 0:62cd296ba2a7 510 // Bit 4 remained set when the function returned, but bit 0 was
fep 0:62cd296ba2a7 511 // cleared. It might be that bit 0 was cleared automatically as a
fep 0:62cd296ba2a7 512 // task that was waiting for bit 0 was removed from the Blocked
fep 0:62cd296ba2a7 513 // state.
fep 0:62cd296ba2a7 514 }
fep 0:62cd296ba2a7 515 else
fep 0:62cd296ba2a7 516 {
fep 0:62cd296ba2a7 517 // Neither bit 0 nor bit 4 remained set. It might be that a task
fep 0:62cd296ba2a7 518 // was waiting for both of the bits to be set, and the bits were
fep 0:62cd296ba2a7 519 // cleared as the task left the Blocked state.
fep 0:62cd296ba2a7 520 }
fep 0:62cd296ba2a7 521 }
fep 0:62cd296ba2a7 522 </pre>
fep 0:62cd296ba2a7 523 * \defgroup xEventGroupSetBits xEventGroupSetBits
fep 0:62cd296ba2a7 524 * \ingroup EventGroup
fep 0:62cd296ba2a7 525 */
fep 0:62cd296ba2a7 526 EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 527
fep 0:62cd296ba2a7 528 /**
fep 0:62cd296ba2a7 529 * event_groups.h
fep 0:62cd296ba2a7 530 *<pre>
fep 0:62cd296ba2a7 531 BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 532 </pre>
fep 0:62cd296ba2a7 533 *
fep 0:62cd296ba2a7 534 * A version of xEventGroupSetBits() that can be called from an interrupt.
fep 0:62cd296ba2a7 535 *
fep 0:62cd296ba2a7 536 * Setting bits in an event group is not a deterministic operation because there
fep 0:62cd296ba2a7 537 * are an unknown number of tasks that may be waiting for the bit or bits being
fep 0:62cd296ba2a7 538 * set. FreeRTOS does not allow nondeterministic operations to be performed in
fep 0:62cd296ba2a7 539 * interrupts or from critical sections. Therefore xEventGroupSetBitsFromISR()
fep 0:62cd296ba2a7 540 * sends a message to the timer task to have the set operation performed in the
fep 0:62cd296ba2a7 541 * context of the timer task - where a scheduler lock is used in place of a
fep 0:62cd296ba2a7 542 * critical section.
fep 0:62cd296ba2a7 543 *
fep 0:62cd296ba2a7 544 * @param xEventGroup The event group in which the bits are to be set.
fep 0:62cd296ba2a7 545 *
fep 0:62cd296ba2a7 546 * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
fep 0:62cd296ba2a7 547 * For example, to set bit 3 only, set uxBitsToSet to 0x08. To set bit 3
fep 0:62cd296ba2a7 548 * and bit 0 set uxBitsToSet to 0x09.
fep 0:62cd296ba2a7 549 *
fep 0:62cd296ba2a7 550 * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
fep 0:62cd296ba2a7 551 * will result in a message being sent to the timer daemon task. If the
fep 0:62cd296ba2a7 552 * priority of the timer daemon task is higher than the priority of the
fep 0:62cd296ba2a7 553 * currently running task (the task the interrupt interrupted) then
fep 0:62cd296ba2a7 554 * *pxHigherPriorityTaskWoken will be set to pdTRUE by
fep 0:62cd296ba2a7 555 * xEventGroupSetBitsFromISR(), indicating that a context switch should be
fep 0:62cd296ba2a7 556 * requested before the interrupt exits. For that reason
fep 0:62cd296ba2a7 557 * *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the
fep 0:62cd296ba2a7 558 * example code below.
fep 0:62cd296ba2a7 559 *
fep 0:62cd296ba2a7 560 * @return If the request to execute the function was posted successfully then
fep 0:62cd296ba2a7 561 * pdPASS is returned, otherwise pdFALSE is returned. pdFALSE will be returned
fep 0:62cd296ba2a7 562 * if the timer service queue was full.
fep 0:62cd296ba2a7 563 *
fep 0:62cd296ba2a7 564 * Example usage:
fep 0:62cd296ba2a7 565 <pre>
fep 0:62cd296ba2a7 566 #define BIT_0 ( 1 << 0 )
fep 0:62cd296ba2a7 567 #define BIT_4 ( 1 << 4 )
fep 0:62cd296ba2a7 568
fep 0:62cd296ba2a7 569 // An event group which it is assumed has already been created by a call to
fep 0:62cd296ba2a7 570 // xEventGroupCreate().
fep 0:62cd296ba2a7 571 EventGroupHandle_t xEventGroup;
fep 0:62cd296ba2a7 572
fep 0:62cd296ba2a7 573 void anInterruptHandler( void )
fep 0:62cd296ba2a7 574 {
fep 0:62cd296ba2a7 575 BaseType_t xHigherPriorityTaskWoken, xResult;
fep 0:62cd296ba2a7 576
fep 0:62cd296ba2a7 577 // xHigherPriorityTaskWoken must be initialised to pdFALSE.
fep 0:62cd296ba2a7 578 xHigherPriorityTaskWoken = pdFALSE;
fep 0:62cd296ba2a7 579
fep 0:62cd296ba2a7 580 // Set bit 0 and bit 4 in xEventGroup.
fep 0:62cd296ba2a7 581 xResult = xEventGroupSetBitsFromISR(
fep 0:62cd296ba2a7 582 xEventGroup, // The event group being updated.
fep 0:62cd296ba2a7 583 BIT_0 | BIT_4 // The bits being set.
fep 0:62cd296ba2a7 584 &xHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 585
fep 0:62cd296ba2a7 586 // Was the message posted successfully?
fep 0:62cd296ba2a7 587 if( xResult == pdPASS )
fep 0:62cd296ba2a7 588 {
fep 0:62cd296ba2a7 589 // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
fep 0:62cd296ba2a7 590 // switch should be requested. The macro used is port specific and
fep 0:62cd296ba2a7 591 // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
fep 0:62cd296ba2a7 592 // refer to the documentation page for the port being used.
fep 0:62cd296ba2a7 593 portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 594 }
fep 0:62cd296ba2a7 595 }
fep 0:62cd296ba2a7 596 </pre>
fep 0:62cd296ba2a7 597 * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
fep 0:62cd296ba2a7 598 * \ingroup EventGroup
fep 0:62cd296ba2a7 599 */
fep 0:62cd296ba2a7 600 #if( configUSE_TRACE_FACILITY == 1 )
fep 0:62cd296ba2a7 601 BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 602 #else
fep 0:62cd296ba2a7 603 #define xEventGroupSetBitsFromISR( xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken ) xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken )
fep 0:62cd296ba2a7 604 #endif
fep 0:62cd296ba2a7 605
fep 0:62cd296ba2a7 606 /**
fep 0:62cd296ba2a7 607 * event_groups.h
fep 0:62cd296ba2a7 608 *<pre>
fep 0:62cd296ba2a7 609 EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
fep 0:62cd296ba2a7 610 const EventBits_t uxBitsToSet,
fep 0:62cd296ba2a7 611 const EventBits_t uxBitsToWaitFor,
fep 0:62cd296ba2a7 612 TickType_t xTicksToWait );
fep 0:62cd296ba2a7 613 </pre>
fep 0:62cd296ba2a7 614 *
fep 0:62cd296ba2a7 615 * Atomically set bits within an event group, then wait for a combination of
fep 0:62cd296ba2a7 616 * bits to be set within the same event group. This functionality is typically
fep 0:62cd296ba2a7 617 * used to synchronise multiple tasks, where each task has to wait for the other
fep 0:62cd296ba2a7 618 * tasks to reach a synchronisation point before proceeding.
fep 0:62cd296ba2a7 619 *
fep 0:62cd296ba2a7 620 * This function cannot be used from an interrupt.
fep 0:62cd296ba2a7 621 *
fep 0:62cd296ba2a7 622 * The function will return before its block time expires if the bits specified
fep 0:62cd296ba2a7 623 * by the uxBitsToWait parameter are set, or become set within that time. In
fep 0:62cd296ba2a7 624 * this case all the bits specified by uxBitsToWait will be automatically
fep 0:62cd296ba2a7 625 * cleared before the function returns.
fep 0:62cd296ba2a7 626 *
fep 0:62cd296ba2a7 627 * @param xEventGroup The event group in which the bits are being tested. The
fep 0:62cd296ba2a7 628 * event group must have previously been created using a call to
fep 0:62cd296ba2a7 629 * xEventGroupCreate().
fep 0:62cd296ba2a7 630 *
fep 0:62cd296ba2a7 631 * @param uxBitsToSet The bits to set in the event group before determining
fep 0:62cd296ba2a7 632 * if, and possibly waiting for, all the bits specified by the uxBitsToWait
fep 0:62cd296ba2a7 633 * parameter are set.
fep 0:62cd296ba2a7 634 *
fep 0:62cd296ba2a7 635 * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
fep 0:62cd296ba2a7 636 * inside the event group. For example, to wait for bit 0 and bit 2 set
fep 0:62cd296ba2a7 637 * uxBitsToWaitFor to 0x05. To wait for bits 0 and bit 1 and bit 2 set
fep 0:62cd296ba2a7 638 * uxBitsToWaitFor to 0x07. Etc.
fep 0:62cd296ba2a7 639 *
fep 0:62cd296ba2a7 640 * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
fep 0:62cd296ba2a7 641 * for all of the bits specified by uxBitsToWaitFor to become set.
fep 0:62cd296ba2a7 642 *
fep 0:62cd296ba2a7 643 * @return The value of the event group at the time either the bits being waited
fep 0:62cd296ba2a7 644 * for became set, or the block time expired. Test the return value to know
fep 0:62cd296ba2a7 645 * which bits were set. If xEventGroupSync() returned because its timeout
fep 0:62cd296ba2a7 646 * expired then not all the bits being waited for will be set. If
fep 0:62cd296ba2a7 647 * xEventGroupSync() returned because all the bits it was waiting for were
fep 0:62cd296ba2a7 648 * set then the returned value is the event group value before any bits were
fep 0:62cd296ba2a7 649 * automatically cleared.
fep 0:62cd296ba2a7 650 *
fep 0:62cd296ba2a7 651 * Example usage:
fep 0:62cd296ba2a7 652 <pre>
fep 0:62cd296ba2a7 653 // Bits used by the three tasks.
fep 0:62cd296ba2a7 654 #define TASK_0_BIT ( 1 << 0 )
fep 0:62cd296ba2a7 655 #define TASK_1_BIT ( 1 << 1 )
fep 0:62cd296ba2a7 656 #define TASK_2_BIT ( 1 << 2 )
fep 0:62cd296ba2a7 657
fep 0:62cd296ba2a7 658 #define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
fep 0:62cd296ba2a7 659
fep 0:62cd296ba2a7 660 // Use an event group to synchronise three tasks. It is assumed this event
fep 0:62cd296ba2a7 661 // group has already been created elsewhere.
fep 0:62cd296ba2a7 662 EventGroupHandle_t xEventBits;
fep 0:62cd296ba2a7 663
fep 0:62cd296ba2a7 664 void vTask0( void *pvParameters )
fep 0:62cd296ba2a7 665 {
fep 0:62cd296ba2a7 666 EventBits_t uxReturn;
fep 0:62cd296ba2a7 667 TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
fep 0:62cd296ba2a7 668
fep 0:62cd296ba2a7 669 for( ;; )
fep 0:62cd296ba2a7 670 {
fep 0:62cd296ba2a7 671 // Perform task functionality here.
fep 0:62cd296ba2a7 672
fep 0:62cd296ba2a7 673 // Set bit 0 in the event flag to note this task has reached the
fep 0:62cd296ba2a7 674 // sync point. The other two tasks will set the other two bits defined
fep 0:62cd296ba2a7 675 // by ALL_SYNC_BITS. All three tasks have reached the synchronisation
fep 0:62cd296ba2a7 676 // point when all the ALL_SYNC_BITS are set. Wait a maximum of 100ms
fep 0:62cd296ba2a7 677 // for this to happen.
fep 0:62cd296ba2a7 678 uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );
fep 0:62cd296ba2a7 679
fep 0:62cd296ba2a7 680 if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )
fep 0:62cd296ba2a7 681 {
fep 0:62cd296ba2a7 682 // All three tasks reached the synchronisation point before the call
fep 0:62cd296ba2a7 683 // to xEventGroupSync() timed out.
fep 0:62cd296ba2a7 684 }
fep 0:62cd296ba2a7 685 }
fep 0:62cd296ba2a7 686 }
fep 0:62cd296ba2a7 687
fep 0:62cd296ba2a7 688 void vTask1( void *pvParameters )
fep 0:62cd296ba2a7 689 {
fep 0:62cd296ba2a7 690 for( ;; )
fep 0:62cd296ba2a7 691 {
fep 0:62cd296ba2a7 692 // Perform task functionality here.
fep 0:62cd296ba2a7 693
fep 0:62cd296ba2a7 694 // Set bit 1 in the event flag to note this task has reached the
fep 0:62cd296ba2a7 695 // synchronisation point. The other two tasks will set the other two
fep 0:62cd296ba2a7 696 // bits defined by ALL_SYNC_BITS. All three tasks have reached the
fep 0:62cd296ba2a7 697 // synchronisation point when all the ALL_SYNC_BITS are set. Wait
fep 0:62cd296ba2a7 698 // indefinitely for this to happen.
fep 0:62cd296ba2a7 699 xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
fep 0:62cd296ba2a7 700
fep 0:62cd296ba2a7 701 // xEventGroupSync() was called with an indefinite block time, so
fep 0:62cd296ba2a7 702 // this task will only reach here if the syncrhonisation was made by all
fep 0:62cd296ba2a7 703 // three tasks, so there is no need to test the return value.
fep 0:62cd296ba2a7 704 }
fep 0:62cd296ba2a7 705 }
fep 0:62cd296ba2a7 706
fep 0:62cd296ba2a7 707 void vTask2( void *pvParameters )
fep 0:62cd296ba2a7 708 {
fep 0:62cd296ba2a7 709 for( ;; )
fep 0:62cd296ba2a7 710 {
fep 0:62cd296ba2a7 711 // Perform task functionality here.
fep 0:62cd296ba2a7 712
fep 0:62cd296ba2a7 713 // Set bit 2 in the event flag to note this task has reached the
fep 0:62cd296ba2a7 714 // synchronisation point. The other two tasks will set the other two
fep 0:62cd296ba2a7 715 // bits defined by ALL_SYNC_BITS. All three tasks have reached the
fep 0:62cd296ba2a7 716 // synchronisation point when all the ALL_SYNC_BITS are set. Wait
fep 0:62cd296ba2a7 717 // indefinitely for this to happen.
fep 0:62cd296ba2a7 718 xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
fep 0:62cd296ba2a7 719
fep 0:62cd296ba2a7 720 // xEventGroupSync() was called with an indefinite block time, so
fep 0:62cd296ba2a7 721 // this task will only reach here if the syncrhonisation was made by all
fep 0:62cd296ba2a7 722 // three tasks, so there is no need to test the return value.
fep 0:62cd296ba2a7 723 }
fep 0:62cd296ba2a7 724 }
fep 0:62cd296ba2a7 725
fep 0:62cd296ba2a7 726 </pre>
fep 0:62cd296ba2a7 727 * \defgroup xEventGroupSync xEventGroupSync
fep 0:62cd296ba2a7 728 * \ingroup EventGroup
fep 0:62cd296ba2a7 729 */
fep 0:62cd296ba2a7 730 EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 731
fep 0:62cd296ba2a7 732
fep 0:62cd296ba2a7 733 /**
fep 0:62cd296ba2a7 734 * event_groups.h
fep 0:62cd296ba2a7 735 *<pre>
fep 0:62cd296ba2a7 736 EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );
fep 0:62cd296ba2a7 737 </pre>
fep 0:62cd296ba2a7 738 *
fep 0:62cd296ba2a7 739 * Returns the current value of the bits in an event group. This function
fep 0:62cd296ba2a7 740 * cannot be used from an interrupt.
fep 0:62cd296ba2a7 741 *
fep 0:62cd296ba2a7 742 * @param xEventGroup The event group being queried.
fep 0:62cd296ba2a7 743 *
fep 0:62cd296ba2a7 744 * @return The event group bits at the time xEventGroupGetBits() was called.
fep 0:62cd296ba2a7 745 *
fep 0:62cd296ba2a7 746 * \defgroup xEventGroupGetBits xEventGroupGetBits
fep 0:62cd296ba2a7 747 * \ingroup EventGroup
fep 0:62cd296ba2a7 748 */
fep 0:62cd296ba2a7 749 #define xEventGroupGetBits( xEventGroup ) xEventGroupClearBits( xEventGroup, 0 )
fep 0:62cd296ba2a7 750
fep 0:62cd296ba2a7 751 /**
fep 0:62cd296ba2a7 752 * event_groups.h
fep 0:62cd296ba2a7 753 *<pre>
fep 0:62cd296ba2a7 754 EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
fep 0:62cd296ba2a7 755 </pre>
fep 0:62cd296ba2a7 756 *
fep 0:62cd296ba2a7 757 * A version of xEventGroupGetBits() that can be called from an ISR.
fep 0:62cd296ba2a7 758 *
fep 0:62cd296ba2a7 759 * @param xEventGroup The event group being queried.
fep 0:62cd296ba2a7 760 *
fep 0:62cd296ba2a7 761 * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
fep 0:62cd296ba2a7 762 *
fep 0:62cd296ba2a7 763 * \defgroup xEventGroupGetBitsFromISR xEventGroupGetBitsFromISR
fep 0:62cd296ba2a7 764 * \ingroup EventGroup
fep 0:62cd296ba2a7 765 */
fep 0:62cd296ba2a7 766 EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 767
fep 0:62cd296ba2a7 768 /**
fep 0:62cd296ba2a7 769 * event_groups.h
fep 0:62cd296ba2a7 770 *<pre>
fep 0:62cd296ba2a7 771 void xEventGroupDelete( EventGroupHandle_t xEventGroup );
fep 0:62cd296ba2a7 772 </pre>
fep 0:62cd296ba2a7 773 *
fep 0:62cd296ba2a7 774 * Delete an event group that was previously created by a call to
fep 0:62cd296ba2a7 775 * xEventGroupCreate(). Tasks that are blocked on the event group will be
fep 0:62cd296ba2a7 776 * unblocked and obtain 0 as the event group's value.
fep 0:62cd296ba2a7 777 *
fep 0:62cd296ba2a7 778 * @param xEventGroup The event group being deleted.
fep 0:62cd296ba2a7 779 */
fep 0:62cd296ba2a7 780 void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 781
fep 0:62cd296ba2a7 782 /* For internal use only. */
fep 0:62cd296ba2a7 783 void vEventGroupSetBitsCallback( void *pvEventGroup, const uint32_t ulBitsToSet ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 784 void vEventGroupClearBitsCallback( void *pvEventGroup, const uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 785
fep 0:62cd296ba2a7 786
fep 0:62cd296ba2a7 787 #if (configUSE_TRACE_FACILITY == 1)
fep 0:62cd296ba2a7 788 UBaseType_t uxEventGroupGetNumber( void* xEventGroup ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 789 #endif
fep 0:62cd296ba2a7 790
fep 0:62cd296ba2a7 791 #ifdef __cplusplus
fep 0:62cd296ba2a7 792 }
fep 0:62cd296ba2a7 793 #endif
fep 0:62cd296ba2a7 794
fep 0:62cd296ba2a7 795 #endif /* EVENT_GROUPS_H */
fep 0:62cd296ba2a7 796
fep 0:62cd296ba2a7 797
fep 0:62cd296ba2a7 798