AM261x MCU+ SDK: Clock

| AM261x MCU+ SDK 26.00.00 |

Clock

# Features Supported

- Provide system tick functionality using a single timer to periodically interrupt the CPU
- Default tick period is 1000 usecs
- Using this system tick,
  - Users can create arbitrary number of clock objects
  - When a clock object expires, a user specified callback is called
  - Clock expiry time is specified in units of clock ticks
  - Each clock can be started in one-shot callback or periodic callback mode
- Provides APIs to wait 'n' clock ticks, get current clock ticks
- Provides APIs to convert clock ticks to time in usecs and vica versa
- API to get current time in units of usecs

# Features NOT Supported

NA

# Important Usage Guidelines

- The user specific callback can be called in interrupt, SWI or task context depending on the underlying RTOS that is used
  - In no-RTOS case, the callback is called in interrupt context
  - It is recommended to assume that the callback is called in ISR context and not block within the callback.
  - Typically one should do very limited work within the callback itself and defer the larger part of the work to a task via a semaphore post.
- ClockP_usleep and ClockP_sleep will block until the user specified time is expired.
  - In no-RTOS case, there is only a single main task and that will block or spin until the ticks have elasped
  - In RTOS case, the current executing task will 'pend' and schedular will switch to another ready task
  - In both cases ISR's are still active
  - In RTOS case, actual sleep will be in the range of `sleep time - ClockP_ticksToUsec(1)` to `sleep time`. If you need to guarantee atleast minimum sleep of `sleep time`, you need to sleep for `sleep time + ClockP_ticksToUsec(1)`, i.e there will be a error on 1 OS tick at max.
- When using multiple CPUs, make sure each CPU uses a different HW timer else the tick ISR will not trigger as expected.
- Recommended value of tick period is 1ms or 1000us
- Adding any module in SysConfig, automatically adds a clock module with a timer configured for 1ms. The default timer is chosen such that it does not overlap with a timer from another CPU.
- In M4F, the M4F internal SysTick timer is used.
- In R5F, one of the many SOC level timer is used.
- ClockP_getTimeUsec shouldn't be called from an ISR with priority higher than that of Tick Interrupt. This is because Tick interrupt won't be able to preempt the current ISR and ClockP_getTimeUsec may return incorrect value.

# Example Usage

Include the below file to access the APIs,

#include <kernel/dpl/ClockP.h>

Example callback that increments a global counter based on the clock that invoked the callback

uint32_t gOneShotCount = 0;
uint32_t gPeriodicCount = 0;
void myClockCallback(ClockP_Object *obj, void *arg)
{
uint32_t *value = (uint32_t*)arg;
(*value)++; /* increment number of time's this callback is called */
}

Example usage to create a clock in one shot mode wit timer expiery of 10ms

ClockP_Params clockParams;
ClockP_Object clockObj;
ClockP_Params_init(&clockParams);
clockParams.timeout = ClockP_usecToTicks(10*1000);
clockParams.start = 1;
clockParams.callback = myClockCallback;
clockParams.args = &gOneShotCount; /* pass address of counter which is incremented in the callback */
ClockP_construct(&clockObj, &clockParams);

Example usage to create a clock in one shot mode with timer period of 100ms

ClockP_Params clockParams;
ClockP_Object clockObj;
ClockP_Params_init(&clockParams);
clockParams.timeout = ClockP_usecToTicks(100*1000);
clockParams.period = clockParams.timeout;
clockParams.start = 1;
clockParams.callback = myClockCallback;
clockParams.args = &gPeriodicCount; /* pass address of counter which is incremented in the callback */
ClockP_construct(&clockObj, &clockParams);

Example usage to measure time and profile a function

uint64_t curTimeInUsecs;
curTimeInUsecs = ClockP_getTimeUsec();
// code or functions to profile
// func1()
// func2()
curTimeInUsecs = ClockP_getTimeUsec() - curTimeInUsecs;

# API

APIs for Clock

ClockP_getTimeUsec
uint64_t ClockP_getTimeUsec(void)
Get current time in units of usecs.
ClockP_construct
int32_t ClockP_construct(ClockP_Object *obj, ClockP_Params *params)
Create a clock object.
ClockP_Params::callback
ClockP_FxnCallback callback
Definition: ClockP.h:123
ClockP_Params::start
uint32_t start
Definition: ClockP.h:120
ClockP_Params_init
void ClockP_Params_init(ClockP_Params *params)
Set default values to ClockP_Params.
ClockP.h
ClockP_Params
Parameters passed during ClockP_construct.
Definition: ClockP.h:118
ClockP_Params::args
void * args
Definition: ClockP.h:126
ClockP_Params::period
uint32_t period
Definition: ClockP.h:122
ClockP_usecToTicks
uint32_t ClockP_usecToTicks(uint64_t usecs)
Convert usecs to clock ticks.
ClockP_Params::timeout
uint32_t timeout
Definition: ClockP.h:121