2 FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd.
\r
5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
\r
7 ***************************************************************************
\r
9 * FreeRTOS provides completely free yet professionally developed, *
\r
10 * robust, strictly quality controlled, supported, and cross *
\r
11 * platform software that has become a de facto standard. *
\r
13 * Help yourself get started quickly and support the FreeRTOS *
\r
14 * project by purchasing a FreeRTOS tutorial book, reference *
\r
15 * manual, or both from: http://www.FreeRTOS.org/Documentation *
\r
19 ***************************************************************************
\r
21 This file is part of the FreeRTOS distribution.
\r
23 FreeRTOS is free software; you can redistribute it and/or modify it under
\r
24 the terms of the GNU General Public License (version 2) as published by the
\r
25 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.
\r
27 >>! NOTE: The modification to the GPL is included to allow you to distribute
\r
28 >>! a combined work that includes FreeRTOS without being obliged to provide
\r
29 >>! the source code for proprietary components outside of the FreeRTOS
\r
32 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
\r
33 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
\r
34 FOR A PARTICULAR PURPOSE. Full license text is available from the following
\r
35 link: http://www.freertos.org/a00114.html
\r
39 ***************************************************************************
\r
41 * Having a problem? Start by reading the FAQ "My application does *
\r
42 * not run, what could be wrong?" *
\r
44 * http://www.FreeRTOS.org/FAQHelp.html *
\r
46 ***************************************************************************
\r
48 http://www.FreeRTOS.org - Documentation, books, training, latest versions,
\r
49 license and Real Time Engineers Ltd. contact details.
\r
51 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
\r
52 including FreeRTOS+Trace - an indispensable productivity tool, a DOS
\r
53 compatible FAT file system, and our tiny thread aware UDP/IP stack.
\r
55 http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High
\r
56 Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS
\r
57 licenses offer ticketed support, indemnification and middleware.
\r
59 http://www.SafeRTOS.com - High Integrity Systems also provide a safety
\r
60 engineered and independently SIL3 certified version for use in safety and
\r
61 mission critical applications that require provable dependability.
\r
66 /* Standard includes. */
\r
69 /* Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
\r
70 all the API functions to use the MPU wrappers. That should only be done when
\r
71 task.h is included from an application file. */
\r
72 #define MPU_WRAPPERS_INCLUDED_FROM_API_FILE
\r
74 /* FreeRTOS includes. */
\r
75 #include "FreeRTOS.h"
\r
78 #include "event_groups.h"
\r
80 /* Lint e961 and e750 are suppressed as a MISRA exception justified because the
\r
81 MPU ports require MPU_WRAPPERS_INCLUDED_FROM_API_FILE to be defined for the
\r
82 header files above, but not in this file, in order to generate the correct
\r
83 privileged Vs unprivileged linkage and placement. */
\r
84 #undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE /*lint !e961 !e750. */
\r
86 #if ( INCLUDE_xEventGroupSetBitFromISR == 1 ) && ( configUSE_TIMERS == 0 )
\r
87 #error configUSE_TIMERS must be set to 1 to make the xEventGroupSetBitFromISR() function available.
\r
90 #if ( INCLUDE_xEventGroupSetBitFromISR == 1 ) && ( INCLUDE_xTimerPendCallbackFromISR == 0 )
\r
91 #error INCLUDE_xTimerPendCallbackFromISR must also be set to one to make the xEventGroupSetBitFromISR() function available.
\r
94 /* The following bit fields convey control information in a task's event list
\r
95 item value. It is important they don't clash with the
\r
96 taskEVENT_LIST_ITEM_VALUE_IN_USE definition. */
\r
97 #if configUSE_16_BIT_TICKS == 1
\r
98 #define eventCLEAR_EVENTS_ON_EXIT_BIT 0x0100U
\r
99 #define eventUNBLOCKED_DUE_TO_BIT_SET 0x0200U
\r
100 #define eventWAIT_FOR_ALL_BITS 0x0400U
\r
101 #define eventEVENT_BITS_CONTROL_BYTES 0xff00U
\r
103 #define eventCLEAR_EVENTS_ON_EXIT_BIT 0x01000000UL
\r
104 #define eventUNBLOCKED_DUE_TO_BIT_SET 0x02000000UL
\r
105 #define eventWAIT_FOR_ALL_BITS 0x04000000UL
\r
106 #define eventEVENT_BITS_CONTROL_BYTES 0xff000000UL
\r
109 typedef struct EVENT_GROUP_DEFINITION
\r
111 EventBits_t uxEventBits;
\r
112 List_t xTasksWaitingForBits; /*< List of tasks waiting for a bit to be set. */
\r
115 /*-----------------------------------------------------------*/
\r
118 * Test the bits set in uxCurrentEventBits to see if the wait condition is met.
\r
119 * The wait condition is defined by xWaitForAllBits. If xWaitForAllBits is
\r
120 * pdTRUE then the wait condition is met if all the bits set in uxBitsToWaitFor
\r
121 * are also set in uxCurrentEventBits. If xWaitForAllBits is pdFALSE then the
\r
122 * wait condition is met if any of the bits set in uxBitsToWait for are also set
\r
123 * in uxCurrentEventBits.
\r
125 static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits, const EventBits_t uxBitsToWaitFor, const BaseType_t xWaitForAllBits );
\r
127 /*-----------------------------------------------------------*/
\r
129 EventGroupHandle_t xEventGroupCreate( void )
\r
131 EventGroup_t *pxEventBits;
\r
133 pxEventBits = pvPortMalloc( sizeof( EventGroup_t ) );
\r
134 if( pxEventBits != NULL )
\r
136 pxEventBits->uxEventBits = 0;
\r
137 vListInitialise( &( pxEventBits->xTasksWaitingForBits ) );
\r
138 traceEVENT_GROUP_CREATE( pxEventBits );
\r
142 traceEVENT_GROUP_CREATE_FAILED();
\r
145 return ( EventGroupHandle_t ) pxEventBits;
\r
147 /*-----------------------------------------------------------*/
\r
149 EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait )
\r
151 EventBits_t uxOriginalBitValue, uxReturn;
\r
152 EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
\r
153 BaseType_t xAlreadyYielded;
\r
155 configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
\r
156 configASSERT( uxBitsToWaitFor != 0 );
\r
157 #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
\r
159 configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
\r
165 traceEVENT_GROUP_SYNC_START( xEventGroup, uxBitsToSet );
\r
167 uxOriginalBitValue = pxEventBits->uxEventBits;
\r
169 ( void ) xEventGroupSetBits( xEventGroup, uxBitsToSet );
\r
171 if( ( ( uxOriginalBitValue | uxBitsToSet ) & uxBitsToWaitFor ) == uxBitsToWaitFor )
\r
173 /* All the rendezvous bits are now set - no need to block. */
\r
174 uxReturn = ( uxOriginalBitValue | uxBitsToSet );
\r
176 /* Rendezvous always clear the bits. They will have been cleared
\r
177 already unless this is the only task in the rendezvous. */
\r
178 pxEventBits->uxEventBits &= uxBitsToWaitFor;
\r
184 if( xTicksToWait != ( TickType_t ) 0 )
\r
186 /* Store the bits that the calling task is waiting for in the
\r
187 task's event list item so the kernel knows when a match is
\r
188 found. Then enter the blocked state. */
\r
189 vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | eventCLEAR_EVENTS_ON_EXIT_BIT | eventWAIT_FOR_ALL_BITS ), xTicksToWait );
\r
191 /* This assignment is obsolete as uxReturn will get set after
\r
192 the task unblocks, but some compilers mistakenly generate a
\r
193 warning about uxReturn being returned without being set if the
\r
194 assignment is omitted. */
\r
199 /* The rendezvous bits were not set, but no block time was
\r
200 specified - just return the current event bit value. */
\r
201 uxReturn = pxEventBits->uxEventBits;
\r
205 xAlreadyYielded = xTaskResumeAll();
\r
207 if( xTicksToWait != ( TickType_t ) 0 )
\r
209 if( xAlreadyYielded == pdFALSE )
\r
211 portYIELD_WITHIN_API();
\r
215 mtCOVERAGE_TEST_MARKER();
\r
218 /* The task blocked to wait for its required bits to be set - at this
\r
219 point either the required bits were set or the block time expired. If
\r
220 the required bits were set they will have been stored in the task's
\r
221 event list item, and they should now be retrieved then cleared. */
\r
222 uxReturn = uxTaskResetEventItemValue();
\r
224 if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
\r
226 /* The task timed out, just return the current event bit value. */
\r
227 taskENTER_CRITICAL();
\r
229 uxReturn = pxEventBits->uxEventBits;
\r
231 /* Although the task got here because it timed out before the
\r
232 bits it was waiting for were set, it is possible that since it
\r
233 unblocked another task has set the bits. If this is the case
\r
234 then it may be required to clear the bits before exiting. */
\r
235 if( ( uxReturn & uxBitsToWaitFor ) == uxBitsToWaitFor )
\r
237 pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
\r
241 mtCOVERAGE_TEST_MARKER();
\r
244 taskEXIT_CRITICAL();
\r
248 /* The task unblocked because the bits were set. Clear the control
\r
249 bits before returning the value. */
\r
250 uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
\r
254 traceEVENT_GROUP_SYNC_END( xEventGroup, uxReturn );
\r
257 /*-----------------------------------------------------------*/
\r
259 EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait )
\r
261 EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
\r
262 EventBits_t uxReturn, uxControlBits = 0;
\r
263 BaseType_t xWaitConditionMet, xAlreadyYielded;
\r
265 /* Check the user is not attempting to wait on the bits used by the kernel
\r
266 itself, and that at least one bit is being requested. */
\r
267 configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
\r
268 configASSERT( uxBitsToWaitFor != 0 );
\r
269 #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
\r
271 configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
\r
277 const EventBits_t uxCurrentEventBits = pxEventBits->uxEventBits;
\r
279 traceEVENT_GROUP_WAIT_BITS_START( xEventGroup, uxBitsToWaitFor );
\r
281 /* Check to see if the wait condition is already met or not. */
\r
282 xWaitConditionMet = prvTestWaitCondition( uxCurrentEventBits, uxBitsToWaitFor, xWaitForAllBits );
\r
284 if( xWaitConditionMet != pdFALSE )
\r
286 /* The wait condition has already been met so there is no need to
\r
288 uxReturn = uxCurrentEventBits;
\r
289 xTicksToWait = ( TickType_t ) 0;
\r
291 /* Clear the wait bits if requested to do so. */
\r
292 if( xClearOnExit != pdFALSE )
\r
294 pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
\r
298 mtCOVERAGE_TEST_MARKER();
\r
301 else if( xTicksToWait == ( TickType_t ) 0 )
\r
303 /* The wait condition has not been met, but no block time was
\r
304 specified, so just return the current value. */
\r
305 uxReturn = uxCurrentEventBits;
\r
309 /* The task is going to block to wait for its required bits to be
\r
310 set. uxControlBits are used to remember the specified behaviour of
\r
311 this call to xEventGroupWaitBits() - for use when the event bits
\r
312 unblock the task. */
\r
313 if( xClearOnExit != pdFALSE )
\r
315 uxControlBits |= eventCLEAR_EVENTS_ON_EXIT_BIT;
\r
319 mtCOVERAGE_TEST_MARKER();
\r
322 if( xWaitForAllBits != pdFALSE )
\r
324 uxControlBits |= eventWAIT_FOR_ALL_BITS;
\r
328 mtCOVERAGE_TEST_MARKER();
\r
331 /* Store the bits that the calling task is waiting for in the
\r
332 task's event list item so the kernel knows when a match is
\r
333 found. Then enter the blocked state. */
\r
334 vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | uxControlBits ), xTicksToWait );
\r
336 /* This is obsolete as it will get set after the task unblocks, but
\r
337 some compilers mistakenly generate a warning about the variable
\r
338 being returned without being set if it is not done. */
\r
342 xAlreadyYielded = xTaskResumeAll();
\r
344 if( xTicksToWait != ( TickType_t ) 0 )
\r
346 if( xAlreadyYielded == pdFALSE )
\r
348 portYIELD_WITHIN_API();
\r
352 mtCOVERAGE_TEST_MARKER();
\r
355 /* The task blocked to wait for its required bits to be set - at this
\r
356 point either the required bits were set or the block time expired. If
\r
357 the required bits were set they will have been stored in the task's
\r
358 event list item, and they should now be retrieved then cleared. */
\r
359 uxReturn = uxTaskResetEventItemValue();
\r
361 if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
\r
363 taskENTER_CRITICAL();
\r
365 /* The task timed out, just return the current event bit value. */
\r
366 uxReturn = pxEventBits->uxEventBits;
\r
368 /* It is possible that the event bits were updated between this
\r
369 task leaving the Blocked state and running again. */
\r
370 if( prvTestWaitCondition( uxReturn, uxBitsToWaitFor, xWaitForAllBits ) != pdFALSE )
\r
372 if( xClearOnExit != pdFALSE )
\r
374 pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
\r
378 mtCOVERAGE_TEST_MARKER();
\r
383 mtCOVERAGE_TEST_MARKER();
\r
386 taskEXIT_CRITICAL();
\r
390 /* The task unblocked because the bits were set. Clear the control
\r
391 bits before returning the value. */
\r
392 uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
\r
396 traceEVENT_GROUP_WAIT_BITS_END( xEventGroup, uxReturn );
\r
399 /*-----------------------------------------------------------*/
\r
401 EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear )
\r
403 EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
\r
404 EventBits_t uxReturn;
\r
406 /* Check the user is not attempting to clear the bits used by the kernel
\r
408 configASSERT( ( uxBitsToClear & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
\r
410 taskENTER_CRITICAL();
\r
412 traceEVENT_GROUP_CLEAR_BITS( xEventGroup, uxBitsToClear );
\r
414 /* The value returned is the event group value prior to the bits being
\r
416 uxReturn = pxEventBits->uxEventBits;
\r
418 /* Clear the bits. */
\r
419 pxEventBits->uxEventBits &= ~uxBitsToClear;
\r
421 taskEXIT_CRITICAL();
\r
425 /*-----------------------------------------------------------*/
\r
427 EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet )
\r
429 ListItem_t *pxListItem, *pxNext;
\r
430 ListItem_t const *pxListEnd;
\r
432 EventBits_t uxBitsToClear = 0, uxBitsWaitedFor, uxControlBits;
\r
433 EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
\r
434 BaseType_t xMatchFound = pdFALSE;
\r
436 /* Check the user is not attempting to set the bits used by the kernel
\r
438 configASSERT( ( uxBitsToSet & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
\r
440 pxList = &( pxEventBits->xTasksWaitingForBits );
\r
441 pxListEnd = listGET_END_MARKER( pxList ); /*lint !e826 !e740 The mini list structure is used as the list end to save RAM. This is checked and valid. */
\r
444 traceEVENT_GROUP_SET_BITS( xEventGroup, uxBitsToSet );
\r
446 pxListItem = listGET_HEAD_ENTRY( pxList );
\r
448 /* Set the bits. */
\r
449 pxEventBits->uxEventBits |= uxBitsToSet;
\r
451 /* See if the new bit value should unblock any tasks. */
\r
452 while( pxListItem != pxListEnd )
\r
454 pxNext = listGET_NEXT( pxListItem );
\r
455 uxBitsWaitedFor = listGET_LIST_ITEM_VALUE( pxListItem );
\r
456 xMatchFound = pdFALSE;
\r
458 /* Split the bits waited for from the control bits. */
\r
459 uxControlBits = uxBitsWaitedFor & eventEVENT_BITS_CONTROL_BYTES;
\r
460 uxBitsWaitedFor &= ~eventEVENT_BITS_CONTROL_BYTES;
\r
462 if( ( uxControlBits & eventWAIT_FOR_ALL_BITS ) == ( EventBits_t ) 0 )
\r
464 /* Just looking for single bit being set. */
\r
465 if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) != ( EventBits_t ) 0 )
\r
467 xMatchFound = pdTRUE;
\r
471 mtCOVERAGE_TEST_MARKER();
\r
474 else if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) == uxBitsWaitedFor )
\r
476 /* All bits are set. */
\r
477 xMatchFound = pdTRUE;
\r
481 /* Need all bits to be set, but not all the bits were set. */
\r
484 if( xMatchFound != pdFALSE )
\r
486 /* The bits match. Should the bits be cleared on exit? */
\r
487 if( ( uxControlBits & eventCLEAR_EVENTS_ON_EXIT_BIT ) != ( EventBits_t ) 0 )
\r
489 uxBitsToClear |= uxBitsWaitedFor;
\r
493 mtCOVERAGE_TEST_MARKER();
\r
496 /* Store the actual event flag value in the task's event list
\r
497 item before removing the task from the event list. The
\r
498 eventUNBLOCKED_DUE_TO_BIT_SET bit is set so the task knows
\r
499 that is was unblocked due to its required bits matching, rather
\r
500 than because it timed out. */
\r
501 ( void ) xTaskRemoveFromUnorderedEventList( pxListItem, pxEventBits->uxEventBits | eventUNBLOCKED_DUE_TO_BIT_SET );
\r
504 /* Move onto the next list item. Note pxListItem->pxNext is not
\r
505 used here as the list item may have been removed from the event list
\r
506 and inserted into the ready/pending reading list. */
\r
507 pxListItem = pxNext;
\r
510 /* Clear any bits that matched when the eventCLEAR_EVENTS_ON_EXIT_BIT
\r
511 bit was set in the control word. */
\r
512 pxEventBits->uxEventBits &= ~uxBitsToClear;
\r
514 ( void ) xTaskResumeAll();
\r
516 return pxEventBits->uxEventBits;
\r
518 /*-----------------------------------------------------------*/
\r
520 void vEventGroupDelete( EventGroupHandle_t xEventGroup )
\r
522 EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
\r
523 const List_t *pxTasksWaitingForBits = &( pxEventBits->xTasksWaitingForBits );
\r
527 traceEVENT_GROUP_DELETE( xEventGroup );
\r
529 while( listCURRENT_LIST_LENGTH( pxTasksWaitingForBits ) > ( UBaseType_t ) 0 )
\r
531 /* Unblock the task, returning 0 as the event list is being deleted
\r
532 and cannot therefore have any bits set. */
\r
533 configASSERT( pxTasksWaitingForBits->xListEnd.pxNext != ( ListItem_t * ) &( pxTasksWaitingForBits->xListEnd ) );
\r
534 ( void ) xTaskRemoveFromUnorderedEventList( pxTasksWaitingForBits->xListEnd.pxNext, ( TickType_t ) eventUNBLOCKED_DUE_TO_BIT_SET );
\r
537 vPortFree( pxEventBits );
\r
539 ( void ) xTaskResumeAll();
\r
541 /*-----------------------------------------------------------*/
\r
543 /* For internal use only - execute a 'set bits' command that was pended from
\r
545 void vEventGroupSetBitsCallback( void *pvEventGroup, const uint32_t ulBitsToSet )
\r
547 ( void ) xEventGroupSetBits( pvEventGroup, ( EventBits_t ) ulBitsToSet );
\r
549 /*-----------------------------------------------------------*/
\r
551 static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits, const EventBits_t uxBitsToWaitFor, const BaseType_t xWaitForAllBits )
\r
553 BaseType_t xWaitConditionMet = pdFALSE;
\r
555 if( xWaitForAllBits == pdFALSE )
\r
557 /* Task only has to wait for one bit within uxBitsToWaitFor to be
\r
558 set. Is one already set? */
\r
559 if( ( uxCurrentEventBits & uxBitsToWaitFor ) != ( EventBits_t ) 0 )
\r
561 xWaitConditionMet = pdTRUE;
\r
565 mtCOVERAGE_TEST_MARKER();
\r
570 /* Task has to wait for all the bits in uxBitsToWaitFor to be set.
\r
571 Are they set already? */
\r
572 if( ( uxCurrentEventBits & uxBitsToWaitFor ) == uxBitsToWaitFor )
\r
574 xWaitConditionMet = pdTRUE;
\r
578 mtCOVERAGE_TEST_MARKER();
\r
582 return xWaitConditionMet;
\r