Clarify OS_GetLocalTime/OS_SetLocalTime use in relation to OSAL_GETTIME_SOURCE_CLOCK

[skliper]

Is your feature request related to a problem? Please describe.
Not really clear/consistent on OS_SetLocalTime and OS_GetLocalTime in relation to OSAL_GETTIME_SOURCE_CLOCK. Currently defaulted to CLOCK_MONOTONIC, so a OS_SetLocalTime may fail. Really need to clarify intent of the design/APIs to be more clear on how they should be used since the OSAL_GETTIME_SOURCE_CLOCK is used in both and the setting has different impacts in the different contexts.

Describe the solution you'd like
May benefit from individual configuration parameters, or maybe OS_SetLocalTime should never be CLOCK_MONOTONIC. Add a bit more context to API/configuration documentation. Use cases?

Describe alternatives you've considered
Anything to clarify/explain intent.

Additional context
Debated "bug", could switch.

Requester Info
Jacob Hageman - NASA/GSFC, OSAL code review

[jphickey]

I looked into the use cases of these functions:

• OS_SetLocalTime() is not used/invoked by any framework code nor any GSFC CFS app. The only place this is called is in the tests.
• OS_GetLocalTime() is used in a couple limited spots, but not to get the "real" time - it calls it multiple times and gets the difference between the samples to find the elapsed time between them.

In particular on pc-linux the CFE PSP uses OS_GetLocalTime() to implement the PSP timebase used for performance monitoring. In this case it is important that the clock used by this is stable over time and is NOT reset (which would break the perflog creating a discontinuity).

Given these use-cases, I think it is correct to be using MONOTONIC to implement this. However I agree it is a misnomer, as the "LocalTime" name suggests it is indeed a calendar time of some sort.

Perhaps we need a different function?

The CFE PSP use case can (and probably should) be changed to call the clock_gettime directly, then maybe this can be defined as a real time/calendar time.