spin1_api.h File Reference

Header file describing the SpiNNaker API runtime environment. More...

#include "sark.h"

Go to the source code of this file.

Data Structures
struct	diagnostics_t
	diagnostic data available to the application More...

Macros
#define	SPINN_SYSRAM_BASE   SYSRAM_BASE
	System RAM base address.
#define	SPINN_SYSRAM_SIZE   SYSRAM_SIZE
	System RAM size.
#define	SPINN_SDRAM_BASE   SDRAM_BASE
	SDRAM base address.
#define	SPINN_SDRAM_SIZE   SDRAM_SIZE
	SDRAM size.
#define	TRUE   (0 == 0)
	Boolean true.
#define	FALSE   (0 != 0)
	Boolean false.
#define	SUCCESS   (uint) 1
	Function result: Success.
#define	FAILURE   (uint) 0
	Function result: Failure.
#define	NULL   0
#define	SPIN1_INLINE   static __inline __attribute__((always_inline))

Typedefs
typedef void(*	callback_t) (uint, uint)
	User callback for event handling.

Enumerations
enum	{   NUM_EVENTS = 8 , MC_PACKET_RECEIVED = 0 , DMA_TRANSFER_DONE = 1 , TIMER_TICK = 2 ,   SDP_PACKET_RX = 3 , USER_EVENT = 4 , MCPL_PACKET_RECEIVED = 5 , FR_PACKET_RECEIVED = 6 ,   FRPL_PACKET_RECEIVED = 7 }
	event-related parameters More...
enum	{ DMA_READ = 0 , DMA_WRITE = 1 }
	DMA transfer direction (from core point of view) More...
enum	{ NO_PAYLOAD = 0 , WITH_PAYLOAD = 1 }
	Spinnaker packet payload presence flag. More...

Functions
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()).
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	spin1_set_timer_tick (uint time)
	Set the timer tick rate. No phase offset.
uint	spin1_get_simulation_time (void)
	Returns the number of timer periods which have elapsed since the beginning of the simulation.
void	spin1_pause (void)
	Pause the simulation on this core. Waits for spin1_resume().
void	spin1_resume (sync_bool sync)
	Resume the simulation on this core that was paused with spin1_pause().
void	spin1_rte (rte_code code)
	Soft-RTEs the core.
static void	spin1_delay_us (uint n)
	This function implements a delay measured in microseconds.
void	spin1_enable_timer_schedule_proc (void)
	This function enables the use of timer_schedule_proc.
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.
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.
uint	spin1_trigger_user_event (uint arg0, uint arg1)
	This function triggers a USER EVENT, i.e., a software interrupt.
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.
static uint	spin1_send_mc_packet (uint key, uint data, uint load)
	This function enqueues a request to send a multicast packet.
static uint	spin1_send_fr_packet (uint key, uint data, uint load)
	This function enqueues a request to send a fixed-route packet.
static void	spin1_msg_free (sdp_msg_t *msg)
	Frees a received SDP message.
static sdp_msg_t *	spin1_msg_get (void)
	Gets an SDP message that has been sent to this core.
static uint	spin1_send_sdp_msg (sdp_msg_t *msg, uint timeout)
	Sends an SDP message.
SPIN1_INLINE void	spin1_store_barrier (void)
SPIN1_INLINE void	spin1_memory_barrier (void)
uint	spin1_irq_disable (void)
	Sets the I bit in the CPSR in order to disable IRQ interrupts to the processor.
uint	spin1_fiq_disable (void)
	Sets the F bit in the CPSR in order to disable FIQ interrupts in the processor.
uint	spin1_int_disable (void)
	Sets the F and I bits in the CPSR in order to disable FIQ and IRQ interrupts in the processor.
void	spin1_mode_restore (uint value)
	Sets the CPSR to the value given in sr, in order to restore the CPSR following a call to spin1_irq_disable().
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.
static void *	spin1_malloc (uint bytes)
	Returns a pointer to a newly-allocated block of memory of size "bytes" in DTCM.
static void	spin1_led_control (uint p)
	This function controls LEDs according to an input pattern.
static void	spin1_srand (uint seed)
	This function is used to initialize the seed for the pseudo-random number generator.
static uint	spin1_rand (void)
	This function generates a pseudo-random 32-bit integer.

Variables
static const uint	VIC_EVENTS []
	Match events above to their VIC interrupts. Indices must match!
diagnostics_t	diagnostics
	Miscellaneous diagnostic information, available to the application.
uchar	leadAp
	lead appl. core has special functions

Detailed Description

Header file describing the SpiNNaker API runtime environment.

---

Data Structure Documentation

diagnostics_t

struct diagnostics_t

diagnostic data available to the application

Data Fields
uint	exit_code	simulation exit code
uint	warnings	warnings type bit map
uint	total_mc_packets	total routed MC packets during simulation
uint	dumped_mc_packets	total dumped MC packets by the router
volatile uint	discarded_mc_packets	total discarded MC packets by API
uint	dma_transfers	total DMA transfers requested
uint	dma_bursts	total DMA bursts completed
uint	dma_queue_full	DMA queue full count.
uint	task_queue_full	task queue full count
uint	tx_packet_queue_full	transmitter packet queue full count
uint	user_event_queue_full	user event queue full count
uint	writeBack_errors	write-back buffer error count
uint	total_fr_packets	total routed FR packets during simulation
uint	dumped_fr_packets	total dumped FR packets by the router
uint	discarded_fr_packets	total discarded FR packets by API
uint	in_timer_callback	bool which states if currently in timer callback
uint	number_timer_tic_in_queue	the number of timer tic callbacks in the queue
uint	largest_number_of_concurrent_timer_tic_overruns	the max number of timer tics callbacks being queued at any time
uint	total_times_tick_tic_callback_overran	the total number of times the timer tic callback overran

Macro Definition Documentation

NULL

#define NULL   0

Null pointer value

Enumeration Type Documentation

anonymous enum

anonymous enum

event-related parameters

Enumerator
NUM_EVENTS	Count of possible events.
MC_PACKET_RECEIVED	Multicast packet received.
DMA_TRANSFER_DONE	DMA transfer complete.
TIMER_TICK	Regular timer tick.
SDP_PACKET_RX	SDP message received.
USER_EVENT	User-triggered interrupt.
MCPL_PACKET_RECEIVED	Multicast packet with payload received.
FR_PACKET_RECEIVED	Fixed route packet received.
FRPL_PACKET_RECEIVED	Fixed route packet with payload received.

anonymous enum

anonymous enum

DMA transfer direction (from core point of view)

Enumerator
DMA_READ	DMA read from SDRAM to TCM.
DMA_WRITE	DMA write from TCM to SDRAM.

anonymous enum

anonymous enum

Spinnaker packet payload presence flag.

Enumerator
NO_PAYLOAD	No payload word present.
WITH_PAYLOAD	Payload word present.

Function Documentation

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_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

spin1_set_timer_tick()

static void spin1_set_timer_tick ( uint  time )

inlinestatic

Set the timer tick rate. No phase offset.

Parameters

[in]

time

The timer tick rate

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_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

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

spin1_delay_us()

static void spin1_delay_us ( uint  n )

inlinestatic

This function implements a delay measured in microseconds.

The function busy waits to implement the delay.

Parameters

[in]

n

requested delay (in microseconds)

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

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

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_send_mc_packet()

static uint spin1_send_mc_packet ( uint  key, uint  data, uint  load  )

inlinestatic

This function enqueues a request to send a multicast packet.

If the software buffer is full then a failure code is returned. If the comms controller hardware buffer and the software buffer are empty then the the packet is sent immediately, otherwise it is placed in a queue to be consumed later by cc_tx_empty() interrupt service routine.

Parameters

[in]	key	packet routing key
[in]	data	packet payload
[in]	load	0 = no payload (ignore data param), 1 = send payload

Returns

SUCCESS or FAILURE

spin1_send_fr_packet()

static uint spin1_send_fr_packet ( uint  key, uint  data, uint  load  )

inlinestatic

This function enqueues a request to send a fixed-route packet.

If the software buffer is full then a failure code is returned. If the comms controller hardware buffer and the software buffer are empty then the the packet is sent immediately, otherwise it is placed in a queue to be consumed later by cc_tx_empty() interrupt service routine.

Parameters

[in]	key	packet routing key
[in]	data	packet payload
[in]	load	0 = no payload (ignore data param), 1 = send payload

Returns

SUCCESS or FAILURE

spin1_msg_free()

static void spin1_msg_free ( sdp_msg_t *  msg )

inlinestatic

Frees a received SDP message.

Parameters

[in]

msg

The message to free.

spin1_msg_get()

static sdp_msg_t * spin1_msg_get ( void  )

inlinestatic

Gets an SDP message that has been sent to this core.

Returns

The SDP message. Must be freed with spin1_msg_free()

spin1_send_sdp_msg()

static uint spin1_send_sdp_msg ( sdp_msg_t *  msg, uint  timeout  )

inlinestatic

Sends an SDP message.

Parameters

[in]	msg	The message to send.
[in]	timeout	How long to wait for the message to be enqueued by SC&MP.

Returns

SUCCESS or FAILURE

spin1_irq_disable()

uint spin1_irq_disable ( void  )

extern

Sets the I bit in the CPSR in order to disable IRQ interrupts to the processor.

Returns

state of the CPSR before the interrupt disable

spin1_fiq_disable()

uint spin1_fiq_disable ( void  )

extern

Sets the F bit in the CPSR in order to disable FIQ interrupts in the processor.

Returns

state of the CPSR before the interrupts disable

spin1_int_disable()

uint spin1_int_disable ( void  )

extern

Sets the F and I bits in the CPSR in order to disable FIQ and IRQ interrupts in the processor.

Returns

state of the CPSR before the interrupts disable

spin1_mode_restore()

void spin1_mode_restore ( uint  value )

extern

Sets the CPSR to the value given in sr, in order to restore the CPSR following a call to spin1_irq_disable().

Parameters

[in]

value

value with which to set the CPSR

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.

spin1_malloc()

static void * spin1_malloc ( uint  bytes )

inlinestatic

Returns a pointer to a newly-allocated block of memory of size "bytes" in DTCM.

Parameters

[in]

bytes

size, in bytes, of the requested memory block

Returns

pointer to the requested memory block, or 0 if unavailable

spin1_led_control()

static void spin1_led_control ( uint  p )

inlinestatic

This function controls LEDs according to an input pattern.

Macros for turning LED number N on, off or inverted are defined in spinnaker.h.

To turn LEDs 0 and 1 on, then invert LED2 and finally turn LED 0 off:

spin1_led_control(LED_ON(0) + LED_ON(1));
spin1_led_control(LED_INV(2));
spin1_led_control(LED_OFF(0));

Parameters

[in]

p

led control word

spin1_srand()

static void spin1_srand ( uint  seed )

inlinestatic

This function is used to initialize the seed for the pseudo-random number generator.

Parameters

[in]

seed

The seed for the PRNG

spin1_rand()

static uint spin1_rand ( void  )

inlinestatic

This function generates a pseudo-random 32-bit integer.

Taken from "Programming Techniques" ARM document ARM DUI 0021A

Returns

32-bit pseudo-random integer

Variable Documentation

VIC_EVENTS

const uint VIC_EVENTS[]

static

Initial value:

= {
    (1 << CC_MC_INT),         
    (1 << DMA_DONE_INT),      
    (1 << TIMER1_INT),        
    0,                        
    (1 << SOFTWARE_INT),      
    (1 << CC_MC_INT),         
    (1 << CC_FR_INT),         
    (1 << CC_FR_INT)          
}

Match events above to their VIC interrupts. Indices must match!