spin1_api.c File Reference

The SpiNNaker API runtime environment. More...

#include <sark.h>
#include <spin1_api.h>
#include <spin1_api_params.h>
#include <scamp_spin1_sync.h>

Macros
#define	IO_API   IO_BUF
	API information will be reported via IO_BUF.
#define	io_delay(us)
	Delay between API I/O messages.
#define	VIC_ENABLE_VECTOR   (0x20)
	Enable flag for VIC vector control (see VIC_CNTL)

Functions
void	cc_rx_error_isr (void)
	Clears errors from the communications controller.
void	cc_rx_ready_isr (void)
	Handles an incoming multicast packet.
void	cc_fr_ready_isr (void)
	Handles an incoming fixed-route packet.
void	cc_tx_empty_isr (void)
	Comms controller ready to send interrupt handler.
void	dma_done_isr (void)
	DMA complete interrupt handler.
void	dma_error_isr (void)
	DMA error interrupt handler.
void	timer1_isr (void)
	Timer 1 interrupt handler.
void	soft_int_isr (void)
	Software-initiated interrupt handler.
void	cc_rx_ready_fiqsr (void)
	Handles an incoming multicast packet. (FIQ)
void	cc_fr_ready_fiqsr (void)
	Handles an incoming fixed-route packet. (FIQ)
void	dma_done_fiqsr (void)
	DMA complete interrupt handler. (FIQ)
void	timer1_fiqsr (void)
	Timer 1 interrupt handler. (FIQ)
void	soft_int_fiqsr (void)
	Software-initiated interrupt handler. (FIQ)
void	sark_int_han (void)
	Interrupt handler for messages from SCAMP.
void	sark_fiqsr (void)
void	spin1_wfi (void)
	Wait for interrupt.
uint	spin1_int_enable (void)
	Enable interrupts. Alias for cpu_int_enable()
static void	configure_communications_controller (void)
	Configures the communications controller.
static void	configure_dma_controller (void)
	Configures the DMA controller.
static void	configure_timer1 (uint time, uint phase)
	Configures Timer 1.
static void	configure_vic (uint enable_timer)
	Configures the VIC.
void	spin1_pause (void)
	Pause the simulation on this core. Waits for spin1_resume().
static void	resume (void)
	Resumes simulating by enabling the main timer.
void	spin1_resume (sync_bool sync)
	Resume the simulation on this core that was paused with spin1_pause().
uint	resume_wait (void)
	Determines if we are waiting for SYNC flip.
static void	dispatch (void)
	Main simulation event dispatch loop.
void	spin1_callback_on (uint event_id, callback_t cback, int priority)
	Enables a callback for a class of event.
void	spin1_callback_off (uint event_id)
	Disables a callback for a class of event.
static void	deschedule (uint event_id)
	Deschedules all callbacks for an event.
uint	spin1_get_simulation_time (void)
	Returns the number of timer periods which have elapsed since the beginning of the simulation.
void	spin1_exit (uint error)
	Terminates a simulation passing a return code.
void	spin1_set_timer_tick_and_phase (uint time, uint phase)
	Set the timer tick rate and phase offset.
static void	clean_up (void)
	Post-exit cleanup.
static void	report_debug (void)
	Report debugging diagnostic information.
static void	report_warns (void)
	Report debugging warnings.
register uint _lr	asm ("lr")
void	spin1_rte (rte_code code)
	Soft-RTEs the core.
static uint	start (sync_bool sync, uint start_paused)
	Begins a simulation by enabling the timer (if called for) and beginning the dispatcher loop. Only returns once told to exit (with spin1_exit()).
uint	spin1_start (sync_bool sync)
	Begins a simulation by enabling the timer (if called for) and beginning the dispatcher loop. Only returns once told to exit (with spin1_exit()).
uint	spin1_start_paused (void)
	Begins a simulation by enabling the timer (if called for) and beginning the dispatcher loop once the system is told (via spin1_resume()) to resume. Only returns once told to exit (with spin1_exit()).
uint	spin1_dma_transfer (uint tag, void *system_address, void *tcm_address, uint direction, uint length)
	Initiates a DMA transfer.
void	spin1_dma_flush (void)
	Flushes any current transfers in the DMA controller.
void	spin1_memcpy (void *dst, void const *src, uint len)
	Directly copies data from src to dst.
void	spin1_flush_rx_packet_queue (void)
	Discards all received packets which are yet to be processed.
void	spin1_flush_tx_packet_queue (void)
	Flushes the outbound packet queue.
uint	spin1_send_packet (uint key, uint data, uint TCR)
	Send a packet. Do not normally call directly; use spin1_send_mc_packet() and spin1_send_fr_packet() instead.
uint	spin1_get_id (void)
	Returns a global (machine-wide) ID for the processor.
uint	spin1_get_core_id (void)
	Returns the core ID.
uint	spin1_get_chip_id (void)
	Returns the (machine-wide) chip ID.
void	schedule_sysmode (uchar event_id, uint arg0, uint arg1)
	Schedule a callback (called with interrupts disabled)
uint	spin1_schedule_callback (callback_t cback, uint arg0, uint arg1, uint priority)
	This function places a cback into the scheduling queue corresponding to its priority.
void	spin1_enable_timer_schedule_proc (void)
	This function enables the use of timer_schedule_proc.
uint	spin1_trigger_user_event (uint arg0, uint arg1)
	This function triggers a USER EVENT, i.e., a software interrupt.
void	sark_pre_main (void)
	Runtime initialisation; called before the application program starts!
void	sark_post_main (void)
	Runtime cleanup, called after the application program finishes!

Variables
uchar	leadAp
	lead appl. core has special functions
static volatile uint	run
	controls simulation start/exit
static volatile uint	paused
	indicates when paused
static volatile uint	resume_sync
	controls re-synchronisation
uint	ticks
	number of elapsed timer periods
uint	timer_tick
	timer tick period
uint	timer_tick_clocks
	timer tick period in clock cycles
int	drift
	drift in clock cycles per timer tick
int	drift_sign
	sign of the drift
int	drift_accum
	accumulation of drifts
int	time_to_next_drift_update
	timer ticks until drift needs to be updated
static uint	timer_phase
	additional phase on starting the timer
static isr_t	old_vector
	Default FIQ handler. Restored after simulation.
static uint	old_select
	Default FIQ select. Restored after simulation.
static uint	old_enable
	Default interrupt enable. Restored after simulation.
static uint	user_int_select = 0
	Interrupt select to be used based on user selections.
static const uint	ALL_HANDLED_INTERRUPTS
	All VIC interrupts that are handled by the API.
static uint	highest_priority = 0
	The highest priority selected.
static int	fiq_event = -1
	Which event is to be handled by the FIQ.
static int	mc_pkt_prio = -2
	Sanity check state for multicast packet handlers.
static int	fr_pkt_prio = -2
	Sanity check state for fixed-route packet handlers.
dma_queue_t	dma_queue
	The pending DMA transfers.
tx_packet_queue_t	tx_packet_queue
	The pending SpiNNaker packets to transmit.
user_event_queue_t	user_event_queue
	The pending user event callbacks to call.
static task_queue_t	task_queue [N_TASK_QUEUES]
	The queue of scheduled tasks.
cback_t	callback [NUM_EVENTS]
	The registered callbacks for each event type.
diagnostics_t	diagnostics
	Miscellaneous diagnostic information, available to the application.

Detailed Description

The SpiNNaker API runtime environment.

Macro Definition Documentation

io_delay

#define io_delay

(

us

)

Delay between API I/O messages.

Parameters

us	Time (in μs) to delay

Does nothing

Function Documentation

cc_rx_error_isr()

void cc_rx_error_isr ( void  )

extern

Clears errors from the communications controller.

This interrupt service routine is called in response to receipt of a packet from the router with either parity or framing errors. The routine simply clears the error and disposes of the packet. The monitor processor may observe packet errors by reading from the router diagnostic registers.

cc_rx_ready_isr()

void cc_rx_ready_isr ( void  )

extern

Handles an incoming multicast packet.

This interrupt service routine is called in response to receipt of a packet from the router. Chips are configured such that fascicle processors receive only multicast neural event packets. In response to receipt of a MC packet a callback is scheduled to process the corresponding routing key and data.

Checking for parity and framing errors is not performed. The VIC is configured so that the interrupts raised by erroneous packets prompt execution of cc_rx_error_isr() which clears them.

cc_fr_ready_isr()

void cc_fr_ready_isr ( void  )

extern

Handles an incoming fixed-route packet.

This interrupt service routine is called in response to receipt of a packet from the router. Chips are configured such that fascicle processors receive only multicast neural event packets. In response to receipt of a MC packet a callback is scheduled to process the corresponding routing key and data.

Checking for parity and framing errors is not performed. The VIC is configured so that the interrupts raised by erroneous packets prompt execution of cc_rx_error_isr() which clears them.

cc_tx_empty_isr()

void cc_tx_empty_isr ( void  )

extern

Comms controller ready to send interrupt handler.

This interrupt service function is called when the comms controller transmit buffer is empty. The function dequeues packets queued for transmission by spin1_send_mc_packet() function and writes them to the comms controller hardware, until either the packet queue is empty or the comms controller is full.

This interrupt is only enabled when there is at least one message to send in the transmit queue.

dma_done_isr()

void dma_done_isr ( void  )

extern

DMA complete interrupt handler.

This interrupt service routine is called upon completion of a DMA transfer. A user callback is scheduled (with two parameters, the ID of the completed transfer and the user-provided transfer tag) and the next DMA transfer request is dequeued and fulfilled. The completion and subsequent scheduling of transfers must be atomic (as they are in this uninterruptable ISR) otherwise transfer requests may not be completed in the order they were made.

dma_error_isr()

void dma_error_isr ( void  )

extern

DMA error interrupt handler.

This interrupt service function is called when a DMA transfer error arises. Currently, such an event causes termination of the simulation.

timer1_isr()

void timer1_isr ( void  )

extern

Timer 1 interrupt handler.

This interrupt service routine is called upon countdown of the processor's primary timer to zero. In response, a callback is scheduled.

soft_int_isr()

void soft_int_isr ( void  )

extern

Software-initiated interrupt handler.

This interrupt service routine is called upon receipt of software controller interrupt, triggered by a "USER EVENT".

cc_rx_ready_fiqsr()

void cc_rx_ready_fiqsr ( void  )

extern

Handles an incoming multicast packet. (FIQ)

This interrupt service routine is called in response to receipt of a packet from the router. Chips are configured such that fascicle processors receive only multicast neural event packets. In response to receipt of a MC packet a callback is scheduled to process the corresponding routing key and data.

Checking for parity and framing errors is not performed. The VIC is configured so that the interrupts raised by erroneous packets prompt execution of cc_rx_error_isr() which clears them.

cc_fr_ready_fiqsr()

void cc_fr_ready_fiqsr ( void  )

extern

Handles an incoming fixed-route packet. (FIQ)

This interrupt service routine is called in response to receipt of a packet from the router. Chips are configured such that fascicle processors receive only multicast neural event packets. In response to receipt of a MC packet a callback is scheduled to process the corresponding routing key and data.

Checking for parity and framing errors is not performed. The VIC is configured so that the interrupts raised by erroneous packets prompt execution of cc_rx_error_isr() which clears them.

dma_done_fiqsr()

void dma_done_fiqsr ( void  )

extern

DMA complete interrupt handler. (FIQ)

This interrupt service routine is called upon completion of a DMA transfer. A user callback is scheduled (with two parameters, the ID of the completed transfer and ‘1’ indicating transfer success) and the next DMA transfer request is dequeued and fulfilled. The completion and subsequent scheduling of transfers must be atomic (as they are in this uninterruptable ISR) otherwise transfer requests may not be completed in the order they were made.

timer1_fiqsr()

void timer1_fiqsr ( void  )

extern

Timer 1 interrupt handler. (FIQ)

This interrupt service routine is called upon countdown of the processor's primary timer to zero. In response, a callback is scheduled.

soft_int_fiqsr()

void soft_int_fiqsr ( void  )

extern

Software-initiated interrupt handler. (FIQ)

This interrupt service routine is called upon receipt of software controller interrupt, triggered by a "USER EVENT".

spin1_wfi()

void spin1_wfi ( void  )

extern

Wait for interrupt.

Puts the CPU to sleep until an interrupt occurs.

spin1_int_enable()

uint spin1_int_enable

(

void

)

Enable interrupts. Alias for cpu_int_enable()

Returns

the old value of the CPSR

configure_communications_controller()

static void configure_communications_controller ( void  )

static

Configures the communications controller.

This function configures the communications controller by clearing out any pending packets from the RX buffer and clearing sticky error bits.

configure_dma_controller()

static void configure_dma_controller ( void  )

static

Configures the DMA controller.

This function configures the DMA controller by aborting any previously- queued or currently-executing transfers and clearing any corresponding interrupts then enabling all interrupts sources.

configure_timer1()

static void configure_timer1 ( uint  time, uint  phase  )

static

Configures Timer 1.

This function configures timer 1 to raise an interrupt with a period specified by ‘time’. Firstly, timer 1 is disabled and any pending interrupts are cleared. Then timer 1 load and background load registers are loaded with the core clock frequency (set by the monitor and recorded in system RAM MHz) multiplied by ‘time’ and finally timer 1 is loaded with the configuration below.

[0]   One-shot/wrapping     Wrapping
[1]   Timer size            32 bit
[3:2] Input clock divide    1
[5]   IRQ enable            Enabled
[6]   Mode                  Periodic
[7]   Timer enable          Disabled

Parameters

[in]	time	timer period in microseconds, 0 = timer disabled
[in]	phase	timer offset in microseconds

configure_vic()

static void configure_vic ( uint  enable_timer )

static

Configures the VIC.

This function configures the Vectored Interrupt Controller. Firstly, all interrupts are disabled and then the addresses of the interrupt service routines are placed in the VIC vector address registers and the corresponding control registers are configured. Priority is set in such a manner that the first interrupt source configured by the function is the first priority, the second interrupt configured is the second priority and so on. This mechanism allows future programmers to reorder the IRQ priorities by simply switching around the order in which they are set (a simple copy+paste operation). Finally, the interrupt sources are enabled.

Parameters

[in]

enable_timer

True if the timer interrupt should be enabled.

spin1_resume()

void spin1_resume

(

sync_bool

sync

)

Resume the simulation on this core that was paused with spin1_pause().

Parameters

[in]

sync

Whether to synchronise the resume with other cores

resume_wait()

uint resume_wait

(

void

)

Determines if we are waiting for SYNC flip.

Returns

true if we are waiting, false if not

dispatch()

static void dispatch ( void  )

static

Main simulation event dispatch loop.

This function executes callbacks which are scheduled in response to events. Callbacks are completed firstly in order of priority and secondly in the order in which they were enqueued.

The dispatcher is the sole consumer of the scheduler queues and so can safely run with interrupts enabled. Note that deschedule() modifies the scheduler queues which naturally influences the callbacks that are dispatched by this function but not in such a way as to allow the dispatcher to move the processor into an invalid state such as calling a NULL function.

Upon emptying the scheduling queues the dispatcher goes into wait for interrupt mode.

Potential hazard: It is possible that an event will occur and result in a callback being scheduled AFTER the last check on the scheduler queues and BEFORE the wait for interrupt call. In this case, the scheduled callback would not be handled until the next event occurs and causes the wait for interrupt call to return.

This hazard is avoided by calling wait for interrupt with interrupts disabled! Any interrupt will still wake up the core and then interrupts are enabled, allowing the core to respond to it.

spin1_callback_on()

void spin1_callback_on	(	uint	event_id,
		callback_t	cback,
		int	priority
	)

Enables a callback for a class of event.

This function sets the given callback to be scheduled on occurrence of the specified event. The priority argument dictates the order in which callbacks are executed by the scheduler.

Parameters

[in]	event_id	Which event to enable
[in]	cback	The callback handler
[in]	priority	The priority of interrupt handling. 0 = non-queueable callback (associated to irq) ‍0 = queueable callback < 0 = preeminent callback (associated to fiq)

spin1_callback_off()

void spin1_callback_off

(

uint

event_id

)

Disables a callback for a class of event.

This function disables the callback for the specified event.

Parameters

[in]

event_id

Which event to disable

deschedule()

static void deschedule ( uint  event_id )

static

Deschedules all callbacks for an event.

This function deschedules all callbacks corresponding to the given event ID. One use for this function is to effectively discard all received packets which are yet to be processed by calling deschedule(MC_PACKET_RECEIVED).

Note

this function cannot guarantee that all callbacks pertaining to the given event ID will be descheduled: once a callback has been prepared for execution by the dispatcher it is immune to descheduling and will be executed upon return to the dispatcher.

Parameters

[in]

event_id

event ID of the callbacks to be descheduled

spin1_get_simulation_time()

uint spin1_get_simulation_time

(

void

)

Returns the number of timer periods which have elapsed since the beginning of the simulation.

Returns

Timer ticks since beginning of simulation.

spin1_exit()

void spin1_exit

(

uint

error

)

Terminates a simulation passing a return code.

Note

This function returns! This technically terminates the simulation loop, not the application.

Parameters

[in]

error

error exit code

spin1_set_timer_tick_and_phase()

void spin1_set_timer_tick_and_phase	(	uint	time,
		uint	phase
	)

Set the timer tick rate and phase offset.

Parameters

[in]	time	The timer tick rate
[in]	phase	The phase offset

clean_up()

static void clean_up ( void  )

static

Post-exit cleanup.

This function is called after simulation exits to configure hardware for idle operation. It cleans up interrupt lines.

report_debug()

static void report_debug ( void  )

static

Report debugging diagnostic information.

This function reports provenance if requested at compile time.

report_warns()

static void report_warns ( void  )

static

Report debugging warnings.

This function reports warnings if requested at compile time

spin1_rte()

void spin1_rte

(

rte_code

code

)

Soft-RTEs the core.

Sets the CPU into an RTE code and stops the timer.

Note

This may return!

Parameters

[in]

code

the error code

start()

static uint start ( sync_bool  sync, uint  start_paused  )

static

Begins a simulation by enabling the timer (if called for) and beginning the dispatcher loop. Only returns once told to exit (with spin1_exit()).

Parameters

[in]	sync	Whether to synchronise with other cores
[in]	start_paused	Whether to start in a paused state

Returns

the exit code

spin1_start()

uint spin1_start

(

sync_bool

sync

)

Begins a simulation by enabling the timer (if called for) and beginning the dispatcher loop. Only returns once told to exit (with spin1_exit()).

Parameters

[in]

sync

Whether to synchronise with other cores

Returns

the exit code

spin1_start_paused()

uint spin1_start_paused

(

void

)

Begins a simulation by enabling the timer (if called for) and beginning the dispatcher loop once the system is told (via spin1_resume()) to resume. Only returns once told to exit (with spin1_exit()).

Returns

the exit code

spin1_dma_transfer()

uint spin1_dma_transfer	(	uint	tag,
		void *	system_address,
		void *	tcm_address,
		uint	direction,
		uint	length
	)

Initiates a DMA transfer.

Parameters

[in]	tag	A label for the transfer. Can be used by DMA complete callback to work out what to do.
	system_address	Address in SDRAM. May be source or destination. Must be word-aligned.
	tcm_address	Address in TCM. May be source or destination. Must be word-aligned.
[in]	direction	Which direction is data being moved in.
[in]	length	How much data is being moved. Must be a whole number of words.

Returns

a locally-unique DMA transfer ID. Can be used by DMA complete callback to identify what finished.

spin1_dma_flush()

void spin1_dma_flush

(

void

)

Flushes any current transfers in the DMA controller.

flushes the hardware queue in the DMA controller, aborts any ongoing transfer in the DMA controller, clears any pending DMA_COMPLETE interrupts in the DMA controller and purges any queued DMA_COMPLETE callbacks in the callback queues. flushes the software DMA queue,

spin1_memcpy()

void spin1_memcpy	(	void *	dst,
		void const *	src,
		uint	len
	)

Directly copies data from src to dst.

Does not require alignment.

Parameters

[out]	dst	Where to copy to
[in]	src	Where to copy from
[in]	len	Number of bytes to copy

spin1_flush_rx_packet_queue()

void spin1_flush_rx_packet_queue

(

void

)

Discards all received packets which are yet to be processed.

Works by calling deschedule() for each queue.

spin1_flush_tx_packet_queue()

void spin1_flush_tx_packet_queue

(

void

)

Flushes the outbound packet queue.

Works by adjusting the queue pointers to make it appear empty to the consumer

spin1_send_packet()

uint spin1_send_packet	(	uint	key,
		uint	data,
		uint	TCR
	)

Send a packet. Do not normally call directly; use spin1_send_mc_packet() and spin1_send_fr_packet() instead.

Parameters

[in]	key	The key of the packet. Determines destinations.
[in]	data	The payload (if any).
[in]	TCR	Transmission control. Especially includes the payload-present bit and the packet type.

Returns

SUCCESS or FAILURE

spin1_get_id()

uint spin1_get_id

(

void

)

Returns a global (machine-wide) ID for the processor.

Returns

Chip ID in bits [20:5], core ID in bits [4:0].

spin1_get_core_id()

uint spin1_get_core_id

(

void

)

Returns the core ID.

Returns

Core ID in the bottom 5 bits.

spin1_get_chip_id()

uint spin1_get_chip_id

(

void

)

Returns the (machine-wide) chip ID.

Returns

Chip ID in the bottom 16 bits.

schedule_sysmode()

void schedule_sysmode	(	uchar	event_id,
		uint	arg0,
		uint	arg1
	)

Schedule a callback (called with interrupts disabled)

This function places a callback into the scheduling queue corresponding to its priority, which is set at configuration time by on_callback(...).

Non-queueable callbacks (those of priority 0) are executed immediately and atomically.

Interrupts are not explicitly disabled during this routine: it is assumed that the function is only called by interrupt service routines responding to events, and these ISRs execute with interrupts disabled.

Note

Also called from sark_base.c and sark_alib.s via weak linking.

Parameters

[in]	event_id	ID of the event triggering a callback
[in]	arg0	argument to be passed to the callback
[in]	arg1	argument to be passed to the callback

spin1_schedule_callback()

uint spin1_schedule_callback	(	callback_t	cback,
		uint	arg0,
		uint	arg1,
		uint	priority
	)

This function places a cback into the scheduling queue corresponding to its priority.

Parameters

[in]	cback	callback to be scheduled
[in]	arg0	argument to be passed to the callback
[in]	arg1	argument to be passed to the callback
[in]	priority	cback priority

Returns

SUCCESS or FAILURE

spin1_trigger_user_event()

uint spin1_trigger_user_event	(	uint	arg0,
		uint	arg1
	)

This function triggers a USER EVENT, i.e., a software interrupt.

Parameters

[in]	arg0	argument to be passed to the callback
[in]	arg1	argument to be passed to the callback

Returns

SUCCESS or FAILURE

sark_pre_main()

void sark_pre_main

(

void

)

Runtime initialisation; called before the application program starts!

This function is a stub for the run-time system. It initialises peripherals in the way the RTS is expected to do

sark_post_main()

void sark_post_main

(

void

)

Runtime cleanup, called after the application program finishes!

This function is a stub for the run-time system. It makes sure that application returns cleanly to the RTS.

Variable Documentation

ALL_HANDLED_INTERRUPTS

const uint ALL_HANDLED_INTERRUPTS

static

Initial value:

=
        ((1 << TIMER1_INT) | (1 << SOFTWARE_INT) | (1 << CC_MC_INT) |
         (1 << CC_FR_INT) | (1 << DMA_ERR_INT)  | (1 << DMA_DONE_INT))

All VIC interrupts that are handled by the API.

fiq_event

int fiq_event = -1

static

Which event is to be handled by the FIQ.

Used to enforce that only one type of basic interrupt handler can use the FIQ. Special cased for packet received handlers, where the with- and without-payload variants are actually using the same interrupt handler.

We usually expect the FIQ to be used for multicast packets, as they have the most stringent reception performance requirements in practice.

mc_pkt_prio

int mc_pkt_prio = -2

static

Sanity check state for multicast packet handlers.

Used to enforce that both the without- and with-payload versions of the handlers use the same basic interrupt handler. The -2 means "not yet assigned".

fr_pkt_prio

int fr_pkt_prio = -2

static

Sanity check state for fixed-route packet handlers.

Used to enforce that both the without- and with-payload versions of the handlers use the same basic interrupt handler. The -2 means "not yet assigned".

user_event_queue

user_event_queue_t user_event_queue

The pending user event callbacks to call.

Registered by spin1_trigger_user_event()

callback

cback_t callback[NUM_EVENTS]

The registered callbacks for each event type.

The external interrupt handlers.

Warning

SARK knows about this variable!