Docs

You are here:
TIM module

Classes

union  TIM_EventID
 
struct  TIM_Time
 
struct  TIM_Capabilities
 

Macros

#define HAL_TIM_USE_INTERRUPT_EVENTS   1
 Enables (1) or disables (0) interrupt level events.
 
#define HAL_TIM_USE_TASK_EVENTS   1
 Enables (1) or disables (0) task level events.
 
#define TIM_NO_EVENT   0xffffffff
 An identifier representing uninitialized (empty) event.
 
#define TIM_Deinit(TIM)   (TIM)->Deinit(TIM)
 
#define TIM_GetTime(TIM)   (TIM)->GetTime(TIM)
 
#define TIM_ResetCounter(TIM)   (TIM)->ResetCounter(TIM)
 
#define TIM_GetCapabilities(TIM, Caps)   (TIM)->GetCapabilities(TIM, Caps)
 
#define TIM_GetError(TIM, TickTimeBase)   (TIM)->GetError(TIM, TickTimeBase)
 

Typedefs

typedef struct TIMDeviceDesc * TIMDevice
 

Enumerations

enum  TIM_EventType { TIM_EVENT_TYPE_NO_TYPE = -1, TIM_EVENT_TYPE_INTERRUPT = 0, TIM_EVENT_TYPE_TASK = 1 }
 

Functions

void TIM_Init (TIMDevice tim, uint32_t TickTimeBase)
 
int64_t TIM_GetTimeInNS (TIMDevice tim)
 
int64_t TIM_GetTimeElapsed (TIMDevice tim, TIM_Time since)
 
TIM_Time TIM_NSToTimTime (TIMDevice tim, int64_t ns)
 
int64_t TIM_TimTimeToNS (TIMDevice tim, TIM_Time t)
 
TIM_EventID TIM_InitEvent (TIMDevice tim, void(*handler)(TIMDevice tim, TIM_EventID event_id, TIM_Time expire_time, void *context), TIM_EventType type, void *context)
 
void TIM_DeinitEvent (TIMDevice tim, TIM_EventID event_id)
 
HALRESULT TIM_ScheduleEvent (TIMDevice tim, TIM_EventID event_id, TIM_Time delta_time)
 
HALRESULT TIM_ScheduleEventAt (TIMDevice tim, TIM_EventID event_id, TIM_Time abs_time)
 
HALRESULT TIM_UnscheduleEvent (TIMDevice tim, TIM_EventID event_id)
 
bool TIM_IsEventScheduled (TIMDevice tim, TIM_EventID event_id)
 
TIM_EventID TIM_SetEventType (TIMDevice tim, TIM_EventID event_id, TIM_EventType type)
 
TIM_EventType TIM_GetEventType (TIM_EventID event_id)
 
TIM_Time TIM_GetTimeToEvent (TIMDevice tim, TIM_EventID event_id)
 
TIM_EventID TIM_GetNextEvent (TIMDevice tim)
 
TIM_Time TIM_GetEventTime (TIMDevice tim, TIM_EventID event_id)
 
void TIM_TaskEventProc (TIMDevice tim)
 
void TIM_InterruptProc (TIMDevice tim)
 
TIM_Time TIM_AddTime (TIMDevice tim, TIM_Time t1, TIM_Time t2)
 
TIM_Time TIM_SubtractTime (TIMDevice tim, TIM_Time t1, TIM_Time t2)
 
int TIM_CompareTime (TIM_Time t1, TIM_Time t2)
 

Detailed Description

Introduction.

TIM module provides time-based functionalities such as free running counter and time-based events. TIM module usually uses internal peripheral timers and timer interrupts to implement periodical time ticks, that become time units. These interrupts also trigger the application-defined events. The events can be executed inside the trigger interrupt service routine (so called interrupt-level events) or in the background task (task-level events). TIM module uses TIMDevice as timer abstraction. Hardware-specific ports are responsible for providing such objects.

Free running counter.

One of the main TIM functionalities is to provide a simple counter that will be incremented periodically with as much precision as possible. This counter is started during timer initialization by a call to TIM_Init. The current value of the counter can be obtained by a call to TIM_GetTime.

Time-based events.

Application can generate time-based events. An event is signaled when a specified amount of time passes. Time based events use free running counter to measure such time periods. When event is signaled an application-defined function (an event handler) can be called.

To create new event and connect an event handler to it the application must call TIM_InitEvent. This call returns event_id that is used to identify the event in the scope of a single TIMDevice.

To schedule an event two functions can be used: TIM_ScheduleEvent and TIM_ScheduleEventAt.

There are two types of events that differ in a way the event handlers are called:

  • The "interrupt-level" events make the event handler functions execute directly in the interrupt service routine (ISR) that triggered the event. Such events must be used with care, and should be as short as possible.
  • The "task-level" events do not call the event handlers from inside the ISR. Instead, they just mark that the event was triggered. The handler is executed during the next call to the TIM_TaskEventProc, which can be in turn called periodically in a OS task or inside some main loop.

The main difference between these two types of event is the response time precision. The response time for "interrupt-level" events is usually shorter, because the event handlers are called directly by the triggering interrupt. These are suited for precise time actions. The "task-level" events usually add some time overhead before the next TIM_TaskEventProc is called. These are suited for less time-critical jobs.

The type of event is declared during event setup (a call to TIM_InitEvent) but it can be changed any time by the TIM_SetEventType. The TIM_GetEventType returns the current type of an event.

Timer setup.

To setup the timer the application must call TIM_Init and provide the timer time base. This time base defines the timer resolution. It's the period between two timer ticks, expressed in nano-seconds. So for example:

TIM_Init(TIM1, 1000);

would setup TIM1 with 1us resolution.

Using TIM events

Let's toggle a LED using events with HAL_TIM1 timer. Let's say we want to toggle every 200ms. To do that we setup HAL_TIM1 to count every 1ms.

// setup timer for 1000000ns = 1ms resolution
TIM_Init(HAL_TIM1, 1000000);

Now, let's create an interrupt-level event and schedule it.

TIM_EventID led_event;
// initialize event
led_event = TIM_InitEvent(HAL_TIM1, event_handler, TIM_EVENT_TYPE_INTERRUPT);
// first event after 100ms from now
t.counter_ticks = 100;
TIM_ScheduleEvent(HAL_TIM1, led_event, t);

We must define the event handler:

void event_handler(TIMDevice tim, TIM_EventID event_id, TIM_Time expire_time)
{
// toggle LED
// re-schedule event
expire_time.counter_ticks += 200;
TIM_ScheduleEventAt(tim, event_id, expire_time);
}

To use the same event as task-level event, the application must periodically call TIM_TaskEventProc, for example in OS task:

void TASK_TIM(void *pvParameters)
{
while(1) {
}
}

Module configuration.

To enable the TIM module, HAL_ENABLE_TIM definition must be set to 1, in hal_config.h. The HAL_TIM_USE_INTERRUPT_EVENTS and HAL_TIM_USE_TASK_EVENTS enable or disable interrupt-level events and task-level events.

Macro Definition Documentation

#define TIM_Deinit (   TIM)    (TIM)->Deinit(TIM)

Deinitializes specified timer object. Stops the running timer.

Parameters
TIMtimer handle
#define TIM_GetCapabilities (   TIM,
  Caps 
)    (TIM)->GetCapabilities(TIM, Caps)

Resets specified timer's counter

Parameters
TIMtimer handle
Capspointer to description structure
#define TIM_GetError (   TIM,
  TickTimeBase 
)    (TIM)->GetError(TIM, TickTimeBase)

Resets specified timer's counter

Parameters
TIMtimer handle
TickTimeBaseselected time base
Returns
selected time base minus actual time base that can be realized by hardware (in nanoseconds)
#define TIM_GetTime (   TIM)    (TIM)->GetTime(TIM)

Returns the number of timer ticks elapsed since the timer was initialized and started running.

Parameters
TIMtimer handle
#define TIM_ResetCounter (   TIM)    (TIM)->ResetCounter(TIM)

Resets specified timer's counter

Parameters
TIMtimer handle

Typedef Documentation

typedef struct TIMDeviceDesc* TIMDevice

TIM Device

Enumeration Type Documentation

Possible event types

Enumerator
TIM_EVENT_TYPE_NO_TYPE 

Uninitialized type of event.

TIM_EVENT_TYPE_INTERRUPT 

This type indicates that the event handler is called from within an interrupt service routine.

TIM_EVENT_TYPE_TASK 

This type indicates, that the event handler is called from a task (and NOT directly in an interrupt service routine).

Function Documentation

TIM_Time TIM_AddTime ( TIMDevice  tim,
TIM_Time  t1,
TIM_Time  t2 
)

Sums up two TIM times.

Parameters
timtimer handler
t1augend
t2addend
Returns
t = t1 + t2
int TIM_CompareTime ( TIM_Time  t1,
TIM_Time  t2 
)

Compares two TIM times.

Parameters
t1first time to compare
t2second time to compare
Return values
1when t1 is greater than t2
-1when t2 is greater than t1
0when the times are equal
void TIM_DeinitEvent ( TIMDevice  tim,
TIM_EventID  event_id 
)

Deinitializes an event. The provided event_id will be reused.

Parameters
timtimer handle
event_idevent id returned by a previous call to TIM_InitEvent or TIM_SetEventType
TIM_Time TIM_GetEventTime ( TIMDevice  tim,
TIM_EventID  event_id 
)

Gets the time at which the given event will be executed.

Parameters
timtimer handler
event_idID of the event
Returns
time at which the event will be executed
TIM_EventType TIM_GetEventType ( TIM_EventID  event_id)

Returns event type

Parameters
event_idID of event that's type we want to get
Returns
Event type
TIM_EventID TIM_GetNextEvent ( TIMDevice  tim)

Gets the next event that will be executed.

Parameters
timtimer handler
Returns
Id of the next event that will be executed
int64_t TIM_GetTimeElapsed ( TIMDevice  tim,
TIM_Time  since 
)

Return timer time in nanoseconds, elapsed since the specified time.

Parameters
timtimer handle
sincereference time
Returns
time in nanoseconds
int64_t TIM_GetTimeInNS ( TIMDevice  tim)

Return timer time in nanoseconds, elapsed since the timer was started.

Parameters
timtimer handle
Returns
time in nanoseconds
TIM_Time TIM_GetTimeToEvent ( TIMDevice  tim,
TIM_EventID  event_id 
)

Returns time left to execute the specified event

Parameters
timtimer handler
event_idID of event
Returns
time to the event
void TIM_Init ( TIMDevice  tim,
uint32_t  TickTimeBase 
)

Initializes the specified timer object and starts the timer.

Parameters
timtimer handle
TickTimeBasetime between timer ticks in nanoseconds
TIM_EventID TIM_InitEvent ( TIMDevice  tim,
void(*)(TIMDevice tim, TIM_EventID event_id, TIM_Time expire_time, void *context)  handler,
TIM_EventType  type,
void *  context 
)

Initializes a new event and connects it's event handler.

Parameters
timtimer handle
handlerevent handler function called when event is triggered
contextevent context passed to the handler function
typeevent type - this can be TIM_EVENT_TYPE_INTERRUPT or TIM_EVENT_TYPE_TASK
Returns
ID of a new event associated with timer or -1 if initialization failed
void TIM_InterruptProc ( TIMDevice  tim)

Calls each handler connected to specified timer that need to be called. This function have to be called in specified interrupt.

Parameters
timtimer handler
bool TIM_IsEventScheduled ( TIMDevice  tim,
TIM_EventID  event_id 
)

Checks if the event is scheduled.

Parameters
timtimer handle
event_idevent id returned by a previous call to TIM_InitEvent or TIM_SetEventType
Returns
true if the event is scheduled, false otherwise
TIM_Time TIM_NSToTimTime ( TIMDevice  tim,
int64_t  ns 
)

Converts nanosecond time to timer time.

Parameters
timtimer handle
nstime in nanoseconds
Returns
time in timer format
HALRESULT TIM_ScheduleEvent ( TIMDevice  tim,
TIM_EventID  event_id,
TIM_Time  delta_time 
)

Schedules an event to be triggered after a specified amount of time.

Parameters
timtimer handle
event_idevent id returned by a previous call to TIM_InitEvent or TIM_SetEventType
delta_time- time after which event will be triggered
Returns
HALRESULT_OK if schedule succeeded, other values indicate error
HALRESULT TIM_ScheduleEventAt ( TIMDevice  tim,
TIM_EventID  event_id,
TIM_Time  abs_time 
)

Schedules an event to be triggered after a specified amount of time.

Parameters
timtimer handle
event_idevent id returned by a previous call to TIM_InitEvent or TIM_SetEventType
abs_time- absolute time at which event will be triggered
Returns
HALRESULT_OK if schedule succeeded, other values indicate error
TIM_EventID TIM_SetEventType ( TIMDevice  tim,
TIM_EventID  event_id,
TIM_EventType  type 
)

Sets event type

Parameters
timtimer handler
event_idID of event that's type we want to set
typenew type of handler
Returns
new Event ID
TIM_Time TIM_SubtractTime ( TIMDevice  tim,
TIM_Time  t1,
TIM_Time  t2 
)

Subtracts two TIM times.

Parameters
timtimer handler
t1minuend
t2subtrahend
Returns
t = t1 - t2
void TIM_TaskEventProc ( TIMDevice  tim)

Calls each handler connected to specified timer that need to be called. This function have to be always called in some loop (in task or "main").

Parameters
timtimer handler
int64_t TIM_TimTimeToNS ( TIMDevice  tim,
TIM_Time  t 
)

Converts timer time to nanosecond time

Parameters
timtimer handle
ttime in timer format
Returns
time in nanoseconds
HALRESULT TIM_UnscheduleEvent ( TIMDevice  tim,
TIM_EventID  event_id 
)

Unschedules an event previously scheduled with TIM_ScheduleEvent or TIM_ScheduleEventAt

Parameters
timtimer handle
event_idevent id
Returns
HALRESULT_OK if unschedule succeeded, other values indicate error
Go to Top