HAL documentation has some serious error related to HAL_GetTick

[EGi]

The HAL L4 page 38 - but I saw it more also in other doc - has an error how to use HAL_GetTick for timeout:

HAL_StatusTypeDef HAL_PPP_Process(PPP_HandleTypeDef)

timeout = HAL_GetTick() + LOCAL_PROCESS_TIMEOUT;

while(ProcessOngoing)

if (HAL_GetTick() ≥ timeout)

Why I think this is wrong: HAL_GetTick returns a uint32_t counter (at least in the ST libs I checked). This unsigned 32 bit value default increments 1000 times/s and overruns from 0xFFFFFFFF to 0x00000000 after ~49.71 days. Suppose the process started at Tick 0xFFFEDCBA. After adding the the wanted timeout (ex. ~74s), the timeout must trigger when Tick reaches 0x00000123. That value will be correctly calculated in the ST example. But 1 tick after the process started, Tick will be 0xFFFFEDCBB. Since that's bigger than the computed end value 0x123, the code incorrectly triggers a timeout after 1ms instead of 74s.

I believe it's better to do it this way:

uint32_t processStart = HAL_GetTick ();

....

if ((HAL_GetTick () - processStart) >= myAppTimeOut) { } //Timeout.

Here one can see this in the 2's complement result at the moment timeout triggers:

The relative timing code will generate at assembly level an overflow once Tick rolls over to 0x0, but in C that flag is discarded. As long as HAL_GetTick did not roll over to 0x0, the core reports no overflow. The relative timeout will be correctly handled in both cases (regardless if there's an overflow or not).

[Nikita91]

This is a very old problem that has been reported many times before...

https://community.st.com/s/question/0D50X00009XkgXi/years-on-continue-to-see-the-same-bad-timeout-code

[Patrice LF · Accepted solution]

Hi @EGi​ 

Thank your for spotting this documentation issue that mismatches with actual STM32Cube HAL drivers timeout implementation. It was reported internally for a fix in forthcoming releases of User Manual of STM32 series HAL and low-layer drivers.

Regards

Patrice