sark_event.c File Reference

Event handling routines for SARK. More...

#include <sark.h>

Macros
#define	EFAIL(x)   (1 << (x))
	How to encode a failure code to go in an event (as events can have multiple failures).

Enumerations
enum	efail_code {   EFAIL_FIQ , EFAIL_IRQ , EFAIL_QUEUE , EFAIL_ALLOC ,   EFAIL_NEW }
	Event failure codes, for event_data_t::rc bitmap. More...

Functions
uint	event_user (uint arg1, uint arg2)
	Used to trigger a user event if one has been registered.
void	event_register_int (event_proc proc, event_type event_num, vic_slot slot)
	Register an event_proc to be called when a particular event occurs and associate that with an IRQ or FIQ interrupt.
void	event_register_queue (event_proc proc, event_type event_num, vic_slot slot, event_priority priority)
	Register an event_proc to be placed on an event queue when a particular event occurs and associate that with an IRQ interrupt.
void	event_enable (event_type event_num, uint enable)
	Enable or disable an event.
void	event_register_pause (event_proc proc, uint arg2)
	Register an event_proc to be called when event processing is paused.
void	event_wait (void)
	Wait for a signal from the monitor processor (i.e., host) before proceeding. Can be used to implement barrier waits.
void	event_run2 (uint restart)
	Execute a list of events (in the order in which they were added to the list). Events are returned to the free queue after execution.
uint	event_start (uint period, uint events, sync_bool wait)
	Start event processing.
void	event_pause (uint pause)
	Used to stop (pause) event processing or resume it again.
void	event_stop (uint rc)
	Used to stop event processing.
static void	enqueue_event (event_t *e, event_priority priority)
	Adds an event to a list of events which can (all) be executed at some later time. Later events are queued at the tail of the queue.
uint	event_queue (event_t *e, event_priority priority)
	Places an event on an event queue for execution at a later time.
uint	event_queue_proc (event_proc proc, uint arg1, uint arg2, event_priority priority)
	Creates a new event and places it on an event queue for execution at a later time.
void	event_free (event_t *e)
	Free a previously allocated event.
static event_t *	get_queue_contents (proc_queue_t *queue)
	Safely get the contents of a queue and reset that queue so it can receive more events.
void	event_run (uint restart)
	Run the event queue until it is empty.
static event_t *	take_one_event_from_queue (proc_queue_t *queue)
	Safely removes a single event from the head of the given queue.
event_t *	event_new (event_proc proc, uint arg1, uint arg2)
	Allocate a new event from the free queue and intialise "proc", "arg1" and "arg2" fields.
uint	event_alloc (uint events)
	Create additional free events by calling sark_alloc().
void	event_config (event_t *e, event_proc proc, uint arg1, uint arg2)
	Configure a (reusable) event that has already been allocated.

Variables
int_handler	fiq_events []
	FIQ interrupt handlers, indexed by event_type_e.
int_handler	irq_events []
	Standard interrupt handlers, indexed by event_type_e.
int_handler	queue_events []
	Event queuers, indexed by event_type_e.
int_handler	null_events []
	Null interrupt handlers, indexed by event_type_e.
static const uchar	vic_bit []
	Mapping from event_type_e to spinnaker_interrupt_numbers_e.
event_data_t	event
	SARK event variables.

Detailed Description

Event handling routines for SARK.

Copyright

© The University of Manchester - 2009-2013

Author

Steve Temple, APT Group, School of Computer Science

Macro Definition Documentation

EFAIL

#define EFAIL

(

x

)

(1 << (x))

How to encode a failure code to go in an event (as events can have multiple failures).

Parameters

[in]

x

The failure code, see efail_code

Returns

the encoded failure

Enumeration Type Documentation

efail_code

enum efail_code

Event failure codes, for event_data_t::rc bitmap.

Enumerator
EFAIL_FIQ	Failed to register as FIQ.
EFAIL_IRQ	Failed to register interrupt.
EFAIL_QUEUE	Event could not be enqueued.
EFAIL_ALLOC	Event queue could not be allocated.
EFAIL_NEW	Event queue was exhausted.

Function Documentation

event_user()

uint event_user	(	uint	arg1,
		uint	arg2
	)

Used to trigger a user event if one has been registered.

The two arguments will be provided to the event_proc() when it is called. Only one user event can be outstanding at any given time.

Parameters

arg1	first argument to event_proc
arg2	second argument to event_proc

Returns

zero if a user event is already pending, 1 otherwise

event_register_int()

void event_register_int	(	event_proc	proc,
		event_type	event,
		vic_slot	slot
	)

Register an event_proc to be called when a particular event occurs and associate that with an IRQ or FIQ interrupt.

A slot in the VIC to be used for the event must be provided. The pseudo-slot SLOT_FIQ is used to indicate that the FIQ interrupt should be used to ensure the fastest possible processing. Only one event can be associated with each slot and a runtime error will occur if a slot is used more than once.

Parameters

proc	the event_proc to call
event	the event to associate with the event_proc
slot	the VIC slot to use (or SLOT_FIQ for FIQs)

event_register_queue()

void event_register_queue	(	event_proc	proc,
		event_type	event,
		vic_slot	slot,
		event_priority	priority
	)

Register an event_proc to be placed on an event queue when a particular event occurs and associate that with an IRQ interrupt.

A slot in the VIC to be used for the event must be provided. Only one event can be associated with each slot and a runtime error will occur if a slot is used more than once or if an invalid queue priority is used.

Parameters

proc	the event_proc to call
event	the event to associate with the event_proc
slot	the VIC slot to use
priority	the priority of the event queue to use

event_enable()

void event_enable	(	event_type	event_num,
		uint	enable
	)

Enable or disable an event.

Enabling restores its interrupt handler to one which calls the handler which was originally registered with the event. Disabling changes its interrupt handler to one which receives and acknowledges the interrupt but which doesn't call the handler which was originally registered with the event. It is expected that disable will be called before enable in all cases

Parameters

event_num	the event to enable
enable	non-zero to enable, zero to disable

event_register_pause()

void event_register_pause	(	event_proc	proc,
		uint	arg2
	)

Register an event_proc to be called when event processing is paused.

The event_proc will receive the pause state (0 = resume, 1 = pause) as its first argument and the value of "arg2" as its second argument.

Parameters

proc	the event_proc to call
arg2	the second argument to be supplied to the event_proc

event_wait()

void event_wait

(

void

)

Wait for a signal from the monitor processor (i.e., host) before proceeding. Can be used to implement barrier waits.

There are two wait states which are used alternately. The first wait after event_start begins is for the signal WAIT0 and subsequent waits wait for signals WAIT1, WAIT0, WAIT1, etc.

event_run2()

void event_run2

(

uint

restart

)

Execute a list of events (in the order in which they were added to the list). Events are returned to the free queue after execution.

This differs from event_run() in that it only considers one event at a time, whereas event_run() processes one priority level of events in one go. This affects when incoming higher-priority events get run.

Parameters

[in]

restart

Whether to start back at priority zero after processing an event.

event_start()

uint event_start	(	uint	period,
		uint	events,
		sync_bool	wait
	)

Start event processing.

An event scheduler runs which takes events from event queues and executes them according to priority ordering. In addition, interrupts will be serviced and any events associated with them will also be executed. This routine will exit if the application calls event_stop or if a kill signal is received from the host.

Parameters

period	timer period in microseconds (timer disabled if zero)
events	number of new events to be created before processing begins
wait	if non-zero causes application to wait from signal from host before processing events.

Returns

return code from event_stop routine or 255 if killed

event_pause()

void event_pause

(

uint

pause

)

Used to stop (pause) event processing or resume it again.

If a pause handler has been registered then this will be called with "pause" as first argument and the second argument that was supplied at the time of registration. (Unlikely to be called from application code).

Parameters

pause

non-zero to pause, zero to resume

event_stop()

void event_stop

(

uint

rc

)

Used to stop event processing.

This will cause the routine event_start to terminate and the user's code after this will then execute. event_start will return the value provided in the "rc" parameter. This is an internal routine of the event processing system and unlikely to be called from an application.

Parameters

rc	return code to return from event_start

enqueue_event()

static void enqueue_event ( event_t *  e, event_priority  priority  )

static

Adds an event to a list of events which can (all) be executed at some later time. Later events are queued at the tail of the queue.

This is the core of the implementation of event_queue() and event_queue_proc()

Parameters

e	The event to enqueue
priority	The priority of the event

event_queue()

uint event_queue	(	event_t *	e,
		event_priority	priority
	)

Places an event on an event queue for execution at a later time.

There are (currently) 4 event queues numbered PRIO_0 (highest priority) to PRIO_3 (lowest). Events are taken from queue 0 until it is empty, then they are taken from queue 1 until it is empty, etc, etc.

Parameters

e	pointer to the event to add
priority	priority of queue to add to

Returns

zero on failure (invalid priority), 1 otherwise

event_queue_proc()

uint event_queue_proc	(	event_proc	proc,
		uint	arg1,
		uint	arg2,
		event_priority	priority
	)

Creates a new event and places it on an event queue for execution at a later time.

Calls event_new() to create and initialise a new event and then, if that is successful, calls event_queue() to place it on an event queue.

Parameters

proc	pointer to an event_proc
arg1	argument 1 to the event_proc
arg2	argument 2 to the event_proc
priority	priority of queue to add to

Returns

zero on failure (invalid priority or failed to allocate a new event), 1 otherwise

event_free()

void event_free

(

event_t *

e

)

Free a previously allocated event.

The event must not have been scheduled.

Parameters

[in]

e

the event to free

get_queue_contents()

static event_t * get_queue_contents ( proc_queue_t *  queue )

inlinestatic

Safely get the contents of a queue and reset that queue so it can receive more events.

Parameters

[in]

queue

The queue to have its contents removed.

Returns

the list of events that were in the queue; NULL if there are no events.

event_run()

void event_run

(

uint

restart

)

Run the event queue until it is empty.

Events are taken from the event queues in priority order and executed. The "restart" parameter controls whether all queues are rescanned for events when processing of a queue at a particular priority is complete. In general, this will be necessary if executing an event can cause new events to be queued.

Parameters

restart

non-zero to cause queues to be rescanned

take_one_event_from_queue()

static event_t * take_one_event_from_queue ( proc_queue_t *  queue )

inlinestatic

Safely removes a single event from the head of the given queue.

Parameters

[in]

queue

the queue to take an event from.

Returns

The event that was at the queue head, or NULL if the queue was empty.

event_new()

event_t * event_new	(	event_proc	proc,
		uint	arg1,
		uint	arg2
	)

Allocate a new event from the free queue and intialise "proc", "arg1" and "arg2" fields.

The "ID", "next" and "time" fields are also set.

Parameters

[in]	proc	pointer to an event_proc
[in]	arg1	argument 1 to the event_proc
[in]	arg2	argument 2 to the event_proc

Returns

pointer to event if successful, NULL otherwise

event_alloc()

uint event_alloc

(

uint

events

)

Create additional free events by calling sark_alloc().

Caller specifies number of events to allocate and they will be added to the existing free queue. Returns 1 on success, 0 on failure.

Parameters

[in]

events

number of new events to allocate

Returns

0 on failure, 1 otherwise

event_config()

void event_config	(	event_t *	event,
		event_proc	proc,
		uint	arg1,
		uint	arg2
	)

Configure a (reusable) event that has already been allocated.

Configure fields "proc", "arg1" and "arg2" from the parameters. Fields "next" and "time" are set to default values.

Parameters

[in]	event	pointer to an event (to be configured)
[in]	proc	pointer to an event_proc
[in]	arg1	argument 1 to the event_proc
[in]	arg2	argument 2 to the event_proc

Variable Documentation

vic_bit

const uchar vic_bit[]

static

Initial value:

= {
    TIMER1_INT,         
    CC_MC_INT,          
    SARK_MSG_INT,       
    SOFTWARE_INT,       
    SARK_SIG_INT,       
    DMA_DONE_INT        
}

Mapping from event_type_e to spinnaker_interrupt_numbers_e.