timer.h File Reference

#include <limits.h>
#include <stdbool.h>
#include <stddef.h>
#include "ecu/dlist.h"

Include dependency graph for timer.h:

Go to the source code of this file.

Data Structures
struct	ecu_timer
	Timer object represented as node in linked list. More...
struct	ecu_tlist
	Timer linked list that runs all software timers (ecu_timer) added to it. Each list usually holds multiple software timers but maps to a single hardware timer on the user's target device. More...

Macros
#define	ECU_TIMER_OBJ_UNUSED    ((void *)0)
	Convenience define for ecu_timer_ctor(). Pass to this function if optional callback object is not needed.
#define	ECU_TICK_MAX    (UINT_MAX)
	Maximum value an ecu_tick_t type can hold.

Typedefs
typedef unsigned int	ecu_tick_t
	To remain portable, units of time are measured arbitrarily in ticks. It is the application's responsibility to convert this into concrete units of time. Typedeffed in case this type needs to change in the future. More...

Enumerations
enum	ecu_timer_type_e { ECU_TIMER_TYPE_ONE_SHOT, ECU_TIMER_TYPE_PERIODIC, ECU_TIMER_TYPES_COUNT }
	Type of ecu_timer used. More...

Functions
Timer Constructors
void	ecu_timer_ctor (struct ecu_timer *me, bool(*callback)(struct ecu_timer *me, void *obj), void *obj)
	Timer constructor. More...
Timer Member Functions
bool	ecu_timer_active (const struct ecu_timer *me)
	Returns true if the timer is currently running. False otherwise. More...
void	ecu_timer_disarm (struct ecu_timer *me)
	Stops the timer. Timer can be rearmed without reconstruction. This function can be used on a timer that is already disarmed. More...
ecu_tick_t	ecu_timer_period (const struct ecu_timer *me)
	Returns the timer's period that was set when it was started. More...
void	ecu_timer_set (struct ecu_timer *me, ecu_tick_t period, enum ecu_timer_type_e type)
	Stops the timer if it was running and reconfigures it with the newly supplied settings. Timer is not restarted. More...
enum ecu_timer_type_e	ecu_timer_type (const struct ecu_timer *me)
	Returns the timer's type that was specified when it was started. More...
Tlist Constructors
void	ecu_tlist_ctor (struct ecu_tlist *me)
	Timer list constructor. More...
Tlist Member Functions
void	ecu_tlist_service (struct ecu_tlist *me, ecu_tick_t elapsed)
	Services all software timers (ecu_timer) currently in the list. Servicing involves expiring appropriate timers, handling timer rearming, etc. This must be periodically called by the application at least once every ECU_TICK_MAX ticks. However the accuracy of the timers is proportional to how often this function is called. More...
void	ecu_tlist_timer_arm (struct ecu_tlist *me, struct ecu_timer *timer, ecu_tick_t period, enum ecu_timer_type_e type)
	Starts a timer with the specified settings. If the timer is already running it is restarted and reconfigured with the newly specified settings. More...
void	ecu_tlist_timer_rearm (struct ecu_tlist *me, struct ecu_timer *timer)
	Restarts the timer with its same settings. More...

Detailed Description

See timer.h section in Sphinx documentation.

Warning

Once started each timer is a shared resource belonging to both the ecu_tlist it was added to, and the application code that created the timer. It is the user's responsibility to ensure exclusive access.

Author

Ian Ress

Version

0.1

Date

2025-04-04

Copyright

Copyright (c) 2025

Typedef Documentation

ecu_tick_t

typedef unsigned int ecu_tick_t

To remain portable, units of time are measured arbitrarily in ticks. It is the application's responsibility to convert this into concrete units of time. Typedeffed in case this type needs to change in the future.

Warning

Must be unsigned.

Enumeration Type Documentation

ecu_timer_type_e

enum ecu_timer_type_e

Type of ecu_timer used.

Enumerator
ECU_TIMER_TYPE_ONE_SHOT	Once timer expires it is stopped.
ECU_TIMER_TYPE_PERIODIC	Once the timer expires it is automatically restarted.
ECU_TIMER_TYPES_COUNT	Total number of timer types.

Function Documentation

ecu_timer_active()

bool ecu_timer_active

(

const struct ecu_timer *

me

)

Returns true if the timer is currently running. False otherwise.

Precondition

me previously constructed via ecu_timer_ctor().

Parameters

me	Timer to check.

ecu_timer_ctor()

void ecu_timer_ctor	(	struct ecu_timer *	me,
		bool(*)(struct ecu_timer *me, void *obj)	callback,
		void *	obj
	)

Timer constructor.

Precondition

Memory already allocated for me.

Warning

me must not be an active timer within a list, otherwise behavior is undefined.

Parameters

me	Timer to construct.
callback	Mandatory callback that executes when timer expires. First parameter passed is this timer object. Callback should return true if successful or return false if it needs to be retried in the next call to ecu_tlist_service(). An example return false scenario could be a write to a queue failed due to it being full, so the write needs to be reattempted. Timer operations such as rearming and disarming can be done in this callback as well.
obj	Optional object to pass to callback. Pass ECU_TIMER_OBJ_UNUSED if unused.

ecu_timer_disarm()

void ecu_timer_disarm

(

struct ecu_timer *

me

)

Stops the timer. Timer can be rearmed without reconstruction. This function can be used on a timer that is already disarmed.

Precondition

me previously constructed via ecu_timer_ctor().

Parameters

me	Timer to stop.

ecu_timer_period()

ecu_tick_t ecu_timer_period

(

const struct ecu_timer *

me

)

Returns the timer's period that was set when it was started.

Precondition

me previously constructed via ecu_timer_ctor().

Parameters

me	Timer to check.

ecu_timer_set()

void ecu_timer_set	(	struct ecu_timer *	me,
		ecu_tick_t	period,
		enum ecu_timer_type_e	type
	)

Stops the timer if it was running and reconfigures it with the newly supplied settings. Timer is not restarted.

Precondition

me previously constructed via ecu_timer_ctor().

Warning

period is measured in hardware timer ticks, not time.

Parameters

me	Timer to set.
period	The timer's period, in ticks, to set. Timer expires after this number of ticks has elapsed. Must be between 1 and ECU_TICK_MAX.
type	The timer's type to set. I.e one-shot, periodic, etc.

ecu_timer_type()

enum ecu_timer_type_e ecu_timer_type

(

const struct ecu_timer *

me

)

Returns the timer's type that was specified when it was started.

Precondition

me previously constructed via ecu_timer_ctor().

Parameters

me	Timer to check.

ecu_tlist_ctor()

void ecu_tlist_ctor

(

struct ecu_tlist *

me

)

Timer list constructor.

Precondition

Memory already allocated for me.

Warning

me must not be an active list with timers added to it, otherwise behavior is undefined.

Parameters

me	Timer list to construct.

ecu_tlist_service()

void ecu_tlist_service	(	struct ecu_tlist *	me,
		ecu_tick_t	elapsed
	)

Services all software timers (ecu_timer) currently in the list. Servicing involves expiring appropriate timers, handling timer rearming, etc. This must be periodically called by the application at least once every ECU_TICK_MAX ticks. However the accuracy of the timers is proportional to how often this function is called.

Precondition

me previously constructed via ecu_tlist_ctor().

Parameters

me	List to service.
elapsed	Number of ticks that has elapsed since the last time this function was called. The list keeps track of time solely based off of this parameter.

ecu_tlist_timer_arm()

void ecu_tlist_timer_arm	(	struct ecu_tlist *	me,
		struct ecu_timer *	timer,
		ecu_tick_t	period,
		enum ecu_timer_type_e	type
	)

Starts a timer with the specified settings. If the timer is already running it is restarted and reconfigured with the newly specified settings.

Precondition

me previously constructed via ecu_tlist_ctor().

timer previously constructed via ecu_timer_ctor().

Parameters

me	List to add timer to.
timer	Timer to start. It will be serviced in calls to ecu_tlist_service()
period	The timer's period, in ticks, to set. Timer expires after this number of ticks has elapsed. Must be between 1 and ECU_TICK_MAX.
type	The timer's type to set. I.e one-shot, periodic, etc.

ecu_tlist_timer_rearm()

void ecu_tlist_timer_rearm	(	struct ecu_tlist *	me,
		struct ecu_timer *	timer
	)

Restarts the timer with its same settings.

Precondition

me previously constructed via ecu_tlist_ctor().

timer previously set via ecu_timer_set() or ecu_tlist_timer_arm().

Parameters

me	List to add timer to.
timer	Timer to restart. It will be serviced in calls to ecu_tlist_service()