2 FreeRTOS V7.3.0 - Copyright (C) 2012 Real Time Engineers Ltd.
\r
4 FEATURES AND PORTS ARE ADDED TO FREERTOS ALL THE TIME. PLEASE VISIT
\r
5 http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
\r
7 ***************************************************************************
\r
9 * FreeRTOS tutorial books are available in pdf and paperback. *
\r
10 * Complete, revised, and edited pdf reference manuals are also *
\r
13 * Purchasing FreeRTOS documentation will not only help you, by *
\r
14 * ensuring you get running as quickly as possible and with an *
\r
15 * in-depth knowledge of how to use FreeRTOS, it will also help *
\r
16 * the FreeRTOS project to continue with its mission of providing *
\r
17 * professional grade, cross platform, de facto standard solutions *
\r
18 * for microcontrollers - completely free of charge! *
\r
20 * >>> See http://www.FreeRTOS.org/Documentation for details. <<< *
\r
22 * Thank you for using FreeRTOS, and thank you for your support! *
\r
24 ***************************************************************************
\r
27 This file is part of the FreeRTOS distribution.
\r
29 FreeRTOS is free software; you can redistribute it and/or modify it under
\r
30 the terms of the GNU General Public License (version 2) as published by the
\r
31 Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
\r
32 >>>NOTE<<< The modification to the GPL is included to allow you to
\r
33 distribute a combined work that includes FreeRTOS without being obliged to
\r
34 provide the source code for proprietary components outside of the FreeRTOS
\r
35 kernel. FreeRTOS is distributed in the hope that it will be useful, but
\r
36 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
\r
37 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
\r
38 more details. You should have received a copy of the GNU General Public
\r
39 License and the FreeRTOS license exception along with FreeRTOS; if not it
\r
40 can be viewed here: http://www.freertos.org/a00114.html and also obtained
\r
41 by writing to Richard Barry, contact details for whom are available on the
\r
46 ***************************************************************************
\r
48 * Having a problem? Start by reading the FAQ "My application does *
\r
49 * not run, what could be wrong?" *
\r
51 * http://www.FreeRTOS.org/FAQHelp.html *
\r
53 ***************************************************************************
\r
56 http://www.FreeRTOS.org - Documentation, training, latest versions, license
\r
57 and contact details.
\r
59 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
\r
60 including FreeRTOS+Trace - an indispensable productivity tool.
\r
62 Real Time Engineers ltd license FreeRTOS to High Integrity Systems, who sell
\r
63 the code with commercial support, indemnification, and middleware, under
\r
64 the OpenRTOS brand: http://www.OpenRTOS.com. High Integrity Systems also
\r
65 provide a safety engineered and independently SIL3 certified version under
\r
66 the SafeRTOS brand: http://www.SafeRTOS.com.
\r
70 * Tests the use of queue sets.
\r
72 * A receive task creates a number of queues and adds them to a queue set before
\r
73 * blocking on the queue set receive. A transmit task and (optionally) an
\r
74 * interrupt repeatedly unblocks the receive task by sending messages to the
\r
75 * queues in a pseudo random order. The receive task removes the messages from
\r
76 * the queues and flags an error if the received message does not match that
\r
77 * expected. The task sends values in the range 0 to
\r
78 * queuesetINITIAL_ISR_TX_VALUE, and the ISR sends value in the range
\r
79 * queuesetINITIAL_ISR_TX_VALUE to ULONG_MAX.
\r
82 /* Standard includes. */
\r
86 /* Kernel includes. */
\r
87 #include "FreeRTOS.h"
\r
91 /* Demo includes. */
\r
92 #include "QueueSet.h"
\r
94 /* The number of queues that are created and added to the queue set. */
\r
95 #define queuesetNUM_QUEUES_IN_SET 3
\r
97 /* The length of each created queue. */
\r
98 #define queuesetQUEUE_LENGTH 3
\r
100 /* Block times used in this demo. A block time or 0 means "don't block". */
\r
101 #define queuesetSHORT_DELAY 200
\r
102 #define queuesetDONT_BLOCK 0
\r
104 /* Messages are sent in incrementing order from both a task and an interrupt.
\r
105 The task sends values in the range 0 to 0xfffe, and the interrupt sends values
\r
106 in the range of 0xffff to ULONG_MAX. */
\r
107 #define queuesetINITIAL_ISR_TX_VALUE 0xffffUL
\r
109 /* The priorities used in this demo. */
\r
110 #define queuesetLOW_PRIORITY ( tskIDLE_PRIORITY )
\r
111 #define queuesetMEDIUM_PRIORITY ( queuesetLOW_PRIORITY + 1 )
\r
112 #define queuesetHIGH_PRIORITY ( queuesetMEDIUM_PRIORITY + 1 )
\r
114 /* For test purposes the priority of the sending task is changed after every
\r
115 queuesetPRIORITY_CHANGE_LOOPS number of values are sent to a queue. */
\r
116 #define queuesetPRIORITY_CHANGE_LOOPS 100UL
\r
118 /* The ISR sends to the queue every queuesetISR_TX_PERIOD ticks. */
\r
119 #define queuesetISR_TX_PERIOD 2//( 100UL )
\r
121 /* The allowable maximum deviation between a received value and the expected
\r
122 received value. A deviation will occur when data is received from a queue
\r
123 inside an ISR in between a task receiving from a queue and the task checking
\r
124 the received value. */
\r
125 #define queuesetALLOWABLE_RX_DEVIATION 5
\r
127 * The task that periodically sends to the queue set.
\r
129 static void prvQueueSetSendingTask( void *pvParameters );
\r
132 * The task that reads from the queue set.
\r
134 static void prvQueueSetReceivingTask( void *pvParameters );
\r
137 * Check the value received from a queue is the expected value. Some values
\r
138 * originate from the send task, some values originate from the ISR, with the
\r
139 * range of the value being used to distinguish between the two message
\r
142 static void prvCheckReceivedValue( unsigned long ulReceived );
\r
145 * For purposes of test coverage, functions that read from and write to a
\r
146 * queue set from an ISR respectively.
\r
148 static void prvReceiveFromQueueInSetFromISR( void );
\r
149 static void prvSendToQueueInSetFromISR( void );
\r
152 * Create the queues and add them to a queue set before resuming the Tx
\r
155 static void prvSetupTest( xTaskHandle xQueueSetSendingTask );
\r
158 * Checks a value received from a queue falls within the range of expected
\r
161 static portBASE_TYPE prvCheckReceivedValueWithinExpectedRange( unsigned long ulReceived, unsigned long ulExpectedReceived );
\r
163 /*-----------------------------------------------------------*/
\r
165 /* The queues that are added to the set. */
\r
166 static xQueueHandle xQueues[ queuesetNUM_QUEUES_IN_SET ] = { 0 };
\r
168 /* Counts how many times each queue in the set is used to ensure all the
\r
169 queues are used. */
\r
170 static unsigned long ulQueueUsedCounter[ queuesetNUM_QUEUES_IN_SET ] = { 0 };
\r
172 /* The handle of the queue set to which the queues are added. */
\r
173 static xQueueSetHandle xQueueSet;
\r
175 /* If the prvQueueSetReceivingTask() task has not detected any errors then
\r
176 it increments ulCycleCounter on each iteration.
\r
177 xAreQueueSetTasksStillRunning() returns pdPASS if the value of
\r
178 ulCycleCounter has changed between consecutive calls, and pdFALSE if
\r
179 ulCycleCounter has stopped incrementing (indicating an error condition). */
\r
180 static volatile unsigned long ulCycleCounter = 0UL;
\r
182 /* Set to pdFAIL if an error is detected by any queue set task.
\r
183 ulCycleCounter will only be incremented if xQueueSetTasksSatus equals pdPASS. */
\r
184 static volatile portBASE_TYPE xQueueSetTasksStatus = pdPASS;
\r
186 /* Just a flag to let the function that writes to a queue from an ISR know that
\r
187 the queues are setup and can be used. */
\r
188 static volatile portBASE_TYPE xSetupComplete = pdFALSE;
\r
190 /* The value sent to the queue from the ISR is file scope so the
\r
191 xAreQueeuSetTasksStillRunning() function can check it is incrementing as
\r
193 static volatile unsigned long ulISRTxValue = queuesetINITIAL_ISR_TX_VALUE;
\r
195 /*-----------------------------------------------------------*/
\r
197 void vStartQueueSetTasks( void )
\r
199 xTaskHandle xQueueSetSendingTask;
\r
201 /* Create the two queues. The handle of the sending task is passed into
\r
202 the receiving task using the task parameter. The receiving task uses the
\r
203 handle to resume the sending task after it has created the queues. */
\r
204 xTaskCreate( prvQueueSetSendingTask, ( signed char * ) "SetTx", configMINIMAL_STACK_SIZE, NULL, queuesetMEDIUM_PRIORITY, &xQueueSetSendingTask );
\r
205 xTaskCreate( prvQueueSetReceivingTask, ( signed char * ) "SetRx", configMINIMAL_STACK_SIZE, ( void * ) xQueueSetSendingTask, queuesetMEDIUM_PRIORITY, NULL );
\r
207 /* It is important that the sending task does not attempt to write to a
\r
208 queue before the queue has been created. It is therefore placed into the
\r
209 suspended state before the scheduler has started. It is resumed by the
\r
210 receiving task after the receiving task has created the queues and added the
\r
211 queues to the queue set. */
\r
212 vTaskSuspend( xQueueSetSendingTask );
\r
214 /*-----------------------------------------------------------*/
\r
216 portBASE_TYPE xAreQueueSetTasksStillRunning( void )
\r
218 static unsigned long ulLastCycleCounter, ulLastISRTxValue = 0;
\r
219 static unsigned long ulLastQueueUsedCounter[ queuesetNUM_QUEUES_IN_SET ] = { 0 };
\r
220 portBASE_TYPE xReturn = pdPASS, x;
\r
222 if( ulLastCycleCounter == ulCycleCounter )
\r
224 /* The cycle counter is no longer being incremented. Either one of the
\r
225 tasks is stalled or an error has been detected. */
\r
229 ulLastCycleCounter = ulCycleCounter;
\r
231 /* Ensure that all the queues in the set have been used. This ensures the
\r
232 test is working as intended and guards against the rand() in the Tx task
\r
233 missing some values. */
\r
234 for( x = 0; x < queuesetNUM_QUEUES_IN_SET; x++ )
\r
236 if( ulLastQueueUsedCounter[ x ] == ulQueueUsedCounter[ x ] )
\r
241 ulLastQueueUsedCounter[ x ] = ulQueueUsedCounter[ x ];
\r
244 /* Check the global status flag. */
\r
245 if( xQueueSetTasksStatus != pdPASS )
\r
250 /* Check that the ISR is still sending values to the queues too. */
\r
251 if( ulISRTxValue == ulLastISRTxValue )
\r
257 ulLastISRTxValue = ulISRTxValue;
\r
262 /*-----------------------------------------------------------*/
\r
264 static void prvQueueSetSendingTask( void *pvParameters )
\r
266 unsigned long ulTaskTxValue = 0;
\r
267 portBASE_TYPE xQueueToWriteTo;
\r
268 xQueueHandle xQueueInUse;
\r
269 unsigned portBASE_TYPE uxPriority = queuesetMEDIUM_PRIORITY, ulLoops = 0;
\r
271 /* Remove compiler warning about the unused parameter. */
\r
272 ( void ) pvParameters;
\r
274 srand( ( unsigned int ) &ulTaskTxValue );
\r
278 /* Generate the index for the queue to which a value is to be sent. */
\r
279 xQueueToWriteTo = rand() % queuesetNUM_QUEUES_IN_SET;
\r
280 xQueueInUse = xQueues[ xQueueToWriteTo ];
\r
282 /* Note which index is being written to to ensure all the queues are
\r
284 ( ulQueueUsedCounter[ xQueueToWriteTo ] )++;
\r
286 /* Send to the queue to unblock the task that is waiting for data to
\r
287 arrive on a queue within the queue set to which this queue belongs. */
\r
288 if( xQueueSendToBack( xQueueInUse, &ulTaskTxValue, portMAX_DELAY ) != pdPASS )
\r
290 /* The send should always pass as an infinite block time was
\r
292 xQueueSetTasksStatus = pdFAIL;
\r
297 /* If the Tx value has reached the range used by the ISR then set it
\r
299 if( ulTaskTxValue == queuesetINITIAL_ISR_TX_VALUE )
\r
304 /* Occasionally change the task priority relative to the priority of
\r
305 the receiving task. */
\r
307 if( ulLoops >= queuesetPRIORITY_CHANGE_LOOPS )
\r
311 if( uxPriority > queuesetHIGH_PRIORITY )
\r
313 uxPriority = queuesetLOW_PRIORITY;
\r
316 vTaskPrioritySet( NULL, uxPriority );
\r
320 /*-----------------------------------------------------------*/
\r
322 static void prvQueueSetReceivingTask( void *pvParameters )
\r
324 unsigned long ulReceived;
\r
325 xQueueHandle xActivatedQueue;
\r
326 xTaskHandle xQueueSetSendingTask;
\r
328 /* The handle to the sending task is passed in using the task parameter. */
\r
329 xQueueSetSendingTask = ( xTaskHandle ) pvParameters;
\r
331 /* Create the queues and add them to the queue set before resuming the Tx
\r
333 prvSetupTest( xQueueSetSendingTask );
\r
337 /* Wait for a message to arrive on one of the queues in the set. */
\r
338 xActivatedQueue = xQueueSelectFromSet( xQueueSet, portMAX_DELAY );
\r
339 configASSERT( xActivatedQueue );
\r
341 if( xActivatedQueue == NULL )
\r
343 /* This should not happen as an infinite delay was used. */
\r
344 xQueueSetTasksStatus = pdFAIL;
\r
348 /* Reading from the queue should pass with a zero block time as
\r
349 this task will only run when something has been posted to a task
\r
350 in the queue set. */
\r
351 if( xQueueReceive( xActivatedQueue, &ulReceived, queuesetDONT_BLOCK ) != pdPASS )
\r
353 xQueueSetTasksStatus = pdFAIL;
\r
356 /* Ensure the value received was the value expected. This function
\r
357 manipulates file scope data and is also called from an ISR, hence
\r
358 the critical section. */
\r
359 taskENTER_CRITICAL();
\r
361 prvCheckReceivedValue( ulReceived );
\r
363 taskEXIT_CRITICAL();
\r
366 if( xQueueSetTasksStatus == pdPASS )
\r
372 /*-----------------------------------------------------------*/
\r
374 void vQueueSetAccessQueueSetFromISR( void )
\r
376 static unsigned long ulCallCount = 0;
\r
378 /* xSetupComplete is set to pdTRUE when the queues have been created and
\r
379 are available for use. */
\r
380 if( xSetupComplete == pdTRUE )
\r
382 /* It is intended that this function is called from the tick hook
\r
383 function, so each call is one tick period apart. */
\r
385 if( ulCallCount > queuesetISR_TX_PERIOD )
\r
389 /* First attempt to read from the queue set. */
\r
390 prvReceiveFromQueueInSetFromISR();
\r
392 /* Then write to the queue set. */
\r
393 prvSendToQueueInSetFromISR();
\r
397 /*-----------------------------------------------------------*/
\r
399 static void prvCheckReceivedValue( unsigned long ulReceived )
\r
401 static unsigned long ulExpectedReceivedFromTask = 0, ulExpectedReceivedFromISR = queuesetINITIAL_ISR_TX_VALUE;
\r
403 /* Values are received in tasks and interrupts. It is likely that the
\r
404 receiving task will sometimes get preempted by the receiving interrupt
\r
405 between reading a value from the queue and calling this function. When
\r
406 that happens, if the receiving interrupt calls this function the values
\r
407 will get passed into this function slightly out of order. For that
\r
408 reason the value passed in is tested against a small range of expected
\r
409 values, rather than a single absolute value. To make the range testing
\r
410 easier values in the range limits are ignored. */
\r
412 /* If the received value is equal to or greater than
\r
413 queuesetINITIAL_ISR_TX_VALUE then it was sent by an ISR. */
\r
414 if( ulReceived >= queuesetINITIAL_ISR_TX_VALUE )
\r
416 /* The value was sent from the ISR. */
\r
417 if( ( ulReceived - queuesetINITIAL_ISR_TX_VALUE ) < queuesetALLOWABLE_RX_DEVIATION )
\r
419 /* The value received is at the lower limit of the expected range.
\r
420 Don't test it and expect to receive one higher next time. */
\r
421 ulExpectedReceivedFromISR++;
\r
423 else if( ( ULONG_MAX - ulReceived ) <= queuesetALLOWABLE_RX_DEVIATION )
\r
425 /* The value received is at the higher limit of the expected range.
\r
426 Don't test it and expect to wrap soon. */
\r
427 ulExpectedReceivedFromISR = queuesetINITIAL_ISR_TX_VALUE;
\r
431 /* Check the value against its expected value range. */
\r
432 if( prvCheckReceivedValueWithinExpectedRange( ulReceived, ulExpectedReceivedFromISR ) != pdPASS )
\r
434 xQueueSetTasksStatus = pdFAIL;
\r
438 /* It is expected to receive an incrementing value. */
\r
439 ulExpectedReceivedFromISR++;
\r
445 /* The value was sent from the Tx task. */
\r
446 if( ulReceived < queuesetALLOWABLE_RX_DEVIATION )
\r
448 /* The value received is at the lower limit of the expected range.
\r
449 Don't test it, and expect to receive one higher next time. */
\r
450 ulExpectedReceivedFromTask++;
\r
452 else if( ( ( queuesetINITIAL_ISR_TX_VALUE - 1 ) - ulReceived ) <= queuesetALLOWABLE_RX_DEVIATION )
\r
454 /* The value received is at the higher limit of the expected range.
\r
455 Don't test it and expect to wrap soon. */
\r
456 ulExpectedReceivedFromTask = 0;
\r
460 /* Check the value against its expected value range. */
\r
461 if( prvCheckReceivedValueWithinExpectedRange( ulReceived, ulExpectedReceivedFromTask ) != pdPASS )
\r
463 xQueueSetTasksStatus = pdFAIL;
\r
467 /* It is expected to receive an incrementing value. */
\r
468 ulExpectedReceivedFromTask++;
\r
473 /*-----------------------------------------------------------*/
\r
475 static portBASE_TYPE prvCheckReceivedValueWithinExpectedRange( unsigned long ulReceived, unsigned long ulExpectedReceived )
\r
477 portBASE_TYPE xReturn = pdPASS;
\r
479 if( ulReceived > ulExpectedReceived )
\r
481 configASSERT( ( ulReceived - ulExpectedReceived ) <= queuesetALLOWABLE_RX_DEVIATION );
\r
482 if( ( ulReceived - ulExpectedReceived ) > queuesetALLOWABLE_RX_DEVIATION )
\r
489 configASSERT( ( ulExpectedReceived - ulReceived ) <= queuesetALLOWABLE_RX_DEVIATION );
\r
490 if( ( ulExpectedReceived - ulReceived ) > queuesetALLOWABLE_RX_DEVIATION )
\r
498 /*-----------------------------------------------------------*/
\r
500 static void prvReceiveFromQueueInSetFromISR( void )
\r
502 xQueueSetMemberHandle xActivatedQueue;
\r
503 unsigned long ulReceived;
\r
505 /* See if any of the queues in the set contain data. */
\r
506 xActivatedQueue = xQueueSelectFromSetFromISR( xQueueSet );
\r
508 if( xActivatedQueue != NULL )
\r
510 /* Reading from the queue for test purposes only. */
\r
511 if( xQueueReceiveFromISR( xActivatedQueue, &ulReceived, NULL ) != pdPASS )
\r
513 /* Data should have been available as the handle was returned from
\r
514 xQueueSelectFromSetFromISR(). */
\r
515 xQueueSetTasksStatus = pdFAIL;
\r
518 /* Ensure the value received was the value expected. */
\r
519 prvCheckReceivedValue( ulReceived );
\r
522 /*-----------------------------------------------------------*/
\r
524 static void prvSendToQueueInSetFromISR( void )
\r
526 static portBASE_TYPE xQueueToWriteTo = 0;
\r
528 if( xQueueSendFromISR( xQueues[ xQueueToWriteTo ], ( void * ) &ulISRTxValue, NULL ) == pdPASS )
\r
532 /* If the Tx value has wrapped then set it back to its
\r
534 if( ulISRTxValue == 0UL )
\r
536 ulISRTxValue = queuesetINITIAL_ISR_TX_VALUE;
\r
539 /* Use a different queue next time. */
\r
541 if( xQueueToWriteTo >= queuesetNUM_QUEUES_IN_SET )
\r
543 xQueueToWriteTo = 0;
\r
547 /*-----------------------------------------------------------*/
\r
549 static void prvSetupTest( xTaskHandle xQueueSetSendingTask )
\r
552 xQueueSetMemberHandle xActivatedQueue;
\r
554 /* Ensure the queues are created and the queue set configured before the
\r
555 sending task is unsuspended.
\r
557 First Create the queue set such that it will be able to hold a message for
\r
558 every space in every queue in the set. */
\r
559 xQueueSet = xQueueCreateSet( queuesetNUM_QUEUES_IN_SET * queuesetQUEUE_LENGTH );
\r
561 for( x = 0; x < queuesetNUM_QUEUES_IN_SET; x++ )
\r
563 /* Create the queue and add it to the set. The queue is just holding
\r
564 unsigned long value. */
\r
565 xQueues[ x ] = xQueueCreate( queuesetQUEUE_LENGTH, sizeof( unsigned long ) );
\r
566 configASSERT( xQueues[ x ] );
\r
567 if( xQueueAddToSet( xQueues[ x ], xQueueSet ) != pdPASS )
\r
569 xQueueSetTasksStatus = pdFAIL;
\r
573 /* The queue has now been added to the queue set and cannot be added to
\r
575 if( xQueueAddToSet( xQueues[ x ], xQueueSet ) != pdFAIL )
\r
577 xQueueSetTasksStatus = pdFAIL;
\r
582 /* Attempt to remove a queue from a queue set it does not belong
\r
583 to (NULL being passed as the queue set in this case). */
\r
584 if( xQueueRemoveFromSet( xQueues[ 0 ], NULL ) != pdFAIL )
\r
586 /* It is not possible to successfully remove a queue from a queue
\r
587 set it does not belong to. */
\r
588 xQueueSetTasksStatus = pdFAIL;
\r
591 /* Attempt to remove a queue from the queue set it does belong to. */
\r
592 if( xQueueRemoveFromSet( xQueues[ 0 ], xQueueSet ) != pdPASS )
\r
594 /* It should be possible to remove the queue from the queue set it
\r
596 xQueueSetTasksStatus = pdFAIL;
\r
599 /* Add the queue back again before starting the dynamic tests. */
\r
600 if( xQueueAddToSet( xQueues[ 0 ], xQueueSet ) != pdPASS )
\r
602 /* If the queue was successfully removed from the queue set then it
\r
603 should be possible to add it back in again. */
\r
604 xQueueSetTasksStatus = pdFAIL;
\r
607 /* The task that sends to the queues is not running yet, so attempting to
\r
608 read from the queue set should fail, resulting in xActivatedQueue being set
\r
610 xActivatedQueue = xQueueSelectFromSet( xQueueSet, queuesetSHORT_DELAY );
\r
611 configASSERT( xActivatedQueue == NULL );
\r
613 /* Resume the task that writes to the queues. */
\r
614 vTaskResume( xQueueSetSendingTask );
\r
616 /* Let the ISR access the queues also. */
\r
617 xSetupComplete = pdTRUE;
\r