2 FreeRTOS V4.0.1 - Copyright (C) 2003-2006 Richard Barry.
\r
4 This file is part of the FreeRTOS distribution.
\r
6 FreeRTOS is free software; you can redistribute it and/or modify
\r
7 it under the terms of the GNU General Public License as published by
\r
8 the Free Software Foundation; either version 2 of the License, or
\r
9 (at your option) any later version.
\r
11 FreeRTOS is distributed in the hope that it will be useful,
\r
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\r
14 GNU General Public License for more details.
\r
16 You should have received a copy of the GNU General Public License
\r
17 along with FreeRTOS; if not, write to the Free Software
\r
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
\r
20 A special exception to the GPL can be applied should you wish to distribute
\r
21 a combined work that includes FreeRTOS, without being obliged to provide
\r
22 the source code for any proprietary components. See the licensing section
\r
23 of http://www.FreeRTOS.org for full details of how and when the exception
\r
26 ***************************************************************************
\r
27 See http://www.FreeRTOS.org for documentation, latest information, license
\r
28 and contact details. Please ensure to read the configuration and relevant
\r
29 port sections of the online documentation.
\r
30 ***************************************************************************
\r
36 typedef void * xQueueHandle;
\r
41 xQueueHandle xQueueCreate(
\r
42 unsigned portBASE_TYPE uxQueueLength,
\r
43 unsigned portBASE_TYPE uxItemSize
\r
47 * Creates a new queue instance. This allocates the storage required by the
\r
48 * new queue and returns a handle for the queue.
\r
50 * @param uxQueueLength The maximum number of items that the queue can contain.
\r
52 * @param uxItemSize The number of bytes each item in the queue will require.
\r
53 * Items are queued by copy, not by reference, so this is the number of bytes
\r
54 * that will be copied for each posted item. Each item on the queue must be
\r
57 * @return If the queue is successfully create then a handle to the newly
\r
58 * created queue is returned. If the queue cannot be created then 0 is
\r
65 portCHAR ucMessageID;
\r
66 portCHAR ucData[ 20 ];
\r
69 void vATask( void *pvParameters )
\r
71 xQueueHandle xQueue1, xQueue2;
\r
73 // Create a queue capable of containing 10 unsigned long values.
\r
74 xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );
\r
77 // Queue was not created and must not be used.
\r
80 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
81 // These should be passed by pointer as they contain a lot of data.
\r
82 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
85 // Queue was not created and must not be used.
\r
88 // ... Rest of task code.
\r
91 * \defgroup xQueueCreate xQueueCreate
\r
92 * \ingroup QueueManagement
\r
94 xQueueHandle xQueueCreate( unsigned portBASE_TYPE uxQueueLength, unsigned portBASE_TYPE uxItemSize );
\r
99 portBASE_TYPE xQueueSend(
\r
100 xQueueHandle xQueue,
\r
101 const void * pvItemToQueue,
\r
102 portTickType xTicksToWait
\r
106 * Post an item on a queue. The item is queued by copy, not by reference.
\r
107 * This function must not be called from an interrupt service routine.
\r
108 * See xQueueSendFromISR () for an alternative which may be used in an ISR.
\r
110 * @param xQueue The handle to the queue on which the item is to be posted.
\r
112 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
113 * queue. The size of the items the queue will hold was defined when the
\r
114 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
115 * into the queue storage area.
\r
117 * @param xTicksToWait The maximum amount of time the task should block
\r
118 * waiting for space to become available on the queue, should it already
\r
119 * be full. The call will return immediately if this is set to 0. The
\r
120 * time is defined in tick periods so the constant portTICK_RATE_MS
\r
121 * should be used to convert to real time if this is required.
\r
123 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
129 portCHAR ucMessageID;
\r
130 portCHAR ucData[ 20 ];
\r
133 unsigned portLONG ulVar = 10UL;
\r
135 void vATask( void *pvParameters )
\r
137 xQueueHandle xQueue1, xQueue2;
\r
138 struct AMessage *pxMessage;
\r
140 // Create a queue capable of containing 10 unsigned long values.
\r
141 xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );
\r
143 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
144 // These should be passed by pointer as they contain a lot of data.
\r
145 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
151 // Send an unsigned long. Wait for 10 ticks for space to become
\r
152 // available if necessary.
\r
153 if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )
\r
155 // Failed to post the message, even after 10 ticks.
\r
161 // Send a pointer to a struct AMessage object. Don't block if the
\r
162 // queue is already full.
\r
163 pxMessage = & xMessage;
\r
164 xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );
\r
167 // ... Rest of task code.
\r
170 * \defgroup xQueueSend xQueueSend
\r
171 * \ingroup QueueManagement
\r
173 signed portBASE_TYPE xQueueSend( xQueueHandle xQueue, const void * pvItemToQueue, portTickType xTicksToWait );
\r
178 portBASE_TYPE xQueueReceive(
\r
179 xQueueHandle xQueue,
\r
181 portTickType xTicksToWait
\r
184 * Receive an item from a queue. The item is received by copy so a buffer of
\r
185 * adequate size must be provided. The number of bytes copied into the buffer
\r
186 * was defined when the queue was created.
\r
188 * This function must not be used in an interrupt service routine. See
\r
189 * xQueueReceiveFromISR for an alternative that can.
\r
191 * @param pxQueue The handle to the queue from which the item is to be
\r
194 * @param pvBuffer Pointer to the buffer into which the received item will
\r
197 * @param xTicksToWait The maximum amount of time the task should block
\r
198 * waiting for an item to receive should the queue be empty at the time
\r
199 * of the call. The time is defined in tick periods so the constant
\r
200 * portTICK_RATE_MS should be used to convert to real time if this is required.
\r
202 * @return pdTRUE if an item was successfully received from the queue,
\r
203 * otherwise pdFALSE.
\r
209 portCHAR ucMessageID;
\r
210 portCHAR ucData[ 20 ];
\r
213 xQueueHandle xQueue;
\r
215 // Task to create a queue and post a value.
\r
216 void vATask( void *pvParameters )
\r
218 struct AMessage *pxMessage;
\r
220 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
221 // These should be passed by pointer as they contain a lot of data.
\r
222 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
225 // Failed to create the queue.
\r
230 // Send a pointer to a struct AMessage object. Don't block if the
\r
231 // queue is already full.
\r
232 pxMessage = & xMessage;
\r
233 xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );
\r
235 // ... Rest of task code.
\r
238 // Task to receive from the queue.
\r
239 void vADifferentTask( void *pvParameters )
\r
241 struct AMessage *pxRxedMessage;
\r
245 // Receive a message on the created queue. Block for 10 ticks if a
\r
246 // message is not immediately available.
\r
247 if( xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )
\r
249 // pcRxedMessage now points to the struct AMessage variable posted
\r
254 // ... Rest of task code.
\r
257 * \defgroup xQueueReceive xQueueReceive
\r
258 * \ingroup QueueManagement
\r
260 signed portBASE_TYPE xQueueReceive( xQueueHandle xQueue, void *pvBuffer, portTickType xTicksToWait );
\r
264 * <pre>unsigned portBASE_TYPE uxQueueMessagesWaiting( xQueueHandle xQueue );</pre>
\r
266 * Return the number of messages stored in a queue.
\r
268 * @param xQueue A handle to the queue being queried.
\r
270 * @return The number of messages available in the queue.
\r
272 * \page uxQueueMessagesWaiting uxQueueMessagesWaiting
\r
273 * \ingroup QueueManagement
\r
275 unsigned portBASE_TYPE uxQueueMessagesWaiting( xQueueHandle xQueue );
\r
279 * <pre>void vQueueDelete( xQueueHandle xQueue );</pre>
\r
281 * Delete a queue - freeing all the memory allocated for storing of items
\r
282 * placed on the queue.
\r
284 * @param xQueue A handle to the queue to be deleted.
\r
286 * \page vQueueDelete vQueueDelete
\r
287 * \ingroup QueueManagement
\r
289 void vQueueDelete( xQueueHandle xQueue );
\r
294 portBASE_TYPE xQueueSendFromISR(
\r
295 xQueueHandle pxQueue,
\r
296 const void *pvItemToQueue,
\r
297 portBASE_TYPE xTaskPreviouslyWoken
\r
301 * Post an item on a queue. It is safe to use this function from within an
\r
302 * interrupt service routine.
\r
304 * Items are queued by copy not reference so it is preferable to only
\r
305 * queue small items, especially when called from an ISR. In most cases
\r
306 * it would be preferable to store a pointer to the item being queued.
\r
308 * @param xQueue The handle to the queue on which the item is to be posted.
\r
310 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
311 * queue. The size of the items the queue will hold was defined when the
\r
312 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
313 * into the queue storage area.
\r
315 * @param cTaskPreviouslyWoken This is included so an ISR can post onto
\r
316 * the same queue multiple times from a single interrupt. The first call
\r
317 * should always pass in pdFALSE. Subsequent calls should pass in
\r
318 * the value returned from the previous call. See the file serial .c in the
\r
319 * PC port for a good example of this mechanism.
\r
321 * @return pdTRUE if a task was woken by posting onto the queue. This is
\r
322 * used by the ISR to determine if a context switch may be required following
\r
325 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
328 void vBufferISR( void )
\r
331 portBASE_TYPE xTaskWokenByPost;
\r
333 // We have not woken a task at the start of the ISR.
\r
334 cTaskWokenByPost = pdFALSE;
\r
336 // Loop until the buffer is empty.
\r
339 // Obtain a byte from the buffer.
\r
340 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
342 // Post the byte. The first time round the loop cTaskWokenByPost
\r
343 // will be pdFALSE. If the queue send causes a task to wake we do
\r
344 // not want the task to run until we have finished the ISR, so
\r
345 // xQueueSendFromISR does not cause a context switch. Also we
\r
346 // don't want subsequent posts to wake any other tasks, so we store
\r
347 // the return value back into cTaskWokenByPost so xQueueSendFromISR
\r
348 // knows not to wake any task the next iteration of the loop.
\r
349 xTaskWokenByPost = xQueueSendFromISR( xRxQueue, &cIn, cTaskWokenByPost );
\r
351 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
353 // Now the buffer is empty we can switch context if necessary.
\r
354 if( cTaskWokenByPost )
\r
361 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
362 * \ingroup QueueManagement
\r
364 signed portBASE_TYPE xQueueSendFromISR( xQueueHandle pxQueue, const void *pvItemToQueue, signed portBASE_TYPE xTaskPreviouslyWoken );
\r
369 portBASE_TYPE xQueueReceiveFromISR(
\r
370 xQueueHandle pxQueue,
\r
372 portBASE_TYPE *pxTaskWoken
\r
376 * Receive an item from a queue. It is safe to use this function from within an
\r
377 * interrupt service routine.
\r
379 * @param pxQueue The handle to the queue from which the item is to be
\r
382 * @param pvBuffer Pointer to the buffer into which the received item will
\r
385 * @param pxTaskWoken A task may be blocked waiting for space to become
\r
386 * available on the queue. If xQueueReceiveFromISR causes such a task to
\r
387 * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will
\r
388 * remain unchanged.
\r
390 * @return pdTRUE if an item was successfully received from the queue,
\r
391 * otherwise pdFALSE.
\r
396 xQueueHandle xQueue;
\r
398 // Function to create a queue and post some values.
\r
399 void vAFunction( void *pvParameters )
\r
401 portCHAR cValueToPost;
\r
402 const portTickType xBlockTime = ( portTickType )0xff;
\r
404 // Create a queue capable of containing 10 characters.
\r
405 xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
\r
408 // Failed to create the queue.
\r
413 // Post some characters that will be used within an ISR. If the queue
\r
414 // is full then this task will block for xBlockTime ticks.
\r
415 cValueToPost = 'a';
\r
416 xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
\r
417 cValueToPost = 'b';
\r
418 xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
\r
420 // ... keep posting characters ... this task may block when the queue
\r
423 cValueToPost = 'c';
\r
424 xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
\r
427 // ISR that outputs all the characters received on the queue.
\r
428 void vISR_Routine( void )
\r
430 portBASE_TYPE xTaskWokenByReceive = pdFALSE;
\r
431 portCHAR cRxedChar;
\r
433 while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )
\r
435 // A character was received. Output the character now.
\r
436 vOutputCharacter( cRxedChar );
\r
438 // If removing the character from the queue woke the task that was
\r
439 // posting onto the queue cTaskWokenByReceive will have been set to
\r
440 // pdTRUE. No matter how many times this loop iterates only one
\r
441 // task will be woken.
\r
444 if( cTaskWokenByPost != ( portCHAR ) pdFALSE;
\r
450 * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR
\r
451 * \ingroup QueueManagement
\r
453 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle pxQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken );
\r
457 * The functions defined above are for passing data to and from tasks. The
\r
458 * functions below are the equivalents for passing data to and from
\r
461 * These functions are called from the co-routine macro implementation and
\r
462 * should not be called directly from application code. Instead use the macro
\r
463 * wrappers defined within croutine.h.
\r
465 signed portBASE_TYPE xQueueCRSendFromISR( xQueueHandle pxQueue, const void *pvItemToQueue, signed portBASE_TYPE xCoRoutinePreviouslyWoken );
\r
466 signed portBASE_TYPE xQueueCRReceiveFromISR( xQueueHandle pxQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken );
\r
467 signed portBASE_TYPE xQueueCRSend( xQueueHandle pxQueue, const void *pvItemToQueue, portTickType xTicksToWait );
\r
468 signed portBASE_TYPE xQueueCRReceive( xQueueHandle pxQueue, void *pvBuffer, portTickType xTicksToWait );
\r