git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/Common/Minimal/crhook.c

   1 /*\r
   2  * FreeRTOS Kernel V10.0.0\r
   3  * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software. If you wish to use our Amazon\r
  14  * FreeRTOS name, please do so in a fair use way that does not cause confusion.\r
  15  *\r
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  22  *\r
  23  * http://www.FreeRTOS.org\r
  24  * http://aws.amazon.com/freertos\r
  25  *\r
  26  * 1 tab == 4 spaces!\r
  27  */\r
  28 \r
  29 /*\r
  30  * This demo file demonstrates how to send data between an ISR and a\r
  31  * co-routine.  A tick hook function is used to periodically pass data between\r
  32  * the RTOS tick and a set of 'hook' co-routines.\r
  33  *\r
  34  * hookNUM_HOOK_CO_ROUTINES co-routines are created.  Each co-routine blocks\r
  35  * to wait for a character to be received on a queue from the tick ISR, checks\r
  36  * to ensure the character received was that expected, then sends the number\r
  37  * back to the tick ISR on a different queue.\r
  38  *\r
  39  * The tick ISR checks the numbers received back from the 'hook' co-routines\r
  40  * matches the number previously sent.\r
  41  *\r
  42  * If at any time a queue function returns unexpectedly, or an incorrect value\r
  43  * is received either by the tick hook or a co-routine then an error is\r
  44  * latched.\r
  45  *\r
  46  * This demo relies on each 'hook' co-routine to execute between each\r
  47  * hookTICK_CALLS_BEFORE_POST tick interrupts.  This and the heavy use of\r
  48  * queues from within an interrupt may result in an error being detected on\r
  49  * slower targets simply due to timing.\r
  50  */\r
  51 \r
  52 /* Scheduler includes. */\r
  53 #include "FreeRTOS.h"\r
  54 #include "croutine.h"\r
  55 #include "queue.h"\r
  56 \r
  57 /* Demo application includes. */\r
  58 #include "crhook.h"\r
  59 \r
  60 /* The number of 'hook' co-routines that are to be created. */\r
  61 #define hookNUM_HOOK_CO_ROUTINES        ( 4 )\r
  62 \r
  63 /* The number of times the tick hook should be called before a character is\r
  64 posted to the 'hook' co-routines. */\r
  65 #define hookTICK_CALLS_BEFORE_POST      ( 500 )\r
  66 \r
  67 /* There should never be more than one item in any queue at any time. */\r
  68 #define hookHOOK_QUEUE_LENGTH           ( 1 )\r
  69 \r
  70 /* Don't block when initially posting to the queue. */\r
  71 #define hookNO_BLOCK_TIME               ( 0 )\r
  72 \r
  73 /* The priority relative to other co-routines (rather than tasks) that the\r
  74 'hook' co-routines should take. */\r
  75 #define mainHOOK_CR_PRIORITY                    ( 1 )\r
  76 /*-----------------------------------------------------------*/\r
  77 \r
  78 /*\r
  79  * The co-routine function itself.\r
  80  */\r
  81 static void prvHookCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex );\r
  82 \r
  83 \r
  84 /*\r
  85  * The tick hook function.  This receives a number from each 'hook' co-routine\r
  86  * then sends a number to each co-routine.  An error is flagged if a send or\r
  87  * receive fails, or an unexpected number is received.\r
  88  */\r
  89 void vApplicationTickHook( void );\r
  90 \r
  91 /*-----------------------------------------------------------*/\r
  92 \r
  93 /* Queues used to send data FROM a co-routine TO the tick hook function.\r
  94 The hook functions received (Rx's) on these queues.  One queue per\r
  95 'hook' co-routine. */\r
  96 static QueueHandle_t xHookRxQueues[ hookNUM_HOOK_CO_ROUTINES ];\r
  97 \r
  98 /* Queues used to send data FROM the tick hook TO a co-routine function.\r
  99 The hood function transmits (Tx's) on these queues.  One queue per\r
 100 'hook' co-routine. */\r
 101 static QueueHandle_t xHookTxQueues[ hookNUM_HOOK_CO_ROUTINES ];\r
 102 \r
 103 /* Set to true if an error is detected at any time. */\r
 104 static BaseType_t xCoRoutineErrorDetected = pdFALSE;\r
 105 \r
 106 /*-----------------------------------------------------------*/\r
 107 \r
 108 void vStartHookCoRoutines( void )\r
 109 {\r
 110 UBaseType_t uxIndex, uxValueToPost = 0;\r
 111 \r
 112         for( uxIndex = 0; uxIndex < hookNUM_HOOK_CO_ROUTINES; uxIndex++ )\r
 113         {\r
 114                 /* Create a queue to transmit to and receive from each 'hook'\r
 115                 co-routine. */\r
 116                 xHookRxQueues[ uxIndex ] = xQueueCreate( hookHOOK_QUEUE_LENGTH, sizeof( UBaseType_t ) );\r
 117                 xHookTxQueues[ uxIndex ] = xQueueCreate( hookHOOK_QUEUE_LENGTH, sizeof( UBaseType_t ) );\r
 118 \r
 119                 /* To start things off the tick hook function expects the queue it\r
 120                 uses to receive data to contain a value.  */\r
 121                 xQueueSend( xHookRxQueues[ uxIndex ], &uxValueToPost, hookNO_BLOCK_TIME );\r
 122 \r
 123                 /* Create the 'hook' co-routine itself. */\r
 124                 xCoRoutineCreate( prvHookCoRoutine, mainHOOK_CR_PRIORITY, uxIndex );\r
 125         }\r
 126 }\r
 127 /*-----------------------------------------------------------*/\r
 128 \r
 129 static UBaseType_t uxCallCounter = 0, uxNumberToPost = 0;\r
 130 void vApplicationTickHook( void )\r
 131 {\r
 132 UBaseType_t uxReceivedNumber;\r
 133 BaseType_t xIndex, xCoRoutineWoken;\r
 134 \r
 135         /* Is it time to talk to the 'hook' co-routines again? */\r
 136         uxCallCounter++;\r
 137         if( uxCallCounter >= hookTICK_CALLS_BEFORE_POST )\r
 138         {\r
 139                 uxCallCounter = 0;\r
 140 \r
 141                 for( xIndex = 0; xIndex < hookNUM_HOOK_CO_ROUTINES; xIndex++ )\r
 142                 {\r
 143                         xCoRoutineWoken = pdFALSE;\r
 144                         if( crQUEUE_RECEIVE_FROM_ISR( xHookRxQueues[ xIndex ], &uxReceivedNumber, &xCoRoutineWoken ) != pdPASS )\r
 145                         {\r
 146                                 /* There is no reason why we would not expect the queue to\r
 147                                 contain a value. */\r
 148                                 xCoRoutineErrorDetected = pdTRUE;\r
 149                         }\r
 150                         else\r
 151                         {\r
 152                                 /* Each queue used to receive data from the 'hook' co-routines\r
 153                                 should contain the number we last posted to the same co-routine. */\r
 154                                 if( uxReceivedNumber != uxNumberToPost )\r
 155                                 {\r
 156                                         xCoRoutineErrorDetected = pdTRUE;\r
 157                                 }\r
 158 \r
 159                                 /* Nothing should be blocked waiting to post to the queue. */\r
 160                                 if( xCoRoutineWoken != pdFALSE )\r
 161                                 {\r
 162                                         xCoRoutineErrorDetected = pdTRUE;\r
 163                                 }\r
 164                         }\r
 165                 }\r
 166 \r
 167                 /* Start the next cycle by posting the next number onto each Tx queue. */\r
 168                 uxNumberToPost++;\r
 169 \r
 170                 for( xIndex = 0; xIndex < hookNUM_HOOK_CO_ROUTINES; xIndex++ )\r
 171                 {\r
 172                         if( crQUEUE_SEND_FROM_ISR( xHookTxQueues[ xIndex ], &uxNumberToPost, pdFALSE ) != pdTRUE )\r
 173                         {\r
 174                                 /* Posting to the queue should have woken the co-routine that\r
 175                                 was blocked on the queue. */\r
 176                                 xCoRoutineErrorDetected = pdTRUE;\r
 177                         }\r
 178                 }\r
 179         }\r
 180 }\r
 181 /*-----------------------------------------------------------*/\r
 182 \r
 183 static void prvHookCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 184 {\r
 185 static UBaseType_t uxReceivedValue[ hookNUM_HOOK_CO_ROUTINES ];\r
 186 BaseType_t xResult;\r
 187 \r
 188         /* Each co-routine MUST start with a call to crSTART(); */\r
 189         crSTART( xHandle );\r
 190 \r
 191         for( ;; )\r
 192         {\r
 193                 /* Wait to receive a value from the tick hook. */\r
 194                 xResult = pdFAIL;\r
 195                 crQUEUE_RECEIVE( xHandle, xHookTxQueues[ uxIndex ], &( uxReceivedValue[ uxIndex ] ), portMAX_DELAY, &xResult );\r
 196 \r
 197                 /* There is no reason why we should not have received something on\r
 198                 the queue. */\r
 199                 if( xResult != pdPASS )\r
 200                 {\r
 201                         xCoRoutineErrorDetected = pdTRUE;\r
 202                 }\r
 203 \r
 204                 /* Send the same number back to the idle hook so it can verify it. */\r
 205                 xResult = pdFAIL;\r
 206                 crQUEUE_SEND( xHandle, xHookRxQueues[ uxIndex ], &( uxReceivedValue[ uxIndex ] ), hookNO_BLOCK_TIME, &xResult );\r
 207                 if( xResult != pdPASS )\r
 208                 {\r
 209                         /* There is no reason why we should not have been able to post to\r
 210                         the queue. */\r
 211                         xCoRoutineErrorDetected = pdTRUE;\r
 212                 }\r
 213         }\r
 214 \r
 215         /* Each co-routine MUST end with a call to crEND(). */\r
 216         crEND();\r
 217 }\r
 218 /*-----------------------------------------------------------*/\r
 219 \r
 220 BaseType_t xAreHookCoRoutinesStillRunning( void )\r
 221 {\r
 222         if( xCoRoutineErrorDetected )\r
 223         {\r
 224                 return pdFALSE;\r
 225         }\r
 226         else\r
 227         {\r
 228                 return pdTRUE;\r
 229         }\r
 230 }\r
 231 \r
 232 \r
 233 \r