spinnaker_tools 3.4.0
SpiNNaker API, sark, sc&mp, bmp firmware and build tools
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
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_tspin1_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]syncWhether 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]errorerror 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]timeThe timer tick rate
[in]phaseThe 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]timeThe 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]syncWhether 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]codethe 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]nrequested 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_idWhich event to enable
[in]cbackThe callback handler
[in]priorityThe 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_idWhich 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]cbackcallback to be scheduled
[in]arg0argument to be passed to the callback
[in]arg1argument to be passed to the callback
[in]prioritycback 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]arg0argument to be passed to the callback
[in]arg1argument 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]tagA label for the transfer. Can be used by DMA complete callback to work out what to do.
system_addressAddress in SDRAM. May be source or destination. Must be word-aligned.
tcm_addressAddress in TCM. May be source or destination. Must be word-aligned.
[in]directionWhich direction is data being moved in.
[in]lengthHow 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]dstWhere to copy to
[in]srcWhere to copy from
[in]lenNumber 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]keyThe key of the packet. Determines destinations.
[in]dataThe payload (if any).
[in]TCRTransmission 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]keypacket routing key
[in]datapacket payload
[in]load0 = 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]keypacket routing key
[in]datapacket payload
[in]load0 = 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]msgThe 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]msgThe message to send.
[in]timeoutHow 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]valuevalue 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]bytessize, 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]pled 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]seedThe 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)
}
@ SOFTWARE_INT
Used only for local software interrupt generation.
Definition spinnaker.h:356
@ CC_FR_INT
Local comms controller fixed route packet received.
Definition spinnaker.h:382
@ DMA_DONE_INT
Local DMA controller transfer complete.
Definition spinnaker.h:367
@ CC_MC_INT
Local comms controller multicast packet received.
Definition spinnaker.h:379
@ TIMER1_INT
Local counter/timer interrupt 1.
Definition spinnaker.h:359

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