Application-provided routines

execAppCurrentTick()

Function prototype:

word execAppCurrentTick(void);

Parameters: None

Returns: the current value of the main timer (the current timer tick).

This function is not part of the executive but is user-supplied and called by the executive when a timer is being activated.

This function should query the hardware or other timer/counting mechanism used to implement the timer system.

execAppFinish()

Function prototype:

void execAppFinish(void);

Parameters: None

Returns: Nothing

This function is not part of the executive but is user-supplied and called only when running under Windows when the executive shuts down.

It is not necessary to provide this function when running only in an embedded environment.

Use this function to de-initialise and release any resources allocated in execAppInit().

execAppIdle()

Function prototype:

void execAppIdle(void);

This function is not part of the executive but is user-supplied and called by the executive repeatedly while there are no events to process.

This function can be used to set the processor into the idle state, or to toggle an output pin or do other calculations to measure how much spare processing bandwidth is available under different operating conditions.

execAppInit()

Function prototype:

void execAppInit(void);

This function is not part of the executive but is user-supplied and called by the executive before any other processing is performed.

In this function, initialise hardware, state machines and perform all other initialisation, and enable the interrupt system.

The executive includes a main() function, so do not create one in the application program.

execAppPostExternalEvent()

Function prototype:

boolean execAppPostExternalEvent(word Event, byte Channel);

Parameters: Event the event number to post
Channel the channel to post the event to

Returns: true if the event was successfully posted.

This function is not part of the executive but is user-supplied and called when an event is posted by the application with a priority outside the range of the event queues.

The channel number is zero-based and is the ‘priority’ of the posted event minus the number of event queues in the system.

This function should pass on or use the event if it can, returning true, or returning false if any of the parameters are out of range or if the action cannot be performed for any reason.

execAppResyncTimer()

Function prototype:

void execAppResyncTimer(word TickCount, boolean Enable);

Parameters: TickCount the time at which the next timeout will occur
Enable true if there are timeouts pending

Returns: nothing.

This function is not part of the executive, but is user supplied.

It is called when a timer is being set up or disabled, and is only called if the time at which the next (pending) timeout was due to occur, has changed.

If Enable is false, then there are no more pending timeouts, and hardware timers may be shut down. No further timer interrupts are required (until this function is called again with Enable true). Additionally, in this case, the value of TickCount is arbitrary, and should not be used.

If Enable is true, the hardware timer system should be reset or modified so that the next timeout (timer interrupt) occurs at the new TickCount value, rather than the one that was currently due.

In this way, this routine should co-operate with a user-supplied timer interrupt routine which should determine when the selected timer has reached its timeout value. At the point it determines this, it should call execProcessTimeouts() and set up the next time to time out or disable itself (depending on the return value from this function – see section 2.1.3.2).

execAppTrace()

Function prototype:

void execAppTrace(byte BeforeState, byte AfterState, word or byte Event);

Parameters: BeforeState state before the state transition AfterState state after the state transition
Event event number causing the transition

Returns: nothing.

This function is not part of the executive, but is user supplied.

It is called when event tracing is enabled (globally) and that particular event is enabled for tracing. It is called after the state transition function just before the current state is set to the next state.

Typically, this function will store the information passed in a circular buffer and/or send it down a communications link.

Care should be taken when tracing frequent events so as to avoid overloading the system and affecting performance.

Timer Interrupt Routine

See the description for execAppResyncTimer in section 2.2.1.6.