vTaskDelay() documentation request

[BryghtLabs-Richard]

With respect to: vTaskDelay() - FreeRTOS™, which currently states:

Delay a task for a given number of ticks. The actual time that the task remains blocked depends on the tick rate. The constant portTICK_PERIOD_MS can be used to calculate real time from the tick rate - with the resolution of one tick period.

After reviewing how vTaskDelay() works, the documentation doesn’t conflict with what it does, but I think documenting a few specific cases may help people familiar with different RTOSs quickly understand the specifics of vTaskDelay().

vTaskDelay(0); From the documentation it sounds like this might do nothing. It yields to other tasks of the same priority.

Documenting vTaskDelay(1); blocks until the next timer tick, <= portTICK_PERIOD_MS of realtime, helps make the distinction between tick-intervals and tick-events. If I understand it, ‘ticks’ means ‘tick-events’, and not ‘tick-intervals’, it’s understandable from the existing text, but if you don’t know that, you might assume vTaskDelay(1); blocks for up to two ticks, so that at least one whole interval has been delayed. If applications you need to guarantee a minimum interval, they need to add the +1 themselves for FreeRTOS.(not a criticism, just a detail I had to search for).

There’s a longer explanation here from 2012: vTaskDelay(0) vs vTaskDelay(1)

[rohitmdn (Rohit Madan)]

Hi @BryghtLabs-Richard, thanks for pointing this out.

@BryghtLabs-Richard

vTaskDelay(0); From the documentation it sounds like this might do nothing. It yields to other tasks of the same priority.

Yes, this is correct. It shall yield to next ready task of equal priority. We will add this to our documentation.

@BryghtLabs-Richard

If I understand it, ‘ticks’ means ‘tick-events’, and not ‘tick-intervals’,

Yes, FreeRTOS measures time using a tick count variable. Tick-event that you are referring is basically the tick-interrupt to check if any high priority task got readied.

@BryghtLabs-Richard

you might assume vTaskDelay(1); blocks for up to two ticks, so that at least one whole interval has been delayed.

I think this confusion is caused by this example here.
Instead of adding documentation case-specific to vTaskDelay(1), we are thinking of updating the example to say

For example, specifying a block period of 100 ticks will cause the task to remain
blocked for 100 ticks after vTaskDelay() is called. The task will be unblocked on
the 100th tick after vTaskDelay is called.

We are planning to add the 0 input case that you pointed out and for the other case update the example in the next website deployment. Let us know what you think.
Thanks for pointing out !

[BryghtLabs-Richard]

Thanks @rohitmdn , your update looks great to me.

I’ve seen the behaviours for (0/1/#) vary widely across different operating systems, so it’s nice to have these specifics included in the documentation.