Does software timer documentation discuss the case of zero periods?

Kernel
1

pmendham wrote on Tuesday, August 30, 2016:

Dear all,

We make heavy use of one-shot software timers on a number of platforms, including FreeRTOS. When porting to FreeRTOS I made the foolish assumption (without checking the source code) that one-shot timers with a zero period would be valid, but that they would expire immediately. I based this on preconceptions from other platforms, but this is definitely not true on FreeRTOS.

I realise that I should have checked the source, and that this assumption was perhaps a bit daft (especially given that FreeRTOS timers can be periodic and a zero period makes no sense in that case) but I was wondering if there was part of the documentation which explicitly states that a timer with a zero period (either through the create or change functions) was invalid. I may have missed such a statement, in which case I would appreciate it if someone could point me in the right direction for my future reference. If I haven’t missed it, would it be worth consider the addition of an explicit statement about the (in)validity of zero periods just to guard against anyone as foolish as me?

Thanks,

Peter

2

rtel wrote on Tuesday, August 30, 2016:

Hi Peter,

I just checked http://www.freertos.org/FreeRTOS-timers-xTimerCreate.html
to see if this was mentioned. In the “Returns” section it says “If the
timer is created successfully then a handle to the newly created timer
is returned. If the timer cannot be created because either there is
insufficient FreeRTOS heap remaining to allocate the timer structures,
or the timer period was set to 0, then NULL is returned.” So it is
mentioned there. However looking on
http://www.freertos.org/FreeRTOS-timers-xTimerChangePeriod.html there
does not seem to be a mention of it.

I think, from memory, setting a period of 0 will trigger an assertion
failure because, as you said, a periodic timer of period zero would
never stop. I suppose it would be possible to allow periods of zero if
the timer is a one-shot - that might make a nice enhancement.