From 23d9c29e025cc0815ab214d11d9d37ea78b9d025 Mon Sep 17 00:00:00 2001 From: rtel Date: Wed, 1 Jan 2020 22:24:44 +0000 Subject: [PATCH] Minor updates to comment block for xTaskCheckForTimeOut(). git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@2791 1d2547de-c912-0410-9cb9-b8ca96c0e9e2 --- FreeRTOS/Source/include/task.h | 181 ++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 84 deletions(-) diff --git a/FreeRTOS/Source/include/task.h b/FreeRTOS/Source/include/task.h index e05354dfa..6d9548ea1 100644 --- a/FreeRTOS/Source/include/task.h +++ b/FreeRTOS/Source/include/task.h @@ -2201,6 +2201,103 @@ uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait */ BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask ); +/** + * task.h + * 
void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut )
+ * + * Capture the current time for future use with xTaskCheckForTimeOut(). + * + * @param pxTimeOut Pointer to a timeout object into which the current time + * is to be captured. The captured time includes the tick count and the number + * of times the tick count has overflowed since the system first booted. + * \defgroup vTaskSetTimeOutState vTaskSetTimeOutState + * \ingroup TaskCtrl + */ +void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut ) PRIVILEGED_FUNCTION; + +/** + * task.h + * 
BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait );
+ * + * Determines if pxTicksToWait ticks has passed since a time was captured + * using a call to vTaskSetTimeOutState(). The captured time includes the tick + * count and the number of times the tick count has overflowed. + * + * @param 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 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, pxTIcksToWait is updated to reflect the + * number of remaining 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;
+	}
+
+ * \defgroup xTaskCheckForTimeOut xTaskCheckForTimeOut + * \ingroup TaskCtrl + */ +BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut, TickType_t * const pxTicksToWait ) PRIVILEGED_FUNCTION; + /*----------------------------------------------------------- * SCHEDULER INTERNALS AVAILABLE FOR PORTING PURPOSES *----------------------------------------------------------*/ @@ -2317,90 +2414,6 @@ TickType_t uxTaskResetEventItemValue( void ) PRIVILEGED_FUNCTION; */ 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 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; - /* * Shortcut used by the queue implementation to prevent unnecessary call to * taskYIELD(); -- 2.39.2