Update documentation of xTaskCheckForTimeOut function to reflect the

intended use of this API.

git-svn-id: http://svn.code.sf.net/p/freertos/code/trunk@2786 1d2547de-c912-0410-9cb9-b8ca96c0e9e2

1 files changed, 86 insertions, 13 deletions

diff --git a/FreeRTOS/Source/include/task.h b/FreeRTOS/Source/include/task.h
index b4e246fb9..e05354dfa 100644
--- a/FreeRTOS/Source/include/task.h
+++ b/FreeRTOS/Source/include/task.h
@@ -314,13 +314,13 @@ is used in assert() statements. */
 	 // an automatic stack variable it might no longer exist, or at least have been corrupted, by the time

 	 // the new task attempts to access it.

 	 xTaskCreate( vTaskCode, "NAME", STACK_SIZE, &ucParameterToPass, tskIDLE_PRIORITY, &xHandle );

-     configASSERT( xHandle );

+	 configASSERT( xHandle );

 

 	 // Use the handle to delete the task.

-     if( xHandle != NULL )

-     {

-	     vTaskDelete( xHandle );

-     }

+	 if( xHandle != NULL )

+	 {

+	 	vTaskDelete( xHandle );

+	 }

  }

    </pre>

  * \defgroup xTaskCreate xTaskCreate

@@ -498,9 +498,9 @@ static const TaskParameters_t xCheckTaskParameters =
 	// for full information.

 	{

 		// Base address					Length	Parameters

-        { cReadWriteArray,				32,		portMPU_REGION_READ_WRITE },

-        { cReadOnlyArray,				32,		portMPU_REGION_READ_ONLY },

-        { cPrivilegedOnlyAccessArray,	128,	portMPU_REGION_PRIVILEGED_READ_WRITE }

+		{ cReadWriteArray,				32,		portMPU_REGION_READ_WRITE },

+		{ cReadOnlyArray,				32,		portMPU_REGION_READ_ONLY },

+		{ cPrivilegedOnlyAccessArray,	128,	portMPU_REGION_PRIVILEGED_READ_WRITE }

 	}

 };

 

@@ -584,9 +584,9 @@ static const TaskParameters_t xCheckTaskParameters =
 	// for full information.

 	{

 		// Base address					Length	Parameters

-        { cReadWriteArray,				32,		portMPU_REGION_READ_WRITE },

-        { cReadOnlyArray,				32,		portMPU_REGION_READ_ONLY },

-        { cPrivilegedOnlyAccessArray,	128,	portMPU_REGION_PRIVILEGED_READ_WRITE }

+		{ cReadWriteArray,				32,		portMPU_REGION_READ_WRITE },

+		{ cReadOnlyArray,				32,		portMPU_REGION_READ_ONLY },

+		{ cPrivilegedOnlyAccessArray,	128,	portMPU_REGION_PRIVILEGED_READ_WRITE }

 	}

 

 	&xTaskBuffer; // Holds the task's data structure.

@@ -2319,12 +2319,85 @@ TaskHandle_t xTaskGetCurrentTaskHandle( void ) PRIVILEGED_FUNCTION;
 

 /*

  * Capture the current time status for future reference.

+ *

+ * @param[out] pxTimeOut Pointer to a timeout object into which the current

+ * time status is to be captured.

  */

 void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION;

 

 /*

- * Compare the time status now with that previously captured to see if the

- * timeout has expired.

+ * Compare the time status now with the one previously captured using

+ * vTaskSetTimeOutState to check if the timeout has occurred.

+ *

+ * @param[in/out] pxTimeOut The time status as captured previously using

+ * vTaskSetTimeOutState. If the timeout has not yet occurred, it is updated

+ * to reflect the current time status.

+ * @param[in/out] pxTicksToWait The number of ticks to check for timeout i.e. if

+ * pxTicksToWait ticks have passed since pxTimeOut was last updated (either by

+ * vTaskSetTimeOutState or xTaskCheckForTimeOut), the timeout has occurred. If

+ * the timeout has not occurred, it is updated to reflect the number of

+ * reamaining ticks.

+ *

+ * @return If timeout has occurred, pdTRUE is returned. Otherwise pdFALSE is

+ * returned and pxTicksToWait is updated to reflect the number of remaining

+ * ticks.

+ *

+ * @see https://www.freertos.org/xTaskCheckForTimeOut.html

+ *

+ * Example Usage:

+ *

+ * // Driver library function used to receive uxWantedBytes from an Rx buffer

+ * // that is filled by a UART interrupt. If there are not enough bytes in the

+ * // Rx buffer then the task enters the Blocked state until it is notified that

+ * // more data has been placed into the buffer. If there is still not enough

+ * // data then the task re-enters the Blocked state, and xTaskCheckForTimeOut()

+ * // is used to re-calculate the Block time to ensure the total amount of time

+ * // spent in the Blocked state does not exceed MAX_TIME_TO_WAIT. This

+ * // continues until either the buffer contains at least uxWantedBytes bytes,

+ * // or the total amount of time spent in the Blocked state reaches

+ * // MAX_TIME_TO_WAIT – at which point the task reads however many bytes are

+ * // available up to a maximum of uxWantedBytes.

+ *

+ * size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )

+ * {

+ * size_t uxReceived = 0;

+ * TickType_t xTicksToWait = MAX_TIME_TO_WAIT;

+ * TimeOut_t xTimeOut;

+ * 

+ * 		// Initialize xTimeOut.  This records the time at which this function

+ * 		// was entered.

+ * 		vTaskSetTimeOutState( &xTimeOut );

+ * 

+ * 		// Loop until the buffer contains the wanted number of bytes, or a

+ * 		// timeout occurs.

+ * 		while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )

+ * 		{

+ * 			// The buffer didn't contain enough data so this task is going to

+ * 			// enter the Blocked state. Adjusting xTicksToWait to account for

+ * 			// any time that has been spent in the Blocked state within this

+ * 			// function so far to ensure the total amount of time spent in the

+ * 			// Blocked state does not exceed MAX_TIME_TO_WAIT.

+ *			if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )

+ * 			{

+ * 				//Timed out before the wanted number of bytes were available,

+ * 				// exit the loop.

+ * 				break;

+ * 			}

+ *

+ * 			// Wait for a maximum of xTicksToWait ticks to be notified that the

+ * 			// receive interrupt has placed more data into the buffer.

+ * 			ulTaskNotifyTake( pdTRUE, xTicksToWait );

+ * 		}

+ * 

+ * 		// Attempt to read uxWantedBytes from the receive buffer into pucBuffer.

+ * 		// The actual number of bytes read (which might be less than

+ * 		// uxWantedBytes) is returned.

+ * 		uxReceived = UART_read_from_receive_buffer( pxUARTInstance,

+ * 													pucBuffer,

+ * 													uxWantedBytes );

+ *

+ * 		return uxReceived;

+ * }

  */

 BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION;