AM62Px MCU+ SDK  10.01.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.

Example Usage

Include the below file to access the APIs,

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:102
ClockP_Object
Opaque clock object used with the clock APIs.
Definition: ClockP.h:63
ClockP_Params::start
uint32_t start
Definition: ClockP.h:99
ClockP_Params_init
void ClockP_Params_init(ClockP_Params *params)
Set default values to ClockP_Params.
ClockP.h
value
uint32_t value
Definition: tisci_otp_revision.h:2
ClockP_Params
Parameters passed during ClockP_construct.
Definition: ClockP.h:97
ClockP_Params::args
void * args
Definition: ClockP.h:105
ClockP_Params::period
uint32_t period
Definition: ClockP.h:101
ClockP_Params::timeout
uint32_t timeout
Definition: ClockP.h:100
ClockP_usecToTicks
uint64_t ClockP_usecToTicks(uint64_t usecs)
Convert usecs to clock ticks.