[U-Boot] [RFC][Timer API] Revised Specification - Implementation details

[Simon Glass]

Hi Graeme,

Thanks very much for doing this. I have been following the discussion
and am very happy that you have continued with it.

On Thu, May 26, 2011 at 6:27 AM, Graeme Russ <graeme.russ at gmail.com> wrote:
> Hello Everyone,
>
> OK - Starting a new thread to discuss implementation details. This is a
> heads-up for arch/platform maintainers - Once this is a bit more stable, I
> will put it on the wiki
>
> Assumed Capabilities of the Platform
>  - Has a 'tick counter' that does not rely on software to increment
>  - tick interval may by a fixed constant which cannot be controlled
>   via software, or it could be programmable (PIT)
>
> API Functions (/lib/timer.c)
>  - u32 get_timer(u32 start)
>    - Returns the number of elapsed milliseconds since 'start'

Can we have a microsecond one also please? Some sort of microsecond
support is needed for udelay anyway. It can be implemented as
get_timer() * 1000 as a fallback. I saw this in your original
proposal. Given the 100 emails you have endured I understand if death
is losing its sting, but it is still a useful feature.

>
> API Functions (/arch/...)
>  - void udelay(u32 delay)
>    - Used for 'short' delays (generally up to several seconds)
>    - Can use the tick counter if it is fast enough
>    - MUST NOT RESET THE TICK COUNTER
>
> 'Helper' Functions (/lib/timer.c)
>  - void sync_timebase(void)
>    - Updates the millisecond timer
>    - Utilises HAL functions to access the platform's tick counter
>    - Must be called more often than the rollover period of the
>      platform's tick counter
>    - Does not need to be called with a regular frequency (immune
>      to interrupt skew)
>    - Is always called by get_timer()
>    - For platforms with short tick counter rollovers it should
>      be called by an ISR
>    - Bill Campbell wrote a good example which proved this can be common
>      and arbitrary (and optionally free of divides and capable of
>      maintaining accuracy even if the tick frequency is not an even
>      division of 1ms)
>
> HAL Functions (/arch/... or /board/...)
>  - u64 get_ticks(void)
>    - Returns a tick count as an unsigned 64-bit integer
>    - Abstracts the implementation of the platform tick counter
>      (platform may by 32-bit 3MHz counter, might be a 16-bit
>      0-999 microsecond plus 16-bit 0-65535 millisecond etc)
>  - u64 ticks_per_millisecond()
>    - Returns the number of ticks (as returned by get_ticks()) per
>      millisecond
>  - void timer_isr()
>    - Optional (particularly if tick counter rollover period is
>      exceptionally log which is usually the case for native 64-bit tick
>      counters)
>    - Simply calls sync_timebase()
>    - For platforms without any tick counter, this can implement one
>      (but accuracy will be harmed due to usage of disable_interrupts() and
>      enable_interrupts() in U-Boot

I suppose this isn't the U-Boot way, but perhaps these could have
names which obviously indicate they are time and HAL-related, and need
to be implemented by a board. Perhaps a timer_ prefix?

>
> So to get the new API up and running, only two functions are mandatory:
>
> get_ticks() which reads the hardware tick counter and deals with any 'funny
> stuff' including rollovers, short timers (12-bit for example), composite
> counters (16-bit 0-999 microsecond + 16-bit millisecond) and maintains a
> 'clean' 64-bit tick counter which rolls over from all 1's to all 0's. The
> 64-bit tick counter does not need to be reset to zero ever (even on startup
> - sync_timebase tacks care of all the details)
>
> ticks_per_millisecond() simply return the number of ticks in a millisecond
> - This may as simple as:
>
> inline u64 ticks_per_millisecond(void)
> {
>        return CONFIG_SYS_TICK_PER_MS;
> }
>
> But it may be trickier if you have a programmable tick frequency

This sounds find as I assume it allows the compiler to optimize to
avoid division, etc. For the microsecond case
ticks_to_microseconds(u64) might be better since the factor may not be
an integer.

>
> The optional timer ISR is required if the tick counter has a short roll
> over duration (short is up to you - 1 second is short, 1 hour might be, 1
> century is not)

Regards,
Simon

>
> Regards,
>
> Graeme
> _______________________________________________
> U-Boot mailing list
> U-Boot at lists.denx.de
> http://lists.denx.de/mailman/listinfo/u-boot
>