len0rd/FreeRTOS-Kernel
1
0
Fork 0
mirror of https://github.com/FreeRTOS/FreeRTOS-Kernel.git synced 2025-06-03 19:09:04 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation of xTaskCheckForTimeOut function to reflect the

Browse source 
intended use of this API.
This commit is contained in:
Gaurav Aggarwal 2019-12-31 20:49:07 +00:00
parent 8f0eaf274c
commit 22dd9a55ab
1 changed files with 86 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

99
FreeRTOS/Source/include/task.h
View file

@ -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;