vTaskDelay... documentation update?

Kernel
1

It took me a few days of debugging with a logic analyzer to find out why my delays were not working as expected before I found the answers in these posts:
vTaskDelay and vTaskDelayUntil Strange Behavior
Does vTaskdelay(1) delay up to one tick or circa one tick?

If I summarize:
vTaskDelay(n) will delay a task by a minimum of n-1 ticks. It could be more depending on scheduling, but it can certainly be less than n.

May I propose to update the documentation on the website to reflect this behavior ?

The documentation 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ā€¦

I recommend something along the lines of:

Delay a task for a given number of ticks. The actual time that the task remains blocked depends on the tick rate and the moment in the tick when the function is called. The minimum time the task will block is could be shorter by up to 1 tick. The constantā€¦

What do you think ?

1 Like
2

Thanks for brining this up @maharvey! Iā€™m going to check with a few folks on the team - notably @rtel - and will get back to you.

Overall I love the suggestion.

3

We can certainly update the vTaskDelay() documentation - but this behaviour isnā€™t specific to vTaskDelay() - any function that accepts a block time in ticks (reading from or writing to a queue, stream buffer, message buffer, semaphore, mutex, etc.) has the resolution of the tick frequency, which is an integer. So it may be better to either introduce another section on the website, perhaps under ā€œtask statesā€ where it talks about entering the Blocked state, or in the book, if that doensā€™t already mention it (maybe section 3.7 ā€œTime Measurement and the Tick Interruptā€).

4

Maybe similar to this description: embOS Real-Time Operating System User Guide & Reference Manual

I think some kind of drawing always helps.

1 Like
5

This has also bitten me in the past until I realized that all functions that take a block time n (in ticks) blocks up to n ticks (and when you realize, itā€™s pretty obvious why). To put it another way, if you block/delay for 1 tick, it blocks until the next tick occurs, and so forth.

I think it would be a good idea to document this somewhere where itā€™s unlikely people will miss it.

6

The big problem is that the only place people canā€™t miss it is to repeat it every time it is mentioned (or at least add a reference note each time it is mentioned) which gets very repetitive.

People historically show that they are very bad at looking at general overview sections because they want to just get coding.

1 Like
7

Glad to see that Iā€™m not the only one who struggled with this. I think @rtelā€™s suggestion might be the best here:

So it may be better to either introduce another section on the website, perhaps under ā€œtask statesā€ where it talks about entering the Blocked state

My suggestion is the following then

  1. To have a short dedicated page on the website that explains that on all APIs with delays or timeouts, the first tick is a actual the fraction of a tick (small diagram would help here)
  2. In each API reference page where such delay of timeout parameter is used, have a blanket statement with a link to the dedicated page. ā€œMore info on ticks resolution in the blocked stateā€
8

Hello @maharvey! I realize itā€™s been a while, but I want to let you know Iā€™ve applied your feedback to the FreeRTOS documentation. You can find a detailed page on the tick resolution here as well as a dedicated FAQ item linking to this here.

If you feel like something needs to be better worded or diagrams corrected, donā€™t hesitate to use the ā€˜Report and Error on this pageā€™ option.

2 Likes