Alternate time references for OSAL timers

[skliper]

OSAL currently has a timer API which references only to the real time clock in the CPU. All timers created using the OS_TimerCreate() / OS_TimerSet() API are always based on the same clock reference.

However, in an embedded system, a local clock may not always be the real reference for events; many systems derive their timing from an external entity which is NOT necessarily synchronized to the local CPU clock.

This ticket will add a new type of OSAL object called a "Time Base". By default a time base can be driven from the local CPU real time clock, which will mimic the current behavior of timers. However the BSP/PSP may create additional time bases and synchronize them to e.g. an external timing interrupt. The same existing "TimerSet" API can be used to set the timers against the alternate time base and it will be transparent to the app.

[skliper]

Imported from trac issue 15. Created by jphickey on 2015-01-14T14:52:20, last modified: 2015-11-20T16:22:16

[skliper]

Trac comment by jphickey on 2015-04-14 11:19:11:

Commit [changeset:aa83cab] is ready for review

This lays the ground work for an OSAL timer API where the underlying services that measure the passage of time and the services that provide callbacks to user applications are separate.

This adds an API definition for the following new function calls:

• OS_TimeBaseCreate() - Creates a time base object, which is just a generic service to measure the passing of time based on some event, which can be the CPU's RTC but not limited to this.
• OS_TimeBaseSet() - Sets up the time base object
• OS_TimeBaseDelete() - Deletes a time base object
• OS_TimeBaseGetIdByName() - Gets a named time base object
• OS_TimerAdd() - This call is a variation on the OS_TimerCreate() that provides a similar callback mechanism but based on a timebase object instead of OS RTC like OS_TimerCreate() assumes.

The reset of the timer API (all pre-existing OS_Timer* calls) are unchanged, so this remains compatible with all existing code.

[skliper]

Trac comment by dheater on 2015-05-08 13:52:14:

What is the purpose of the timebase_id parameter in OS_TimerAdd? I don't see a similar parameter in any of functions...

[skliper]

Trac comment by jphickey on 2015-05-08 13:57:48:

The timebase_id parameter specifies which TimeBase object that the timer is referencing. Multiple timers can reference the same timebase.

The objective here is to differentiate the real hardware/OS resource - the indication of passage of time - with the software callbacks, of which there could be many...

In fact the OS_Timer implementation in posix-ng is a purely software entity that gives callbacks into the user code -- it does not call directly the OS at all, it goes through the timebase object to get its own time reference.

[skliper]

Trac comment by dheater on 2015-05-15 16:13:21:

OK. Looks good to me.

[skliper]

Trac comment by sstrege on 2015-05-19 10:17:23:

Daniel's question indicates the need to keep the OSAL Library API document up-to-date with these types of changes. User's need to have a reference document for defining the API parameters.

Other than that I approve these changes

[skliper]

Trac comment by glimes on 2015-05-19 14:14:07:

accept

[skliper]

Trac comment by acudmore on 2015-06-02 14:02:10:

accept

[skliper]

Trac comment by glimes on 2015-06-16 12:02:21:

Side note -- I am occasionally seeing the OS_TimerCreate test fail, unable
to allocate as many timers as it wants. Investigating. My hypothesis is that
this is purely a testing issue.

[skliper]

Trac comment by glimes on 2015-07-02 12:42:08:

Commit [changeset:aa83cab] is now included in the OSAL "development" branch
as of the [changeset:2c9c345] merge.