Simulation Functions Header File. More...

#include <stdbool.h>
#include "common-typedefs.h"
#include <spin1_api.h>

Data Structures
struct	simulation_config
	the position and human readable terms for each element from the region containing the timing details. More...

struct	simulation_provenance
	elements that are always grabbed for provenance if possible when requested More...

Macros
#define	MAX_DMA_CALLBACK_TAG 16

Typedefs
typedef void(*	prov_callback_t) (address_t)
	the definition of the callback used by provenance data functions

typedef void(*	resume_callback_t) (void)
	the definition of the callback used by pause and resume

typedef void(*	exit_callback_t) (void)

typedef resume_callback_t	start_callback_t
	the definition of the callback used to call a function once at start

Enumerations
enum	simulation_commands { CMD_STOP = 6 , CMD_RUNTIME = 7 , PROVENANCE_DATA_GATHERING = 8 , IOBUF_CLEAR = 9 , CMD_PAUSE = 10 , CMD_GET_TIME = 11 }
	the commands that the simulation control protocol may send More...

Functions
bool	simulation_initialise (address_t address, uint32_t expected_application_magic_number, uint32_t timer_period, uint32_t simulation_ticks_pointer, uint32_t infinite_run_pointer, uint32_t time_pointer, int sdp_packet_callback_priority, int dma_transfer_complete_priority)
	initialises the simulation interface which involves: More...

static bool	simulation_steps_initialise (address_t address, uint32_t expected_application_magic_number, uint32_t simulation_steps_pointer, uint32_t infinite_steps_pointer, uint32_t *step_pointer, int sdp_packet_callback_priority, int dma_transfer_complete_priority)
	initialises the simulation interface for step-based simulation, which involves: More...

void	simulation_set_provenance_data_address (address_t provenance_data_address)
	Set the address of the data region where provenance data is to be stored. More...

void	simulation_set_provenance_function (prov_callback_t provenance_function, address_t provenance_data_address)
	Set an additional callback function to store extra provenance data. More...

void	simulation_set_exit_function (exit_callback_t exit_function)
	Set an additional function to call before exiting the binary when running without a fixed duration of execution. More...

void	simulation_set_start_function (start_callback_t start_function)
	Set an additional function to call before starting the binary. More...

void	simulation_handle_pause_resume (resume_callback_t callback)
	cleans up the house keeping, falls into a sync state and handles the resetting up of states as required to resume. Note that following this function, the code should call simulation_ready_to_read (see later). More...

void	simulation_exit (void)
	a helper method for people not using the auto pause and resume functionality More...

void	simulation_run (void)
	Starts the simulation running, returning when it is complete,.

void	simulation_ready_to_read (void)
	Indicates that all data has been written and the core is going idle, so any data can now be read.

bool	simulation_sdp_callback_on (uint sdp_port, callback_t sdp_callback)
	Registers an additional SDP callback on a given SDP port. This is required when using simulation_register_sdp_callback, as this will register its own SDP handler. More...

void	simulation_sdp_callback_off (uint sdp_port)
	disables SDP callbacks on the given port More...

bool	simulation_dma_transfer_done_callback_on (uint tag, callback_t callback)
	registers a DMA transfer callback to the simulation system More...

void	simulation_dma_transfer_done_callback_off (uint tag)
	turns off a registered callback for a given DMA transfer done tag More...

void	simulation_set_uses_timer (bool sim_uses_timer)
	set whether the simulation uses the timer. By default it will be assumed that simulations use the timer unless this function is called. More...

void	simulation_set_sync_steps (uint32_t n_steps)
	sets the simulation to enter a synchronisation barrier repeatedly during the simulation. The synchronisation message must be sent from the host. Note simulation_is_finished() must be used each timestep to cause the pause to happen. More...

bool	simulation_is_finished (void)
	determine if the simulation is finished. Will also pause the simulation for resynchronisation if requested (see simulation_set_sync_steps). More...

Detailed Description

Simulation Functions Header File.

Specifies functions that are used to get simulation information and start simulations.

Definition in file simulation.h.

Data Structure Documentation

◆ simulation_config

struct simulation_config

the position and human readable terms for each element from the region containing the timing details.

Definition at line 39 of file simulation.h.

Data Fields
uint32_t	application_magic_number
uint32_t	timer_period
uint32_t	control_sdp_port
uint32_t	num_timing_detail_words

◆ simulation_provenance

struct simulation_provenance

elements that are always grabbed for provenance if possible when requested

Definition at line 47 of file simulation.h.

Data Fields
uint32_t	transmission_event_overflow
uint32_t	callback_queue_overloads
uint32_t	dma_queue_overloads
uint32_t	user_queue_overloads
uint32_t	timer_tic_has_overrun
uint32_t	max_num_timer_tic_overrun
uint32_t	provenance_data_elements[]

Macro Definition Documentation

◆ MAX_DMA_CALLBACK_TAG

#define MAX_DMA_CALLBACK_TAG 16

constant for how many DMA IDs you can use (caps the values of the tags as well)

Definition at line 35 of file simulation.h.

Typedef Documentation

◆ exit_callback_t

typedef void(* exit_callback_t) (void)

the definition of the callback used by pause and resume when exit command is sent and models want to do cleaning up

Definition at line 82 of file simulation.h.

Enumeration Type Documentation

◆ simulation_commands

enum simulation_commands

the commands that the simulation control protocol may send

Enumerator
CMD_STOP	Asks the simulation loop to stop as soon as possible.
CMD_RUNTIME	Tells the simulation loop how long to run for.
PROVENANCE_DATA_GATHERING	Asks the application to gather provenance data.
IOBUF_CLEAR	Clears the IOBUF.
CMD_PAUSE	Asks the application to pause. This relies on the application using simulation_is_finished which can then handle the pause status better.
CMD_GET_TIME	Get the current simulation time.

Definition at line 58 of file simulation.h.

Function Documentation

◆ simulation_initialise()

bool simulation_initialise	(	address_t	address,
		uint32_t	expected_application_magic_number,
		uint32_t *	timer_period,
		uint32_t *	simulation_ticks_pointer,
		uint32_t *	infinite_run_pointer,
		uint32_t *	time_pointer,
		int	sdp_packet_callback_priority,
		int	dma_transfer_complete_priority
	)

initialises the simulation interface which involves:

Reading the timing details for the simulation out of a region, which is formatted as: uint32_t magic_number; uint32_t timer_period; uint32_t n_simulation_ticks;
setting the simulation SDP port code that supports multiple runs of the executing code through front end calls.

setting up the registration for storing provenance data

Parameters

[in]	address	The address of the region
[in]	expected_application_magic_number	The expected value of the magic number that checks if the data was meant for this code
[out]	timer_period	Pointer to an int to receive the timer period, in microseconds
[in]	simulation_ticks_pointer	Pointer to the number of simulation ticks, to allow this to be updated when requested via SDP
[in]	infinite_run_pointer	Pointer to the infinite run flag, to allow this to be updated when requested via SDP
[in]	time_pointer	Pointer to the current time, to allow this to be updated when requested via SDP
[in]	sdp_packet_callback_priority	The priority to use for the SDP packet reception
[in]	dma_transfer_complete_priority	The priority to use for the DMA transfer complete callbacks

Returns: True if the data was found, false otherwise

Definition at line 370 of file simulation.c.

◆ simulation_steps_initialise()

static bool simulation_steps_initialise	(	address_t	address,
		uint32_t	expected_application_magic_number,
		uint32_t *	simulation_steps_pointer,
		uint32_t *	infinite_steps_pointer,
		uint32_t *	step_pointer,
		int	sdp_packet_callback_priority,
		int	dma_transfer_complete_priority
	)

inlinestatic

initialises the simulation interface for step-based simulation, which involves:

Reading the timing details for the simulation out of a region, which is formatted as: uint32_t magic_number; uint32_t timer_period; (ignored in this case) uint32_t n_simulation_steps;
setting the simulation SDP port code that supports multiple runs of the executing code through front end calls.

setting up the registration for storing provenance data

Parameters

[in]	address	The address of the region
[in]	expected_application_magic_number	The expected value of the magic number that checks if the data was meant for this code
[in]	simulation_steps_pointer	Pointer to the number of simulation steps, to allow this to be updated when requested via SDP
[in]	infinite_steps_pointer	Pointer to the infinite steps flag, to allow this to be updated when requested via SDP
[in]	step_pointer	Pointer to the current step, to allow this to be updated when requested via SDP
[in]	sdp_packet_callback_priority	The priority to use for the SDP packet reception
[in]	dma_transfer_complete_priority	The priority to use for the DMA transfer complete callbacks or <= -2 to disable

Returns: True if the data was found, false otherwise

Definition at line 142 of file simulation.h.

◆ simulation_set_provenance_data_address()

void simulation_set_provenance_data_address ( address_t provenance_data_address )

Set the address of the data region where provenance data is to be stored.

Parameters

[in] provenance_data_address the address where provenance data should be stored

Definition at line 414 of file simulation.c.

◆ simulation_set_provenance_function()

void simulation_set_provenance_function	(	prov_callback_t	provenance_function,
		address_t	provenance_data_address
	)

Set an additional callback function to store extra provenance data.

Parameters

[in]	provenance_function	function to call for extra provenance data
[in]	provenance_data_address	the address where provenance data should be stored

Definition at line 418 of file simulation.c.

◆ simulation_set_exit_function()

void simulation_set_exit_function ( exit_callback_t exit_function )

Set an additional function to call before exiting the binary when running without a fixed duration of execution.

Parameters

[in] exit_function function to call when the host tells the simulation to exit. Executed before API exit.

Definition at line 425 of file simulation.c.

◆ simulation_set_start_function()

void simulation_set_start_function ( start_callback_t start_function )

Set an additional function to call before starting the binary.

Parameters

[in] start_function function to call when the host tells the simulation to start. Executed before "synchronisation".

Definition at line 429 of file simulation.c.

◆ simulation_handle_pause_resume()

void simulation_handle_pause_resume ( resume_callback_t callback )

cleans up the house keeping, falls into a sync state and handles the resetting up of states as required to resume. Note that following this function, the code should call simulation_ready_to_read (see later).

Parameters

[in] callback The function to call just before the simulation is resumed (to allow the resetting of the simulation)

Definition at line 113 of file simulation.c.

◆ simulation_exit()

void simulation_exit ( void )

a helper method for people not using the auto pause and resume functionality

Helper when not using the auto pause and resume functionality

Definition at line 127 of file simulation.c.

◆ simulation_sdp_callback_on()

bool simulation_sdp_callback_on	(	uint	sdp_port,
		callback_t	sdp_callback
	)

Registers an additional SDP callback on a given SDP port. This is required when using simulation_register_sdp_callback, as this will register its own SDP handler.

Parameters

[in]	sdp_port	The SDP port to use
[in]	sdp_callback	The callback to call when a packet is received

Returns: true if successful, false otherwise

Definition at line 323 of file simulation.c.

◆ simulation_sdp_callback_off()

void simulation_sdp_callback_off ( uint sdp_port )

disables SDP callbacks on the given port

Parameters

[in] sdp_port The SDP port to disable callbacks for

Definition at line 333 of file simulation.c.

◆ simulation_dma_transfer_done_callback_on()

bool simulation_dma_transfer_done_callback_on	(	uint	tag,
		callback_t	callback
	)

registers a DMA transfer callback to the simulation system

Parameters

[in]	tag	the DMA transfer tag to register against
[in]	callback	the callback to register for the given tag

Returns: true if successful, false otherwise

Definition at line 346 of file simulation.c.

◆ simulation_dma_transfer_done_callback_off()

void simulation_dma_transfer_done_callback_off ( uint tag )

turns off a registered callback for a given DMA transfer done tag

Parameters

[in] tag the DMA transfer tag to de-register

Definition at line 366 of file simulation.c.

◆ simulation_set_uses_timer()

void simulation_set_uses_timer ( bool sim_uses_timer )

set whether the simulation uses the timer. By default it will be assumed that simulations use the timer unless this function is called.

Parameters

[in] sim_uses_timer Whether the simulation uses the timer (true) or not (false)

Definition at line 433 of file simulation.c.

◆ simulation_set_sync_steps()

void simulation_set_sync_steps ( uint32_t n_steps )

sets the simulation to enter a synchronisation barrier repeatedly during the simulation. The synchronisation message must be sent from the host. Note simulation_is_finished() must be used each timestep to cause the pause to happen.

Parameters

[in] n_steps The number of steps of simulation between synchronisations

Definition at line 437 of file simulation.c.

◆ simulation_is_finished()

bool simulation_is_finished ( void )

determine if the simulation is finished. Will also pause the simulation for resynchronisation if requested (see simulation_set_sync_steps).

Returns: true if the simulation is finished, false if not.

Definition at line 444 of file simulation.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ simulation_config

◆ simulation_provenance

Macro Definition Documentation

◆ MAX_DMA_CALLBACK_TAG

Typedef Documentation

◆ exit_callback_t

Enumeration Type Documentation

◆ simulation_commands

Function Documentation

◆ simulation_initialise()

◆ simulation_steps_initialise()

◆ simulation_set_provenance_data_address()

◆ simulation_set_provenance_function()

◆ simulation_set_exit_function()

◆ simulation_set_start_function()

◆ simulation_handle_pause_resume()

◆ simulation_exit()

◆ simulation_sdp_callback_on()

◆ simulation_sdp_callback_off()

◆ simulation_dma_transfer_done_callback_on()

◆ simulation_dma_transfer_done_callback_off()

◆ simulation_set_uses_timer()

◆ simulation_set_sync_steps()

◆ simulation_is_finished()