SARK - Spinnaker Application Runtime Kernel. More...

#include <sark.h>

Macros
#define	SARK_ID_STR "SARK/SpiNNaker"
	Our "application" identifier string.

Functions
void	sark_int_han (void)
	Interrupt handler for messages from SCAMP.

void	sark_fiq_han (void)
	Interrupt handler for messages from SCAMP. (FIQ)

void	rte_handler (uint code)
	Simple RTE handler.

uint	sark_chip_id (void)
	Returns the ID of this chip as a 16-bit number.

uint	sark_core_id (void)
	Returns the virtual core number of this core.

uint	sark_app_id (void)
	Returns the ID of the application running on this core.

uint	sark_count_bits (uint word)
	Count the number of bits set in a word.

uint	sark_str_len (char *string)
	Counts the number of characters in a zero terminated string.

void	sark_cpu_state (cpu_state state)
	Sets the CPU state field in the VCPU block for this core.

uint	sark_app_raise (void)
	Raise a semaphore associated with the AppID running on this core.

uint	sark_app_lower (void)
	Lowers a semaphore associated with the AppID running on this core.

uint	sark_app_sema (void)
	Used to get the value of the semaphore associated with the AppID running on this core.

uint	sark_app_cores (void)
	Used to get the number of cores on this chip which are running the current application.

uint	sark_app_lead (void)
	Returns the core ID of the lowest numbered core on this chip which is running the current application.

void	sw_error_fl (sw_err_mode mode, char *file, uint line)
	Generates a software error, logging the filename and line number at which the error occurs.

void *	sark_block_init (void *buf, uint count, uint size)
	Initialise a memory buffer into a linked list of "count" blocks of "size" bytes.

sdp_msg_t *	sark_msg_get (void)
	Get an SDP message buffer from the pool maintained by SARK.

void	sark_msg_free (sdp_msg_t *msg)
	Return an SDP message buffer which was acquired by sark_msg_get() to the free buffer pool.

void *	sark_block_get (mem_block_t *root)
	Generic call to get a buffer from a pool whose "root" is supplied.

void	sark_block_free (mem_block_t root, void blk)
	Generic call to free a buffer into a pool whose "root" is supplied.

sdp_msg_t *	sark_shmsg_get (void)
	Get a free SDP message from the shared SysRAM pool.

void	sark_shmsg_free (sdp_msg_t *msg)
	Return a shared memory SDP message to the shared SysRAM pool.

void	sark_call_cpp_constructors (void)
	Calls the constructors for any C++ objects created at global scope.

uint	sark_init (uint *stack)
	This sets up SARK stacks and some internal data structures.

void	sark_pre_main (void)
	Basic setup before calling c_main().

void	sark_post_main (void)
	Basic teardown after calling c_main().

uint	sark_msg_send (sdp_msg_t *msg, uint timeout)
	Send an SDP message.

uint	sark_cmd_ver (sdp_msg_t *msg)
	SCP handler for the Version command.

uint	sark_cmd_read (sdp_msg_t *msg)
	SCP handler for the Read command which reads memory and returns the data read to the host.

uint	sark_cmd_write (sdp_msg_t *msg)
	SCP handler for the Write command which writes memory with data supplied by the host.

uint	sark_cmd_fill (sdp_msg_t *msg)
	SCP handler for the Fill command which fills memory with a data word.

static uint	sark_debug (sdp_msg_t *msg)
	Basic SCP message handler.

static void	swap_hdr (sdp_msg_t *msg)
	Swap SDP headers around so that a reply goes back to the sender of the request that it is a reply for.

void	sark_int (void *pc)
	Handles messages from SCAMP.

Variables
sark_data_t	sark
	Main SARK variables.

Detailed Description

SARK - Spinnaker Application Runtime Kernel.

Copyright: © The University of Manchester - 2010-2013

Author: Steve Temple, APT Group, School of Computer Science

Function Documentation

◆ sark_fiq_han()

void sark_fiq_han ( void )

Interrupt handler for messages from SCAMP. (FIQ)

Just throws the packet away.

◆ rte_handler()

void rte_handler ( uint code )

Simple RTE handler.

Regs and state have been saved before we get here and if we return we do "cpu_shutdown". Can be replaced by user-provided alternative.

Parameters

[in] code The error code

◆ sark_chip_id()

uint sark_chip_id ( void )

Returns the ID of this chip as a 16-bit number.

The upper 8 bits are the X coordinate of the chip and the lower 8 bits are the Y coordinate. Just a wrapper to return sv->p2p_addr.

Returns: chip ID ((X << 8) + Y)

◆ sark_core_id()

uint sark_core_id ( void )

Returns the virtual core number of this core.

This is in the range 0 to 17 (though 0 will only be returned on the core which hosts the monitor processor). Just a wrapper to return sark.virt_cpu.

Returns: core number in the range 0..17

◆ sark_app_id()

uint sark_app_id ( void )

Returns the ID of the application running on this core.

Just a wrapper to return sark_vec->app_id.

Returns: application ID in the range 0..255

◆ sark_count_bits()

uint sark_count_bits ( uint word )

Count the number of bits set in a word.

Parameters

word	whose bits are to be counted

Returns: number of bits set

◆ sark_str_len()

uint sark_str_len ( char * string )

Counts the number of characters in a zero terminated string.

The terminator is not included in the count.

Parameters

string zero terminated string

Returns: number of characters

◆ sark_cpu_state()

void sark_cpu_state ( cpu_state state )

Sets the CPU state field in the VCPU block for this core.

Parameters

state the state to set

◆ sark_app_raise()

uint sark_app_raise ( void )

Raise a semaphore associated with the AppID running on this core.

The semaphore is initialised to zero before the application starts. Returns the new value of the semaphore and can be used to determine when all cores running a given application have reached a given point. Also allows a single core to be differentiated from other cores by testing for value 1 returned from this function. Uses sark_sema_raise.

Returns: value of semaphore after raising

◆ sark_app_lower()

uint sark_app_lower ( void )

Lowers a semaphore associated with the AppID running on this core.

If all cores running an application raise the semaphore when they start and lower it when they complete this can be used to determine when all cores have started (semaphore equals number of cores) and when all cores have finished (semaphore equals zero). Uses sark_sema_lower.

Returns: value of semaphore before lowering.

◆ sark_app_sema()

uint sark_app_sema ( void )

Used to get the value of the semaphore associated with the AppID running on this core.

Returns: current value of semaphore.

◆ sark_app_cores()

uint sark_app_cores ( void )

Used to get the number of cores on this chip which are running the current application.

Returns: number of cores with same AppID

◆ sark_app_lead()

uint sark_app_lead ( void )

Returns the core ID of the lowest numbered core on this chip which is running the current application.

Can be used to identify a single core to do shared initialisation.

Returns: lowest numbered core running this app.

◆ sw_error_fl()

void sw_error_fl	(	sw_err_mode	mode,
		char *	file,
		uint	line
	)

Generates a software error, logging the filename and line number at which the error occurs.

Usually used via the sw_error macro which inserts the filename and line number automatically. The mode parameter determines whether or not rt_error should be called to shut down the core. mode can be SW_RTE to always call rt_error(), SW_NEVER to always return or SW_OPT which consults sark.sw_rte to choose what to do.

Parameters

mode	determines if rt_error() is called
file	file name
line	line number

◆ sark_block_init()

void * sark_block_init	(	void *	buf,
		uint	size,
		uint	count
	)

Initialise a memory buffer into a linked list of "count" blocks of "size" bytes.

size needs to be at least 4 and a multiple of 4 and the memory buffer needs to be at least size * count" bytes</tt>. The first word of each block is a pointer to the next block. Returns a pointer to the last block. The buffer can be used to initialise a "root" struct of type mem_block_t.

Parameters


  
    buf base address of memory buffer (word aligned) 
    size of each block (at least 4 and a multiple of 4) 
    count number of blocks


Returns
pointer to last block

◆ sark_msg_get()

sdp_msg_t * sark_msg_get ( void )

Get an SDP message buffer from the pool maintained by SARK.

Applications typically have 4 buffers in the pool though this can be changed by setting sark_vec->num_msgs in sark_config. If there are no free buffers available, NULL is returned.

Returns: pointer to SDP buffer (or NULL)

◆ sark_msg_free()

void sark_msg_free ( sdp_msg_t * msg )

Return an SDP message buffer which was acquired by sark_msg_get() to the free buffer pool.

Parameters

msg	pointer to SDP message

◆ sark_block_get()

void * sark_block_get ( mem_block_t * root )

Generic call to get a buffer from a pool whose "root" is supplied.

Returns pointer to buffer on success, NULL on failure.

Parameters

root	pointer to a block pool held in a mem_block_t

Returns: pointer to a free block if available or NULL if not

◆ sark_block_free()

void sark_block_free	(	mem_block_t *	root,
		void *	blk
	)

Generic call to free a buffer into a pool whose "root" is supplied.

The block should have been allocated from the same pool previously!

Parameters

root	pointer to a block pool held in a mem_block_t
blk	pointer to the block to be freed.

◆ sark_shmsg_get()

sdp_msg_t * sark_shmsg_get ( void )

Get a free SDP message from the shared SysRAM pool.

Returns pointer to message on success, NULL on failure. Because several cores may attempt to access a shared memory message concurrently, a hardware lock is used to ensure exclusive access. Interrupts are turned off while this occurs but this should be for a relatively short time (1-5us ??)

Returns: pointer to a shared memory SDP message or NULL if none available

◆ sark_shmsg_free()

void sark_shmsg_free ( sdp_msg_t * msg )

Return a shared memory SDP message to the shared SysRAM pool.

Because several cores may attempt to access a shared memory message concurrently, a hardware lock is used to ensure exclusive access. Interrupts are turned off while this occurs but this should be for a relatively short time (1-5us ??)

Parameters

msg	pointer to the message

◆ sark_call_cpp_constructors()

void sark_call_cpp_constructors ( void )

Calls the constructors for any C++ objects created at global scope.

Should generally be called from any user-supplied sark_pre_main() function

◆ sark_init()

uint sark_init ( uint * stack )

This sets up SARK stacks and some internal data structures.

This is a weak declaration so that it may be replaced with another routine though not many systems will want to do this.

"sark_config" (also weak — see sark_alib.s) can be used to preconfigure some parameters which are used here.

Note: arrive in SVC mode — must leave in same mode!

Parameters

[in] stack the top of the SVC stack

Returns: the mode (CPSR) which will be entered on return

◆ sark_pre_main()

void sark_pre_main ( void )

Basic setup before calling c_main().

Can be replaced by user code by name override.

◆ sark_post_main()

void sark_post_main ( void )

Basic teardown after calling c_main().

Can be replaced by user code by name override.

◆ sark_msg_send()

uint sark_msg_send	(	sdp_msg_t *	msg,
		uint	timeout
	)

Send an SDP message.

The message is sent to the monitor processor using a shared memory buffer and then sent to the appropriate place from there. A timeout in milliseconds must be supplied which applies to the transfer of the message to the monitor processor. Normally this will take less than 1ms if the monitor processor is functioning normally. A timeout of 10ms is probably appropriate in most circumstances. The call can fail either because of a timeout or if there are no shared memory SDP buffers available.

Parameters

msg	pointer to an SDP message buffer
timeout	time in ms before sending is abandoned

Returns: 1 if successful, 0 for failure

◆ sark_cmd_ver()

uint sark_cmd_ver ( sdp_msg_t * msg )

SCP handler for the Version command.

Copies various pieces of information into the supplied SDP message buffer. The information copied is the chip address (16 bits), virtual and physical core numbers (8 bits each), the version number of SARK (16 bits), the size of SDP message data buffers (16 bits) and the Unix time at which the application was built (32 bits). A text string is also returned which gives the base kernel name (eg SARK) and the system on which it is running (eg SpiNNaker).

(Unlikely to be called by application code).

Parameters

msg	SDP message buffer

Returns: size of returned message

◆ sark_cmd_read()

uint sark_cmd_read ( sdp_msg_t * msg )

SCP handler for the Read command which reads memory and returns the data read to the host.

Various argument errors are trapped but if successful, data is transferred from memory into the SDP message starting at msg->arg1. If half or word alignment is specified, the address and count must be 2 or 4 byte aligned.

(Unlikely to be called by application code).

Parameters

msg	The message: `msg->arg1`: first address to be read (suitably aligned) `msg->arg2`: number of bytes to read (suitably aligned) `msg->arg3`: mode of reading (TYPE_BYTE, TYPE_HALF or TYPE_WORD)

Returns: size of returned message

◆ sark_cmd_write()

uint sark_cmd_write ( sdp_msg_t * msg )

SCP handler for the Write command which writes memory with data supplied by the host.

Various argument errors are trapped but if successful, data is transferred to memory from the SDP message starting at msg->data. If half or word alignment is specified, the address and count must be 2 or 4 byte aligned.

(Unlikely to be called by application code).

Parameters

msg	The message: `msg->arg1`: first address to be written (suitably aligned) `msg->arg2`: number of bytes to write (suitably aligned) `msg->arg3`: mode of writing (TYPE_BYTE, TYPE_HALF or TYPE_WORD) `msg->data`: data to be written

Returns: size of returned message (usually 0)

◆ sark_cmd_fill()

uint sark_cmd_fill ( sdp_msg_t * msg )

SCP handler for the Fill command which fills memory with a data word.

(Unlikely to be called by application code).

Parameters

msg	The message `msg->arg1`: first address to be written (must be word aligned) `msg->arg2`: data word `msg->arg3`: byte count (must be non-zero and a multiple of 4)

Returns: size of returned message (usually 0)

◆ sark_debug()

static uint sark_debug ( sdp_msg_t * msg )

static

Basic SCP message handler.

SARK only supports a subset of messages. Will delegate to:

sark_cmd_ver()
sark_cmd_read()
sark_cmd_write()
sark_cmd_fill()
Parameters

[in,out] msg The SCP message

Returns
the size of the result message payload, in bytes

◆ swap_hdr()

static void swap_hdr ( sdp_msg_t * msg )

static

Swap SDP headers around so that a reply goes back to the sender of the request that it is a reply for.

Parameters

[in,out] msg The SDP message

◆ sark_int()

void sark_int ( void * pc )

Handles messages from SCAMP.

Interrupt handler for CPU interrupt from monitor processor. Entry and exit are via wrapper code sark_int_han() in "sark_alib.s" This handler executes in System mode with interrupts enabled.

Handles watchdog timer responses, signals, SDP message reception. Delegates to:

Parameters

[in] pc Where the CPU was executing when the interrupt happened. Used for watchdog reporting.

buf	base address of memory buffer (word aligned)
size	of each block (at least 4 and a multiple of 4)
count	number of blocks

Macros

Functions

Variables

Detailed Description

Function Documentation

◆ sark_fiq_han()

◆ rte_handler()

◆ sark_chip_id()

◆ sark_core_id()

◆ sark_app_id()

◆ sark_count_bits()

◆ sark_str_len()

◆ sark_cpu_state()

◆ sark_app_raise()

◆ sark_app_lower()

◆ sark_app_sema()

◆ sark_app_cores()

◆ sark_app_lead()

◆ sw_error_fl()

◆ sark_block_init()

◆ sark_msg_get()

◆ sark_msg_free()

◆ sark_block_get()

◆ sark_block_free()

◆ sark_shmsg_get()

◆ sark_shmsg_free()

◆ sark_call_cpp_constructors()

◆ sark_init()

◆ sark_pre_main()

◆ sark_post_main()

◆ sark_msg_send()

◆ sark_cmd_ver()

◆ sark_cmd_read()

◆ sark_cmd_write()

◆ sark_cmd_fill()

◆ sark_debug()

◆ swap_hdr()

◆ sark_int()