Update documentation of xTaskCheckForTimeOut function to reflect the
intended use of this API.
diff --git a/FreeRTOS/Source/include/task.h b/FreeRTOS/Source/include/task.h
index b4e246f..e05354d 100644
--- a/FreeRTOS/Source/include/task.h
+++ b/FreeRTOS/Source/include/task.h
@@ -314,13 +314,13 @@
// 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 @@
// 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 @@
// 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 @@
/*
* 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;
