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:

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:

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.

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.

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.

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

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).

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

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.

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

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

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

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.

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.

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).

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

◆ prov_callback_t

typedef void(* prov_callback_t) (address_t)

the definition of the callback used by provenance data functions

Definition at line 75 of file simulation.h.

◆ resume_callback_t

typedef void(* resume_callback_t) (void)

the definition of the callback used by pause and resume

Definition at line 78 of file simulation.h.

◆ 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.

◆ start_callback_t

typedef resume_callback_t start_callback_t

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

Definition at line 85 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_run()

void simulation_run ( void )

Starts the simulation running, returning when it is complete,.

Definition at line 108 of file simulation.c.

◆ simulation_ready_to_read()

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.

Definition at line 131 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

◆ prov_callback_t

◆ resume_callback_t

◆ exit_callback_t

◆ start_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_run()

◆ simulation_ready_to_read()

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