The implementation of the Live Packet Gatherer. More...

#include <common-typedefs.h>
#include <circular_buffer.h>
#include <data_specification.h>
#include <debug.h>
#include <simulation.h>
#include <spin1_api.h>
#include <eieio.h>

Data Structures
struct	lpg_provenance_data_t
	Provenance data store. More...

struct	key_translation_entry

struct	lpg_config
	Definitions of each element in the configuration. More...

Macros
#define	FLAG_IS_SET(flags, bit) (((flags) & (bit)) != 0)
	How to test if a bit flag is set.

#define	CLAMP8(value) ((value) & 0xFF)
	How to use just the low 8 bits of an integer value.

#define	CLAMP16(value) ((value) & 0xFFFF)
	How to use just the low 16 bits of an integer value.

#define	HAVE_PAYLOAD(pkt_type) FLAG_IS_SET(pkt_type, 0x1)
	Does the packet type include a payload?

#define	HAVE_WIDE_LOAD(pkt_type) FLAG_IS_SET(pkt_type, 0x2)
	Does the packet type include a double-width payload?

#define	BUFFER_CAPACITY 256
	The size of the circular buffers.

Enumerations
enum	{ MC_PACKET = -1 , SDP = 0 , USER = 1 , DMA = 2 , TIMER = 3 }
	values for the priority for each callback More...

enum	{ SYSTEM_REGION , CONFIGURATION_REGION , PROVENANCE_REGION }
	human readable definitions of each region in SDRAM More...

enum	packet_types { NO_PAYLOAD_16 , PAYLOAD_16 , NO_PAYLOAD_32 , PAYLOAD_32 }
	EIEIO packet types. More...

Functions
static bool	find_translation_entry (uint32_t key, uint32_t *index)
	find a key translation entry

static uint32_t	translated_key (uint32_t key)

static void	write_word (void *base, uint32_t index, uint32_t value)
	Because WHY OH WHY would you use aligned memory? At least with this we don't get data aborts.

static void	write_short (void *base, uint32_t index, uint32_t value)
	Simple mirror of write_word() for true 16 bit values.

static uint8_t	get_event_count (void)
	Get how many events there are waiting to be sent.

static void	flush_events (void)
	Send buffered events to host via SDP AER message and clear internal buffers.

static void	record_provenance_data (address_t provenance_region_address)
	Store provenance data elements into SDRAM.

static void	timer_callback (uint unused0, uint unused1)
	Periodic timer callback.

static void	flush_events_if_full (void)
	Flush events to the outside world if our internal buffers are now full.

static void	process_incoming_event (uint key)
	Processes an incoming multicast packet without payload.

static void	process_incoming_event_payload (uint key, uint payload)
	Processes an incoming multicast packet with payload.

static void	incoming_event_process_callback (uint unused0, uint unused1)
	Handler for processing incoming packets that have been locally queued.

static void	incoming_event_callback (uint key, uint unused)
	FIQ handler for incoming packets without payload.

static void	incoming_event_payload_callback (uint key, uint payload)
	FIQ handler for incoming packets with payload.

static bool	read_parameters (struct lpg_config *sdram_config)
	Copies the application configuration from DSG SDRAM to DTCM.

static bool	initialize (uint32_t *timer_period)
	Initialise the application.

static bool	configure_sdp_msg (void)
	Sets up the AER EIEIO data message.

void	c_main (void)
	Entry point.

Variables
static sdp_msg_t	g_event_message
	The SDP message that we will send.

static uint16_t *	sdp_msg_aer_header
	The location of the EIEIO header in the message.

static uint16_t *	sdp_msg_aer_payload_prefix = NULL
	The location of the payload prefix in the message. `NULL` if no prefix.

static uint16_t *	sdp_msg_aer_data
	Pointer to outbound message data. Might only be half-word aligned!

static uint32_t	time
	Current simulation time.

static uint32_t	packets_sent
	The number of packets sent so far this timestamp.

static uint32_t	buffer_index
	Index into our buffer in sdp_msg_aer_data.

static uint16_t	eieio_constant_header
	Part of the generic EIEIO header that is constant.

static uint8_t	event_size
	The size of an individual event.

static uint8_t	sdp_msg_aer_header_len
	The length of the header, in bytes.

static uint32_t	simulation_ticks = 0
	When we will run until.

static uint32_t	infinite_run = FALSE
	TRUE if we're running without bound. FALSE if we're only running for a limited period of time.

static circular_buffer	without_payload_buffer
	Circular buffer of incoming multicast packets that lack payloads.

static circular_buffer	with_payload_buffer
	Circular buffer of incoming multicast packets that have payloads.

static bool	processing_events = false
	Whether we are processing events (or discarding them).

static lpg_provenance_data_t	provenance_data
	The provenance information that we are collecting.

static struct lpg_config *	config
	The configuration data of the application.

Detailed Description

The implementation of the Live Packet Gatherer.

The purpose of this application is to allow recorded information to be streamed out of SpiNNaker in real time. It does not scale very well, as SpiNNaker's aggregate internal state can change with a much higher bandwidth than its external networking can handle.

Definition in file live_packet_gather.c.

Data Structure Documentation

◆ lpg_provenance_data_t

struct lpg_provenance_data_t

Provenance data store.

Definition at line 35 of file live_packet_gather.c.

Data Fields
uint32_t	number_of_overflows_no_payload	Count of overflows when no payload was sent.
uint32_t	number_of_overflows_with_payload	Count of overflows when a payload was sent.
uint32_t	number_of_gathered_events	Number of events gathered and recorded.
uint32_t	number_of_sent_messages	Number of messages sent to host.

◆ key_translation_entry

struct key_translation_entry

Definition at line 46 of file live_packet_gather.c.

Data Fields
uint32_t	key
uint32_t	mask
uint32_t	lo_atom

◆ lpg_config

struct lpg_config

Definitions of each element in the configuration.

This is copied from SDRAM into DTCM for speed.

Definition at line 58 of file live_packet_gather.c.

Data Fields
uint32_t	apply_prefix	P bit.
uint32_t	prefix	Prefix data.
uint32_t	prefix_type	Type bits.
uint32_t	packet_type	F bit (for the receiver)
uint32_t	key_right_shift	Right payload shift (for the sender)
uint32_t	payload_timestamp	T bit.
uint32_t	payload_apply_prefix	D bit.
uint32_t	payload_prefix	Payload prefix data (for the receiver)
uint32_t	payload_right_shift	Right payload shift (for the sender)
uint32_t	sdp_tag	SDP tag to use when sending.
uint32_t	sdp_dest	SDP destination to use when sending.
uint32_t	packets_per_timestamp	Maximum number of packets to send per timestep, or 0 for "send them all".
uint32_t	received_key_mask	Mask to apply to non-translated keys.
uint32_t	translated_key_right_shift	Shift to apply to received and translated keys.
uint32_t	n_translation_entries	The number of entries in the translation table.
key_translation_entry	translation_table[]	Translation table.

Macro Definition Documentation

◆ FLAG_IS_SET

#define FLAG_IS_SET	(	flags,
		bit
	)	(((flags) & (bit)) != 0)

How to test if a bit flag is set.

Definition at line 171 of file live_packet_gather.c.

◆ CLAMP8

#define CLAMP8 ( value ) ((value) & 0xFF)

How to use just the low 8 bits of an integer value.

Definition at line 174 of file live_packet_gather.c.

◆ CLAMP16

#define CLAMP16 ( value ) ((value) & 0xFFFF)

How to use just the low 16 bits of an integer value.

Definition at line 177 of file live_packet_gather.c.

◆ HAVE_PAYLOAD

#define HAVE_PAYLOAD ( pkt_type ) FLAG_IS_SET(pkt_type, 0x1)

Does the packet type include a payload?

Definition at line 180 of file live_packet_gather.c.

◆ HAVE_WIDE_LOAD

#define HAVE_WIDE_LOAD ( pkt_type ) FLAG_IS_SET(pkt_type, 0x2)

Does the packet type include a double-width payload?

Definition at line 183 of file live_packet_gather.c.

◆ BUFFER_CAPACITY

#define BUFFER_CAPACITY 256

The size of the circular buffers.

Definition at line 186 of file live_packet_gather.c.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

values for the priority for each callback

Enumerator
MC_PACKET	Multicast packet interrupt uses FIQ (super high prio)
SDP	SDP interrupt is highest priority.
USER	Interrupt for enqueued list of received packets.
DMA	DMA complete interrupt is low priority.
TIMER	Timer interrupt is lowest priority.

Definition at line 94 of file live_packet_gather.c.

◆ anonymous enum

anonymous enum

human readable definitions of each region in SDRAM

Definition at line 103 of file live_packet_gather.c.

◆ packet_types

enum packet_types

EIEIO packet types.

Definition at line 110 of file live_packet_gather.c.

Function Documentation

◆ find_translation_entry()

static bool find_translation_entry	(	uint32_t	key,
		uint32_t *	index
	)

inlinestatic

find a key translation entry

Definition at line 189 of file live_packet_gather.c.

◆ translated_key()

static uint32_t translated_key ( uint32_t key )

inlinestatic

Definition at line 215 of file live_packet_gather.c.

◆ write_word()

static void write_word	(	void *	base,
		uint32_t	index,
		uint32_t	value
	)

inlinestatic

Because WHY OH WHY would you use aligned memory? At least with this we don't get data aborts.

Parameters

[out]	base	Buffer to write in. Only guaranteed to be half-word aligned.
[in]	index	Offset in count of words into the buffer.
[in]	value	Value to write in (as little-endian).

Definition at line 239 of file live_packet_gather.c.

◆ write_short()

static void write_short	(	void *	base,
		uint32_t	index,
		uint32_t	value
	)

inlinestatic

Simple mirror of write_word() for true 16 bit values.

Parameters

[in]	base	place to write to
[in]	index	location in base to write to
[in]	value	the value to write to the base.

Definition at line 250 of file live_packet_gather.c.

◆ get_event_count()

static uint8_t get_event_count ( void )

inlinestatic

Get how many events there are waiting to be sent.

Returns: The number of events waiting

Definition at line 257 of file live_packet_gather.c.

◆ flush_events()

static void flush_events ( void )

static

Send buffered events to host via SDP AER message and clear internal buffers.

Definition at line 268 of file live_packet_gather.c.

◆ record_provenance_data()

static void record_provenance_data ( address_t provenance_region_address )

static

Store provenance data elements into SDRAM.

Parameters

[out] provenance_region_address Where the provenance data will be written

Definition at line 304 of file live_packet_gather.c.

◆ timer_callback()

static void timer_callback	(	uint	unused0,
		uint	unused1
	)

static

Periodic timer callback.

Forces all events to be sent at least on the timer tick (calling flush_events()) and handles pausing as required.

Parameters

unused0	unused
unused1	unused

Definition at line 318 of file live_packet_gather.c.

◆ flush_events_if_full()

static void flush_events_if_full ( void )

inlinestatic

Flush events to the outside world if our internal buffers are now full.

Calls flush_events() to do the flush.

Definition at line 345 of file live_packet_gather.c.

◆ process_incoming_event()

static void process_incoming_event ( uint key )

static

Processes an incoming multicast packet without payload.

Parameters

[in] key The key of the packet.

Definition at line 353 of file live_packet_gather.c.

◆ process_incoming_event_payload()

static void process_incoming_event_payload	(	uint	key,
		uint	payload
	)

static

Processes an incoming multicast packet with payload.

Parameters

[in]	key	The key of the packet.
[in]	payload	The payload word of the packet.

Definition at line 385 of file live_packet_gather.c.

◆ incoming_event_process_callback()

static void incoming_event_process_callback	(	uint	unused0,
		uint	unused1
	)

static

Handler for processing incoming packets that have been locally queued.

Triggered by calling spin1_trigger_user_event() in incoming_event_callback() and incoming_event_payload_callback(), which (being attached to the FIQ) just enqueue messages for later handling. Delegates to process_incoming_event() and process_incoming_event_payload() for actual processing.

Packets without payload are slightly higher priority than packets with payload.

Sends multiple SDP packets if required.

Parameters

unused0	Ignored
unused1	Ignored

Definition at line 430 of file live_packet_gather.c.

◆ incoming_event_callback()

static void incoming_event_callback	(	uint	key,
		uint	unused
	)

static

FIQ handler for incoming packets without payload.

Just enqueues them for later handling by incoming_event_process_callback(), which will hand off to process_incoming_event().

Parameters

[in]	key	The key of the incoming packet.
	unused	unused

Definition at line 459 of file live_packet_gather.c.

◆ incoming_event_payload_callback()

static void incoming_event_payload_callback	(	uint	key,
		uint	payload
	)

static

FIQ handler for incoming packets with payload.

Just enqueues them for later handling by incoming_event_process_callback(), which will hand off to process_incoming_event_payload().

Parameters

[in]	key	The key of the incoming packet.
[in]	payload	The payload word of the incoming packet.

Definition at line 479 of file live_packet_gather.c.

◆ read_parameters()

static bool read_parameters ( struct lpg_config * sdram_config )

static

Copies the application configuration from DSG SDRAM to DTCM.

Note that it's faster to copy by field than to use spin1_memcpy()!

Parameters

[in] sdram_config Where to copy from

Definition at line 498 of file live_packet_gather.c.

◆ initialize()

static bool initialize ( uint32_t * timer_period )

static

Initialise the application.

Parameters

[out] timer_period Value for programming the timer ticks. A pointer to this variable is retained by the simulation framework.

Returns: True if initialisation succeeds.

Definition at line 535 of file live_packet_gather.c.

◆ configure_sdp_msg()

static bool configure_sdp_msg ( void )

static

Sets up the AER EIEIO data message.

Returns: bool where True was successful init and false otherwise.

Definition at line 568 of file live_packet_gather.c.

◆ c_main()

void c_main ( void )

Entry point.

Definition at line 673 of file live_packet_gather.c.

Variable Documentation

◆ g_event_message

sdp_msg_t g_event_message

static

The SDP message that we will send.

Definition at line 119 of file live_packet_gather.c.

◆ sdp_msg_aer_header

uint16_t* sdp_msg_aer_header

static

The location of the EIEIO header in the message.

Definition at line 122 of file live_packet_gather.c.

◆ sdp_msg_aer_payload_prefix

uint16_t* sdp_msg_aer_payload_prefix = NULL

static

The location of the payload prefix in the message. NULL if no prefix.

Definition at line 125 of file live_packet_gather.c.

◆ sdp_msg_aer_data

uint16_t* sdp_msg_aer_data

static

Pointer to outbound message data. Might only be half-word aligned!

Definition at line 128 of file live_packet_gather.c.

◆ time

uint32_t time

static

Current simulation time.

Definition at line 131 of file live_packet_gather.c.

◆ packets_sent

uint32_t packets_sent

static

The number of packets sent so far this timestamp.

Definition at line 134 of file live_packet_gather.c.

◆ buffer_index

uint32_t buffer_index

static

Index into our buffer in sdp_msg_aer_data.

Definition at line 137 of file live_packet_gather.c.

◆ eieio_constant_header

uint16_t eieio_constant_header

static

Part of the generic EIEIO header that is constant.

Definition at line 140 of file live_packet_gather.c.

◆ event_size

uint8_t event_size

static

The size of an individual event.

Definition at line 143 of file live_packet_gather.c.

◆ sdp_msg_aer_header_len

uint8_t sdp_msg_aer_header_len

static

The length of the header, in bytes.

Definition at line 146 of file live_packet_gather.c.

◆ simulation_ticks

uint32_t simulation_ticks = 0

static

When we will run until.

Definition at line 149 of file live_packet_gather.c.

◆ infinite_run

uint32_t infinite_run = FALSE

static

TRUE if we're running without bound. FALSE if we're only running for a limited period of time.

Definition at line 153 of file live_packet_gather.c.

◆ without_payload_buffer

circular_buffer without_payload_buffer

static

Circular buffer of incoming multicast packets that lack payloads.

Definition at line 156 of file live_packet_gather.c.

◆ with_payload_buffer

circular_buffer with_payload_buffer

static

Circular buffer of incoming multicast packets that have payloads.

Definition at line 159 of file live_packet_gather.c.

◆ processing_events

bool processing_events = false

static

Whether we are processing events (or discarding them).

Definition at line 162 of file live_packet_gather.c.

◆ provenance_data

lpg_provenance_data_t provenance_data

static

The provenance information that we are collecting.

Definition at line 165 of file live_packet_gather.c.

◆ config

struct lpg_config* config

static

The configuration data of the application.

Definition at line 168 of file live_packet_gather.c.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ lpg_provenance_data_t

◆ key_translation_entry

◆ lpg_config

Macro Definition Documentation

◆ FLAG_IS_SET

◆ CLAMP8

◆ CLAMP16

◆ HAVE_PAYLOAD

◆ HAVE_WIDE_LOAD

◆ BUFFER_CAPACITY

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ packet_types

Function Documentation

◆ find_translation_entry()

◆ translated_key()

◆ write_word()

◆ write_short()

◆ get_event_count()

◆ flush_events()

◆ record_provenance_data()

◆ timer_callback()

◆ flush_events_if_full()

◆ process_incoming_event()

◆ process_incoming_event_payload()

◆ incoming_event_process_callback()

◆ incoming_event_callback()

◆ incoming_event_payload_callback()

◆ read_parameters()

◆ initialize()

◆ configure_sdp_msg()

◆ c_main()

Variable Documentation

◆ g_event_message

◆ sdp_msg_aer_header

◆ sdp_msg_aer_payload_prefix

◆ sdp_msg_aer_data

◆ time

◆ packets_sent

◆ buffer_index

◆ eieio_constant_header

◆ event_size

◆ sdp_msg_aer_header_len

◆ simulation_ticks

◆ infinite_run

◆ without_payload_buffer

◆ with_payload_buffer

◆ processing_events

◆ provenance_data

◆ config