version 2.8
GTIMER

Detailed Description

Module which provides software based timers for user-space applications.

The reason why uGFX has it's own timer abstraction is because virtual timers provided by ChibiOS/RT are interrupt context only. While great for what they are designed for, they make coding of the input drivers much more complex. For non-performance critical drivers like these input drivers, it would also hog an in-ordinate amount of critical (interrupt locked) system time. This contrary to the goals of a real-time operating system. So a user-land (thread based) timer mechanism is also required.

Precondition
GFX_USE_GTIMER must be set to TRUE in your gfxconf.h

Data Structures

struct  GTimer_t
 A GTimer structure. More...
 

Functions

void gtimerInit (GTimer *pt)
 Initialise a timer. More...
 
void gtimerDeinit (GTimer *pt)
 Deinitialise a timer. More...
 
void gtimerStart (GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, delaytime_t millisec)
 Set a timer going or alter its properties if it is already going. More...
 
void gtimerStop (GTimer *pt)
 Stop a timer (periodic or otherwise) More...
 
bool_t gtimerIsActive (GTimer *pt)
 Test if a timer is currently active. More...
 
void gtimerJab (GTimer *pt)
 Jab a timer causing the current period to immediate expire. More...
 
void gtimerJabI (GTimer *pt)
 Jab a timer causing the current period to immediate expire. More...
 

GTIMER Optional Sizing Parameters

#define GTIMER_THREAD_PRIORITY   HIGH_PRIORITY
 Defines the GTIMER thread priority. More...
 
#define GTIMER_THREAD_WORKAREA_SIZE   2048
 Defines the size of the timer threads work area (stack+structures). More...
 

Typedefs

typedef struct GTimer_t GTimer
 A GTimer structure. More...
 

Function Documentation

void gtimerDeinit ( GTimer pt)

Deinitialise a timer.

Parameters
[in]ptPointer to a GTimer structure
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 134 of file gtimer.c.

References gtimerStop().

void gtimerInit ( GTimer pt)

Initialise a timer.

Parameters
[in]ptPointer to a GTimer structure
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 129 of file gtimer.c.

Referenced by gwinGProgressbarCreate().

bool_t gtimerIsActive ( GTimer pt)

Test if a timer is currently active.

Parameters
[in]ptPointer to a GTimer structure
Returns
TRUE if active, FALSE otherwise
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 208 of file gtimer.c.

References FALSE, and TRUE.

Referenced by ginputGetToggle().

void gtimerJab ( GTimer pt)

Jab a timer causing the current period to immediate expire.

The callback function will be called as soon as possible.

Precondition
Use from a normal thread context.
Parameters
[in]ptPointer to a GTimer structure
Note
If the timer is not active this does nothing.
Repeated Jabs before the callback function actually happens are ignored.
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 212 of file gtimer.c.

References gfxMutexEnter(), gfxMutexExit(), and gfxSemSignal().

Referenced by ginputGetToggleStatus().

void gtimerJabI ( GTimer pt)

Jab a timer causing the current period to immediate expire.

The callback function will be called as soon as possible.

Precondition
Use from an interrupt routine context.
Parameters
[in]ptPointer to a GTimer structure
Note
If the timer is not active this does nothing.
Repeated Jabs before the callback function actually happens are ignored.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 223 of file gtimer.c.

References gfxSemSignalI().

Referenced by ginputGetToggleStatus().

void gtimerStart ( GTimer pt,
GTimerFunction  fn,
void *  param,
bool_t  periodic,
delaytime_t  millisec 
)

Set a timer going or alter its properties if it is already going.

Parameters
[in]ptPointer to a GTimer structure
[in]fnThe callback function
[in]paramThe parameter to pass to the callback function
[in]periodicIs the timer a periodic timer? FALSE is a once-only timer.
[in]millisecThe timer period. The following special values are allowed: TIME_IMMEDIATE causes the callback function to be called asap. A periodic timer with this value will fire once only. TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI)
Note
If the timer is already active its properties are updated with the new parameters. The current period will be immediately canceled (without the callback function being called) and the timer will be restart with the new timer properties.
The callback function should be careful not to over-run the thread stack. Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to change the default size.
The callback function should return as quickly as possible as all timer callbacks are performed by a single thread. If a callback function takes too long it could affect the timer response for other timers.
A timer callback function is not a replacement for a dedicated thread if the function wants to perform computationally expensive stuff.
As the callback function is called on GTIMER's thread, the function must make sure it uses appropriate synchronisation controls such as semaphores or mutexes around any data structures it shares with other threads such as the main application thread.
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 139 of file gtimer.c.

References gfxMillisecondsToTicks(), gfxMutexEnter(), gfxMutexExit(), gfxSemSignal(), gfxSystemTicks(), gfxThreadClose(), gfxThreadCreate(), GTIMER_THREAD_PRIORITY, and GTIMER_THREAD_WORKAREA_SIZE.

Referenced by ginputGetToggle(), and gwinProgressbarDecrement().

void gtimerStop ( GTimer pt)

Stop a timer (periodic or otherwise)

Parameters
[in]ptPointer to a GTimer structure
Note
If the timer is not active this does nothing.
Function Class:
Normal API, this function can be invoked by regular system threads.

Definition at line 190 of file gtimer.c.

References gfxMutexEnter(), and gfxMutexExit().

Referenced by gtimerDeinit(), and gwinProgressbarDecrement().

Macro Definition Documentation

#define GTIMER_THREAD_PRIORITY   HIGH_PRIORITY

Defines the GTIMER thread priority.

Defaults to HIGH_PRIORITY

Definition at line 34 of file gtimer_options.h.

Referenced by gtimerStart().

#define GTIMER_THREAD_WORKAREA_SIZE   2048

Defines the size of the timer threads work area (stack+structures).

Defaults to 2048 bytes

Definition at line 41 of file gtimer_options.h.

Referenced by gtimerStart().

Typedef Documentation

typedef struct GTimer_t GTimer

A GTimer structure.