git.sur5r.net Git - freertos/blob - 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_BIT        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_BIT        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         }\r
 132 \r
 133         return ( xEventGroupHandle ) pxEventBits;\r
 134 }\r
 135 /*-----------------------------------------------------------*/\r
 136 \r
 137 xEventBitsType xEventGroupSync( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToSet, xEventBitsType uxBitsToWaitFor, portTickType xBlockTime )\r
 138 {\r
 139 xEventBitsType uxOriginalBitValue, uxReturn;\r
 140 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
 141 portBASE_TYPE xYieldedAlready;\r
 142 \r
 143         vTaskSuspendAll();\r
 144         {\r
 145                 uxOriginalBitValue = pxEventBits->uxEventBits;\r
 146 \r
 147                 ( void ) xEventGroupSetBits( xEventGroup, uxBitsToSet );\r
 148 \r
 149                 if( ( ( uxOriginalBitValue | uxBitsToSet ) & uxBitsToWaitFor ) == uxBitsToWaitFor )\r
 150                 {\r
 151                         /* All the rendezvous bits will have been set once this task set\r
 152                         its bits - no need to block. */\r
 153                         uxReturn = ( uxOriginalBitValue | uxBitsToSet );\r
 154 \r
 155                         /* Rendezvous always clear the bits.  They will have been cleared\r
 156                         already unless this is the only task in the rendezvous. */\r
 157                         pxEventBits->uxEventBits &= uxBitsToWaitFor;\r
 158 \r
 159                         xBlockTime = 0;\r
 160                 }\r
 161                 else\r
 162                 {\r
 163                         if( xBlockTime != ( portTickType ) 0 )\r
 164                         {\r
 165                                 /* Store the bits that the calling task is waiting for in the\r
 166                                 task's event list item so the kernel knows when a match is\r
 167                                 found.  Then enter the blocked state. */\r
 168                                 vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | taskCLEAR_EVENTS_ON_EXIT_BIT | taskWAIT_FOR_ALL_BITS ), xBlockTime );\r
 169                         }\r
 170                         else\r
 171                         {\r
 172                                 /* The rendezvous bits were not set, but no block time was\r
 173                                 specified - just return the current event bit value. */\r
 174                                 uxReturn = pxEventBits->uxEventBits;\r
 175                         }\r
 176                 }\r
 177         }\r
 178         xYieldedAlready = xTaskResumeAll();\r
 179 \r
 180         if( xBlockTime != ( portTickType ) 0 )\r
 181         {\r
 182                 if( xYieldedAlready == pdFALSE )\r
 183                 {\r
 184                         portYIELD_WITHIN_API();\r
 185                 }\r
 186 \r
 187                 /* The task blocked to wait for its required bits to be set - at this\r
 188                 point either the required bits were set or the block time expired.  If\r
 189                 the required bits were set they will have been stored in the task's\r
 190                 event list item, and they should now be retrieved then cleared. */\r
 191                 uxReturn = uxTaskResetEventItemValue();\r
 192 \r
 193                 if( ( uxReturn & taskUNBLOCKED_DUE_TO_BIT_SET_BIT ) == ( xEventBitsType ) 0 )\r
 194                 {\r
 195                         /* The task timed out, just return the current event bit value. */\r
 196                         uxReturn = pxEventBits->uxEventBits;\r
 197                 }\r
 198                 else\r
 199                 {\r
 200                         /* The task unblocked because the bits were set.  Clear the control\r
 201                         bits before returning the value. */\r
 202                         uxReturn &= ~taskEVENT_BITS_CONTROL_BYTES;\r
 203                 }\r
 204         }\r
 205 \r
 206         return uxReturn;\r
 207 }\r
 208 /*-----------------------------------------------------------*/\r
 209 \r
 210 xEventBitsType xEventGroupWaitBits( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToWaitFor, portBASE_TYPE xClearOnExit, portBASE_TYPE xWaitForAllBits, portTickType xBlockTime )\r
 211 {\r
 212 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
 213 const xEventBitsType uxCurrentEventBits = pxEventBits->uxEventBits;\r
 214 xEventBitsType uxReturn, uxControlBits = 0;\r
 215 \r
 216         /* Check the user is not attempting to wait on the bits used by the kernel\r
 217         itself, and that at least one bit is being requested. */\r
 218         configASSERT( ( uxBitsToWaitFor & taskEVENT_BITS_CONTROL_BYTES ) == 0 );\r
 219         configASSERT( uxBitsToWaitFor != 0 );\r
 220 \r
 221         taskENTER_CRITICAL();\r
 222         {\r
 223                 if( xWaitForAllBits == pdFALSE )\r
 224                 {\r
 225                         /* Task only has to wait for one bit within uxBitsToWaitFor to be set.  Is\r
 226                         one already set? */\r
 227                         if( ( uxCurrentEventBits & uxBitsToWaitFor ) != ( xEventBitsType ) 0 )\r
 228                         {\r
 229                                 /* At least one of the bits was set.  No need to block. */\r
 230                                 xBlockTime = 0;\r
 231                         }\r
 232                 }\r
 233                 else\r
 234                 {\r
 235                         /* Task has to wait for all the bits in uxBitsToWaitFor to be set.  Are they\r
 236                         set already? */\r
 237                         if( ( uxCurrentEventBits & uxBitsToWaitFor ) == uxBitsToWaitFor )\r
 238                         {\r
 239                                 /* All the bits were set, no need to block. */\r
 240                                 xBlockTime = 0;\r
 241                         }\r
 242                 }\r
 243 \r
 244                 /* The task can return now if either its wait condition is already met\r
 245                 or the requested block time is 0. */\r
 246                 if( xBlockTime == ( portTickType ) 0 )\r
 247                 {\r
 248                         /* No need to block, just set the return value. */\r
 249                         uxReturn = uxCurrentEventBits;\r
 250 \r
 251                         if( xClearOnExit != pdFALSE )\r
 252                         {\r
 253                                 /* The user requested the bits be cleared again prior to exiting\r
 254                                 this function. */\r
 255                                 pxEventBits->uxEventBits &= ~uxBitsToWaitFor;\r
 256                         }\r
 257                 }\r
 258                 else\r
 259                 {\r
 260                         /* The task is going to block to wait for its required bits to be\r
 261                         set.  uxControlBits are used to remember the specified behaviour of\r
 262                         this call to xEventGroupWaitBits() - for use when the event bits\r
 263                         unblock the task. */\r
 264                         if( xClearOnExit != pdFALSE )\r
 265                         {\r
 266                                 uxControlBits |= taskCLEAR_EVENTS_ON_EXIT_BIT;\r
 267                         }\r
 268 \r
 269                         if( xWaitForAllBits != pdFALSE )\r
 270                         {\r
 271                                 uxControlBits |= taskWAIT_FOR_ALL_BITS;\r
 272                         }\r
 273 \r
 274                         /* Store the bits that the calling task is waiting for in the\r
 275                         task's event list item so the kernel knows when a match is\r
 276                         found.  Then enter the blocked state. */\r
 277                         vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | uxControlBits ), xBlockTime );\r
 278                         portYIELD_WITHIN_API();\r
 279                 }\r
 280         }\r
 281         taskEXIT_CRITICAL();\r
 282 \r
 283         if( xBlockTime != ( portTickType ) 0 )\r
 284         {\r
 285                 /* The task blocked to wait for its required bits to be set - at this\r
 286                 point either the required bits were set or the block time expired.  If\r
 287                 the required bits were set they will have been stored in the task's\r
 288                 event list item, and they should now be retrieved then cleared. */\r
 289                 uxReturn = uxTaskResetEventItemValue();\r
 290 \r
 291                 if( ( uxReturn & taskUNBLOCKED_DUE_TO_BIT_SET_BIT ) == ( xEventBitsType ) 0 )\r
 292                 {\r
 293                         /* The task timed out, just return the current event bit value. */\r
 294                         uxReturn = pxEventBits->uxEventBits;\r
 295                 }\r
 296                 else\r
 297                 {\r
 298                         /* The task unblocked because the bits were set.  Clear the control\r
 299                         bits before returning the value. */\r
 300                         uxReturn &= ~taskEVENT_BITS_CONTROL_BYTES;\r
 301                 }\r
 302         }\r
 303 \r
 304         return uxReturn;\r
 305 }\r
 306 /*-----------------------------------------------------------*/\r
 307 \r
 308 xEventBitsType xEventGroupClearBits( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToClear )\r
 309 {\r
 310 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
 311 xEventBitsType uxReturn;\r
 312 \r
 313         /* Check the user is not attempting to clear the bits used by the kernel\r
 314         itself. */\r
 315         configASSERT( ( uxBitsToClear & taskEVENT_BITS_CONTROL_BYTES ) == 0 );\r
 316 \r
 317         uxBitsToClear = ~uxBitsToClear;\r
 318         taskENTER_CRITICAL();\r
 319         {\r
 320                 /* The value returned is the event group value prior to the bits being\r
 321                 cleared. */\r
 322                 uxReturn = pxEventBits->uxEventBits;\r
 323 \r
 324                 /* Clear the bits. */\r
 325                 pxEventBits->uxEventBits &= uxBitsToClear;\r
 326         }\r
 327         taskEXIT_CRITICAL();\r
 328 \r
 329         return uxReturn;\r
 330 }\r
 331 /*-----------------------------------------------------------*/\r
 332 \r
 333 xEventBitsType xEventGroupSetBits( xEventGroupHandle xEventGroup, xEventBitsType uxBitsToSet )\r
 334 {\r
 335 xListItem *pxListItem, *pxNext;\r
 336 xListItem const *pxListEnd;\r
 337 xList *pxList;\r
 338 xEventBitsType uxBitsToClear = 0, uxBitsWaitedFor, uxControlBits;\r
 339 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
 340 portBASE_TYPE xMatchFound = pdFALSE;\r
 341 \r
 342         /* Check the user is not attempting to set the bits used by the kernel\r
 343         itself. */\r
 344         configASSERT( ( uxBitsToSet & taskEVENT_BITS_CONTROL_BYTES ) == 0 );\r
 345 \r
 346         pxList = &( pxEventBits->xTasksWaitingForBits );\r
 347         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
 348         pxListItem = listGET_HEAD_ENTRY( pxList );\r
 349         vTaskSuspendAll();\r
 350         {\r
 351                 /* Set the bits. */\r
 352                 pxEventBits->uxEventBits |= uxBitsToSet;\r
 353 \r
 354                 /* See if the new bit value should unblock any tasks. */\r
 355                 while( pxListItem != pxListEnd )\r
 356                 {\r
 357                         pxNext = listGET_NEXT( pxListItem );\r
 358                         uxBitsWaitedFor = listGET_LIST_ITEM_VALUE( pxListItem );\r
 359 \r
 360                         /* Split the bits waited for from the control bits. */\r
 361                         uxControlBits = uxBitsWaitedFor & taskEVENT_BITS_CONTROL_BYTES;\r
 362                         uxBitsWaitedFor &= ~taskEVENT_BITS_CONTROL_BYTES;\r
 363 \r
 364                         if( ( uxControlBits & taskWAIT_FOR_ALL_BITS ) == ( xEventBitsType ) 0 )\r
 365                         {\r
 366                                 /* Just looking for single bit being set. */\r
 367                                 if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) != ( xEventBitsType ) 0 )\r
 368                                 {\r
 369                                         xMatchFound = pdTRUE;\r
 370                                 }\r
 371                         }\r
 372                         else if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) == uxBitsWaitedFor )\r
 373                         {\r
 374                                 /* All bits are set. */\r
 375                                 xMatchFound = pdTRUE;\r
 376                         }\r
 377                         else\r
 378                         {\r
 379                                 /* Need all bits to be set, but not all the bits were set. */\r
 380                         }\r
 381 \r
 382                         if( xMatchFound != pdFALSE )\r
 383                         {\r
 384                                 /* The bits match.  Should the bits be cleared on exit? */\r
 385                                 if( ( uxControlBits & taskCLEAR_EVENTS_ON_EXIT_BIT ) != ( xEventBitsType ) 0 )\r
 386                                 {\r
 387                                         uxBitsToClear |= uxBitsWaitedFor;\r
 388                                 }\r
 389 \r
 390                                 /* Store the actual event flag value in the task's event list\r
 391                                 item before removing the task from the event list.  The\r
 392                                 taskUNBLOCKED_DUE_TO_BIT_SET_BIT bit is set so the task knows\r
 393                                 that is was unblocked due to its required bits matching, rather\r
 394                                 than because it timed out. */\r
 395                                 ( void ) xTaskRemoveFromUnorderedEventList( pxListItem, pxEventBits->uxEventBits | taskUNBLOCKED_DUE_TO_BIT_SET_BIT );\r
 396                         }\r
 397 \r
 398                         /* Move onto the next list item.  Note pxListItem->pxNext is not\r
 399                         used here as the list item may have been removed from the event list\r
 400                         and inserted into the ready/pending reading list. */\r
 401                         pxListItem = pxNext;\r
 402                 }\r
 403 \r
 404                 /* Clear any bits that matched when the taskCLEAR_EVENTS_ON_EXIT_BIT\r
 405                 bit was set in the control word. */\r
 406                 pxEventBits->uxEventBits &= ~uxBitsToClear;\r
 407         }\r
 408         ( void ) xTaskResumeAll();\r
 409 \r
 410         return pxEventBits->uxEventBits;\r
 411 }\r
 412 /*-----------------------------------------------------------*/\r
 413 \r
 414 void vEventGroupDelete( xEventGroupHandle xEventGroup )\r
 415 {\r
 416 xEVENT_BITS *pxEventBits = ( xEVENT_BITS * ) xEventGroup;\r
 417 const xList *pxTasksWaitingForBits = &( pxEventBits->xTasksWaitingForBits );\r
 418 \r
 419         vTaskSuspendAll();\r
 420         {\r
 421                 while( listCURRENT_LIST_LENGTH( pxTasksWaitingForBits ) > ( unsigned portBASE_TYPE ) 0 )\r
 422                 {\r
 423                         /* Unblock the task, returning 0 as the event list is being deleted\r
 424                         and     cannot therefore have any bits set. */\r
 425                         configASSERT( pxTasksWaitingForBits->xListEnd.pxNext != ( xListItem * ) &( pxTasksWaitingForBits->xListEnd ) );\r
 426                         ( void ) xTaskRemoveFromUnorderedEventList( pxTasksWaitingForBits->xListEnd.pxNext, ( portTickType ) 0 );\r
 427                 }\r
 428 \r
 429                 vPortFree( pxEventBits );\r
 430         }\r
 431         ( void ) xTaskResumeAll();\r
 432 }\r
 433 /*-----------------------------------------------------------*/\r
 434 \r
 435 /* For internal use only - execute a 'set bits' command that was pended from\r
 436 an interrupt. */\r
 437 void vEventGroupSetBitsCallback( void *pvEventGroup, unsigned long ulBitsToSet )\r
 438 {\r
 439         ( void ) xEventGroupSetBits( pvEventGroup, ( xEventBitsType ) ulBitsToSet );\r
 440 }\r
 441 \r
 442 \r