]> git.sur5r.net Git - freertos/blob - FreeRTOS/Source/event_groups.c
Add trace macros into the event groups implementation.
[freertos] / FreeRTOS / Source / event_groups.c
1 /*\r
2     FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd.\r
3     All rights reserved\r
4 \r
5     VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.\r
6 \r
7     ***************************************************************************\r
8      *                                                                       *\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
12      *                                                                       *\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
16      *                                                                       *\r
17      *    Thank you!                                                         *\r
18      *                                                                       *\r
19     ***************************************************************************\r
20 \r
21     This file is part of the FreeRTOS distribution.\r
22 \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
26 \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
30     >>! kernel.\r
31 \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
36 \r
37     1 tab == 4 spaces!\r
38 \r
39     ***************************************************************************\r
40      *                                                                       *\r
41      *    Having a problem?  Start by reading the FAQ "My application does   *\r
42      *    not run, what could be wrong?"                                     *\r
43      *                                                                       *\r
44      *    http://www.FreeRTOS.org/FAQHelp.html                               *\r
45      *                                                                       *\r
46     ***************************************************************************\r
47 \r
48     http://www.FreeRTOS.org - Documentation, books, training, latest versions,\r
49     license and Real Time Engineers Ltd. contact details.\r
50 \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
54 \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
58 \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
62 \r
63     1 tab == 4 spaces!\r
64 */\r
65 \r
66 /* Standard includes. */\r
67 #include <stdlib.h>\r
68 \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
73 \r
74 /* FreeRTOS includes. */\r
75 #include "FreeRTOS.h"\r
76 #include "task.h"\r
77 #include "timers.h"\r
78 #include "event_groups.h"\r
79 \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
85 \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
88 #endif\r
89 \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
92 #endif\r
93 \r
94 \r
95 #if configUSE_16_BIT_TICKS == 1\r
96         #define taskCLEAR_EVENTS_ON_EXIT_BIT    0x0100U\r
97         #define taskUNBLOCKED_DUE_TO_BIT_SET    0x0200U\r
98         #define taskWAIT_FOR_ALL_BITS                   0x0400U\r
99         #define taskEVENT_BITS_CONTROL_BYTES    0xff00U\r
100 #else\r
101         #define taskCLEAR_EVENTS_ON_EXIT_BIT    0x01000000UL\r
102         #define taskUNBLOCKED_DUE_TO_BIT_SET    0x02000000UL\r
103         #define taskWAIT_FOR_ALL_BITS                   0x04000000UL\r
104         #define taskEVENT_BITS_CONTROL_BYTES    0xff000000UL\r
105 #endif\r
106 \r
107 typedef struct EventBitsDefinition\r
108 {\r
109         xEventBitsType uxEventBits;\r
110         xList xTasksWaitingForBits;             /*< List of tasks waiting for a bit to be set. */\r
111 } xEVENT_BITS;\r
112 \r
113 /* Used internally only. */\r
114 typedef struct EVENT_GROUP_CALLBACK_PARAMTERS\r
115 {\r
116         xEventGroupHandle xTargetEventGroup;\r
117         xEventBitsType xBitsToSet;\r
118 } xEventGroupCallbackParameters;\r
119 \r
120 /*-----------------------------------------------------------*/\r
121 \r
122 xEventGroupHandle xEventGroupCreate( void )\r
123 {\r
124 xEVENT_BITS *pxEventBits;\r
125 \r
126         pxEventBits = pvPortMalloc( sizeof( xEVENT_BITS ) );\r
127         if( pxEventBits != NULL )\r
128         {\r
129                 pxEventBits->uxEventBits = 0;\r
130                 vListInitialise( &( pxEventBits->xTasksWaitingForBits ) );\r
131                 traceEVENT_GROUP_CREATE( pxEventBits );         \r
132         }\r
133         else\r
134         {\r
135                 traceEVENT_GROUP_CREATE_FAILED();\r
136         }\r
137 \r
138         return ( xEventGroupHandle ) pxEventBits;\r
139 }\r
140 /*-----------------------------------------------------------*/\r
141 \r
142 xEventBitsType xEventGroupSync( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToSet, xEventBitsType uxBitsToWaitFor, portTickType xTicksToWait )\r
143 {\r
144 xEventBitsType uxOriginalBitValue, uxReturn;\r
145 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
146 portBASE_TYPE xYieldedAlready;\r
147 \r
148         #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )\r
149         {\r
150                 configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );\r
151         }\r
152         #endif\r
153 \r
154         vTaskSuspendAll();\r
155         {\r
156                 traceEVENT_GROUP_SYNC_START( xEventGroup, uxBitsToSet );\r
157 \r
158                 uxOriginalBitValue = pxEventBits->uxEventBits;\r
159 \r
160                 ( void ) xEventGroupSetBits( xEventGroup, uxBitsToSet );\r
161 \r
162                 if( ( ( uxOriginalBitValue | uxBitsToSet ) & uxBitsToWaitFor ) == uxBitsToWaitFor )\r
163                 {\r
164                         /* All the rendezvous bits will have been set once this task set\r
165                         its bits - no need to block. */\r
166                         uxReturn = ( uxOriginalBitValue | uxBitsToSet );\r
167 \r
168                         /* Rendezvous always clear the bits.  They will have been cleared\r
169                         already unless this is the only task in the rendezvous. */\r
170                         pxEventBits->uxEventBits &= uxBitsToWaitFor;\r
171 \r
172                         xTicksToWait = 0;\r
173                 }\r
174                 else\r
175                 {\r
176                         if( xTicksToWait != ( portTickType ) 0 )\r
177                         {\r
178                                 /* Store the bits that the calling task is waiting for in the\r
179                                 task's event list item so the kernel knows when a match is\r
180                                 found.  Then enter the blocked state. */\r
181                                 vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | taskCLEAR_EVENTS_ON_EXIT_BIT | taskWAIT_FOR_ALL_BITS ), xTicksToWait );\r
182 \r
183                                 /* This is obsolete as it will get set after the task unblocks,\r
184                                 but some compilers mistakenly generate a warning about the\r
185                                 variable being returned without being set if it is not done. */\r
186                                 uxReturn = 0;\r
187                         }\r
188                         else\r
189                         {\r
190                                 /* The rendezvous bits were not set, but no block time was\r
191                                 specified - just return the current event bit value. */\r
192                                 uxReturn = pxEventBits->uxEventBits;\r
193                         }\r
194                 }\r
195         }\r
196         xYieldedAlready = xTaskResumeAll();\r
197 \r
198         if( xTicksToWait != ( portTickType ) 0 )\r
199         {\r
200                 if( xYieldedAlready == pdFALSE )\r
201                 {\r
202                         portYIELD_WITHIN_API();\r
203                 }\r
204 \r
205                 /* The task blocked to wait for its required bits to be set - at this\r
206                 point either the required bits were set or the block time expired.  If\r
207                 the required bits were set they will have been stored in the task's\r
208                 event list item, and they should now be retrieved then cleared. */\r
209                 uxReturn = uxTaskResetEventItemValue();\r
210 \r
211                 if( ( uxReturn & taskUNBLOCKED_DUE_TO_BIT_SET ) == ( xEventBitsType ) 0 )\r
212                 {\r
213                         /* The task timed out, just return the current event bit value. */\r
214                         uxReturn = pxEventBits->uxEventBits;\r
215                 }\r
216                 else\r
217                 {\r
218                         /* The task unblocked because the bits were set.  Clear the control\r
219                         bits before returning the value. */\r
220                         uxReturn &= ~taskEVENT_BITS_CONTROL_BYTES;\r
221                 }\r
222         }\r
223 \r
224         traceEVENT_GROUP_SYNC_END( xEventGroup, uxReturn );\r
225         return uxReturn;\r
226 }\r
227 /*-----------------------------------------------------------*/\r
228 \r
229 xEventBitsType xEventGroupWaitBits( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToWaitFor, portBASE_TYPE xClearOnExit, portBASE_TYPE xWaitForAllBits, portTickType xTicksToWait )\r
230 {\r
231 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
232 xEventBitsType uxReturn, uxControlBits = 0;\r
233 \r
234         /* Check the user is not attempting to wait on the bits used by the kernel\r
235         itself, and that at least one bit is being requested. */\r
236         configASSERT( ( uxBitsToWaitFor & taskEVENT_BITS_CONTROL_BYTES ) == 0 );\r
237         configASSERT( uxBitsToWaitFor != 0 );\r
238         #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )\r
239         {\r
240                 configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );\r
241         }\r
242         #endif\r
243 \r
244         taskENTER_CRITICAL();\r
245         {\r
246                 const xEventBitsType uxCurrentEventBits = pxEventBits->uxEventBits;\r
247 \r
248                 traceEVENT_GROUP_WAIT_BITS_START( xEventGroup, uxBitsToWaitFor );\r
249 \r
250                 if( xWaitForAllBits == pdFALSE )\r
251                 {\r
252                         /* Task only has to wait for one bit within uxBitsToWaitFor to be set.  Is\r
253                         one already set? */\r
254                         if( ( uxCurrentEventBits & uxBitsToWaitFor ) != ( xEventBitsType ) 0 )\r
255                         {\r
256                                 /* At least one of the bits was set.  No need to block. */\r
257                                 xTicksToWait = 0;\r
258                         }\r
259                 }\r
260                 else\r
261                 {\r
262                         /* Task has to wait for all the bits in uxBitsToWaitFor to be set.  Are they\r
263                         set already? */\r
264                         if( ( uxCurrentEventBits & uxBitsToWaitFor ) == uxBitsToWaitFor )\r
265                         {\r
266                                 /* All the bits were set, no need to block. */\r
267                                 xTicksToWait = 0;\r
268                         }\r
269                 }\r
270 \r
271                 /* The task can return now if either its wait condition is already met\r
272                 or the requested block time is 0. */\r
273                 if( xTicksToWait == ( portTickType ) 0 )\r
274                 {\r
275                         /* No need to block, just set the return value. */\r
276                         uxReturn = uxCurrentEventBits;\r
277 \r
278                         if( xClearOnExit != pdFALSE )\r
279                         {\r
280                                 /* The user requested the bits be cleared again prior to exiting\r
281                                 this function. */\r
282                                 pxEventBits->uxEventBits &= ~uxBitsToWaitFor;\r
283                         }\r
284                 }\r
285                 else\r
286                 {\r
287                         /* The task is going to block to wait for its required bits to be\r
288                         set.  uxControlBits are used to remember the specified behaviour of\r
289                         this call to xEventGroupWaitBits() - for use when the event bits\r
290                         unblock the task. */\r
291                         if( xClearOnExit != pdFALSE )\r
292                         {\r
293                                 uxControlBits |= taskCLEAR_EVENTS_ON_EXIT_BIT;\r
294                         }\r
295 \r
296                         if( xWaitForAllBits != pdFALSE )\r
297                         {\r
298                                 uxControlBits |= taskWAIT_FOR_ALL_BITS;\r
299                         }\r
300 \r
301                         /* Store the bits that the calling task is waiting for in the\r
302                         task's event list item so the kernel knows when a match is\r
303                         found.  Then enter the blocked state. */\r
304                         vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | uxControlBits ), xTicksToWait );\r
305                         portYIELD_WITHIN_API();\r
306 \r
307                         /* This is obsolete as it will get set after the task unblocks, but\r
308                         some compilers mistakenly generate a warning about the variable\r
309                         being returned without being set if it is not done. */\r
310                         uxReturn = 0;\r
311                 }\r
312         }\r
313         taskEXIT_CRITICAL();\r
314 \r
315         if( xTicksToWait != ( portTickType ) 0 )\r
316         {\r
317                 /* The task blocked to wait for its required bits to be set - at this\r
318                 point either the required bits were set or the block time expired.  If\r
319                 the required bits were set they will have been stored in the task's\r
320                 event list item, and they should now be retrieved then cleared. */\r
321                 uxReturn = uxTaskResetEventItemValue();\r
322 \r
323                 if( ( uxReturn & taskUNBLOCKED_DUE_TO_BIT_SET ) == ( xEventBitsType ) 0 )\r
324                 {\r
325                         /* The task timed out, just return the current event bit value. */\r
326                         uxReturn = pxEventBits->uxEventBits;\r
327                 }\r
328                 else\r
329                 {\r
330                         /* The task unblocked because the bits were set.  Clear the control\r
331                         bits before returning the value. */\r
332                         uxReturn &= ~taskEVENT_BITS_CONTROL_BYTES;\r
333                 }\r
334         }\r
335 \r
336         traceEVENT_GROUP_WAIT_BITS_END( xEventGroup, uxReturn );\r
337         return uxReturn;\r
338 }\r
339 /*-----------------------------------------------------------*/\r
340 \r
341 xEventBitsType xEventGroupClearBits( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToClear )\r
342 {\r
343 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
344 xEventBitsType uxReturn;\r
345 \r
346         /* Check the user is not attempting to clear the bits used by the kernel\r
347         itself. */\r
348         configASSERT( ( uxBitsToClear & taskEVENT_BITS_CONTROL_BYTES ) == 0 );\r
349 \r
350         uxBitsToClear = ~uxBitsToClear;\r
351         taskENTER_CRITICAL();\r
352         {\r
353                 traceEVENT_GROUP_CLEAR_BITS( xEventGroup, ~uxBitsToClear );\r
354 \r
355                 /* The value returned is the event group value prior to the bits being\r
356                 cleared. */\r
357                 uxReturn = pxEventBits->uxEventBits;\r
358 \r
359                 /* Clear the bits. */\r
360                 pxEventBits->uxEventBits &= uxBitsToClear;\r
361         }\r
362         taskEXIT_CRITICAL();\r
363 \r
364         return uxReturn;\r
365 }\r
366 /*-----------------------------------------------------------*/\r
367 \r
368 xEventBitsType xEventGroupSetBits( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToSet )\r
369 {\r
370 xListItem *pxListItem, *pxNext;\r
371 xListItem const *pxListEnd;\r
372 xList *pxList;\r
373 xEventBitsType uxBitsToClear = 0, uxBitsWaitedFor, uxControlBits;\r
374 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
375 portBASE_TYPE xMatchFound = pdFALSE;\r
376 \r
377         /* Check the user is not attempting to set the bits used by the kernel\r
378         itself. */\r
379         configASSERT( ( uxBitsToSet & taskEVENT_BITS_CONTROL_BYTES ) == 0 );\r
380 \r
381         pxList = &( pxEventBits->xTasksWaitingForBits );\r
382         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
383         vTaskSuspendAll();\r
384         {\r
385                 traceEVENT_GROUP_SET_BITS( xEventGroup, uxBitsToSet );\r
386 \r
387                 pxListItem = listGET_HEAD_ENTRY( pxList );\r
388 \r
389                 /* Set the bits. */\r
390                 pxEventBits->uxEventBits |= uxBitsToSet;\r
391 \r
392                 /* See if the new bit value should unblock any tasks. */\r
393                 while( pxListItem != pxListEnd )\r
394                 {\r
395                         pxNext = listGET_NEXT( pxListItem );\r
396                         uxBitsWaitedFor = listGET_LIST_ITEM_VALUE( pxListItem );\r
397                         xMatchFound = pdFALSE;\r
398 \r
399                         /* Split the bits waited for from the control bits. */\r
400                         uxControlBits = uxBitsWaitedFor & taskEVENT_BITS_CONTROL_BYTES;\r
401                         uxBitsWaitedFor &= ~taskEVENT_BITS_CONTROL_BYTES;\r
402 \r
403                         if( ( uxControlBits & taskWAIT_FOR_ALL_BITS ) == ( xEventBitsType ) 0 )\r
404                         {\r
405                                 /* Just looking for single bit being set. */\r
406                                 if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) != ( xEventBitsType ) 0 )\r
407                                 {\r
408                                         xMatchFound = pdTRUE;\r
409                                 }\r
410                         }\r
411                         else if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) == uxBitsWaitedFor )\r
412                         {\r
413                                 /* All bits are set. */\r
414                                 xMatchFound = pdTRUE;\r
415                         }\r
416                         else\r
417                         {\r
418                                 /* Need all bits to be set, but not all the bits were set. */\r
419                         }\r
420 \r
421                         if( xMatchFound != pdFALSE )\r
422                         {\r
423                                 /* The bits match.  Should the bits be cleared on exit? */\r
424                                 if( ( uxControlBits & taskCLEAR_EVENTS_ON_EXIT_BIT ) != ( xEventBitsType ) 0 )\r
425                                 {\r
426                                         uxBitsToClear |= uxBitsWaitedFor;\r
427                                 }\r
428 \r
429                                 /* Store the actual event flag value in the task's event list\r
430                                 item before removing the task from the event list.  The\r
431                                 taskUNBLOCKED_DUE_TO_BIT_SET bit is set so the task knows\r
432                                 that is was unblocked due to its required bits matching, rather\r
433                                 than because it timed out. */\r
434                                 ( void ) xTaskRemoveFromUnorderedEventList( pxListItem, pxEventBits->uxEventBits | taskUNBLOCKED_DUE_TO_BIT_SET );\r
435                         }\r
436 \r
437                         /* Move onto the next list item.  Note pxListItem->pxNext is not\r
438                         used here as the list item may have been removed from the event list\r
439                         and inserted into the ready/pending reading list. */\r
440                         pxListItem = pxNext;\r
441                 }\r
442 \r
443                 /* Clear any bits that matched when the taskCLEAR_EVENTS_ON_EXIT_BIT\r
444                 bit was set in the control word. */\r
445                 pxEventBits->uxEventBits &= ~uxBitsToClear;\r
446         }\r
447         ( void ) xTaskResumeAll();\r
448 \r
449         return pxEventBits->uxEventBits;\r
450 }\r
451 /*-----------------------------------------------------------*/\r
452 \r
453 void vEventGroupDelete( xEventGroupHandle xEventGroup )\r
454 {\r
455 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
456 const xList *pxTasksWaitingForBits = &( pxEventBits->xTasksWaitingForBits );\r
457 \r
458         vTaskSuspendAll();\r
459         {\r
460                 traceEVENT_GROUP_DELETE( xEventGroup );\r
461 \r
462                 while( listCURRENT_LIST_LENGTH( pxTasksWaitingForBits ) > ( unsigned portBASE_TYPE ) 0 )\r
463                 {\r
464                         /* Unblock the task, returning 0 as the event list is being deleted\r
465                         and     cannot therefore have any bits set. */\r
466                         configASSERT( pxTasksWaitingForBits->xListEnd.pxNext != ( xListItem * ) &( pxTasksWaitingForBits->xListEnd ) );\r
467                         ( void ) xTaskRemoveFromUnorderedEventList( pxTasksWaitingForBits->xListEnd.pxNext, ( portTickType ) taskUNBLOCKED_DUE_TO_BIT_SET );\r
468                 }\r
469 \r
470                 vPortFree( pxEventBits );\r
471         }\r
472         ( void ) xTaskResumeAll();\r
473 }\r
474 /*-----------------------------------------------------------*/\r
475 \r
476 /* For internal use only - execute a 'set bits' command that was pended from\r
477 an interrupt. */\r
478 void vEventGroupSetBitsCallback( void *pvEventGroup, unsigned long ulBitsToSet )\r
479 {\r
480         ( void ) xEventGroupSetBits( pvEventGroup, ( xEventBitsType ) ulBitsToSet );\r
481 }\r
482 \r
483 \r