implementation of simulation.h More...

#include "simulation.h"
#include <stdbool.h>
#include <debug.h>
#include <spin1_api_params.h>
#include <spin1_api.h>
#include <wfi.h>

Functions
uint	resume_wait (void)
	Indicate whether the SYNC signal has been received.

static void *	simulation_store_provenance_data (void)
	Store basic provenance data.

static void	execute_provenance_storage (void)
	Run the provenance data storage.

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

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)
	Exit the application.

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.

static void	send_ok_response (sdp_msg_t *msg)
	Send an OK response to the host when a command message is received.

static void	wait_before_run (bool reset_event)
	wait for a signal before running

static void	synchronise_start (uint unused0, uint unused1)
	Callback when starting after synchronise.

static void	set_cpu_wait_state ()
	Set the CPU state depending on the event wait state.

static void	simulation_control_scp_callback (uint mailbox, uint port)
	Handle the new commands needed to resume the binary with a new runtime counter, as well as switching off the binary when it truly needs to be stopped.

static void	simulation_sdp_callback_handler (uint mailbox, uint port)
	handles the SDP callbacks interface.

bool	simulation_sdp_callback_on (uint sdp_port, callback_t 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

static void	simulation_dma_transfer_done_callback (uint unused, uint tag)
	handles the DMA transfer done callbacks interface.

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

bool	simulation_initialise (address_t address, uint32_t expected_app_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_done_callback_priority)
	initialises the simulation interface 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_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).

Variables
static uint32_t *	pointer_to_simulation_time
	the pointer to the simulation time used by application models

static uint32_t *	pointer_to_infinite_run
	the pointer to the flag for if it is a infinite run

static uint32_t *	pointer_to_current_time
	the pointer to the current simulation time

static prov_callback_t	stored_provenance_function = NULL
	the function call to run when extracting provenance data from the chip

static exit_callback_t	stored_exit_function = NULL
	the function call to run when received a exit command.

static resume_callback_t	stored_resume_function = NULL
	the function call to run just before resuming a simulation

static start_callback_t	stored_start_function = NULL
	the function call to run at the start of simulation

static struct simulation_provenance *	prov = NULL
	the region ID for storing provenance data from the chip

static callback_t	sdp_callback [NUM_SDP_PORTS]
	the list of SDP callbacks for ports

static callback_t	dma_complete_callbacks [MAX_DMA_CALLBACK_TAG]
	the list of DMA callbacks for DMA complete callbacks

static bool	uses_timer = true
	Whether the simulation uses the timer or not (default true)

static uint32_t	n_sync_steps
	The number of steps to run before synchronisation.

static uint32_t	next_sync_step
	The number simulation timestep at the next synchronisation.

static bool	simulation_paused = false
	Whether the simulation has been manually "paused".

Detailed Description

implementation of simulation.h

Definition in file simulation.c.

Function Documentation

◆ resume_wait()

uint resume_wait ( void )

extern

Indicate whether the SYNC signal has been received.

Returns: 0 (false) if not received and 1 (true) if received.

◆ simulation_store_provenance_data()

static void * simulation_store_provenance_data ( void )

static

Store basic provenance data.

Returns: the address after which new provenance data can be stored

gets access to the diagnostics object from SARK

Definition at line 80 of file simulation.c.

◆ execute_provenance_storage()

static void execute_provenance_storage ( void )

static

Run the provenance data storage.

Definition at line 97 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_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 )

Exit the application.

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

◆ send_ok_response()

static void send_ok_response ( sdp_msg_t * msg )

static

Send an OK response to the host when a command message is received.

Parameters

[in] msg the message object to send to the host.

Definition at line 137 of file simulation.c.

◆ wait_before_run()

static void wait_before_run ( bool reset_event )

inlinestatic

wait for a signal before running

Parameters

reset_event If true, the event is reset after the event has been received

Definition at line 152 of file simulation.c.

◆ synchronise_start()

static void synchronise_start	(	uint	unused0,
		uint	unused1
	)

static

Callback when starting after synchronise.

Parameters

unused0	unused
unused1	unused

Definition at line 165 of file simulation.c.

◆ set_cpu_wait_state()

static void set_cpu_wait_state ( )

inlinestatic

Set the CPU state depending on the event wait state.

Definition at line 174 of file simulation.c.

◆ simulation_control_scp_callback()

static void simulation_control_scp_callback	(	uint	mailbox,
		uint	port
	)

static

Handle the new commands needed to resume the binary with a new runtime counter, as well as switching off the binary when it truly needs to be stopped.

Parameters

[in]	mailbox	The mailbox containing the SDP packet received
[in]	port	The port on which the packet was received

Definition at line 187 of file simulation.c.

◆ simulation_sdp_callback_handler()

static void simulation_sdp_callback_handler	(	uint	mailbox,
		uint	port
	)

static

handles the SDP callbacks interface.

Parameters

[in,out]	mailbox	The pointer to the received message
[in]	port	What port the message was received on

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

static void simulation_dma_transfer_done_callback	(	uint	unused,
		uint	tag
	)

static

handles the DMA transfer done callbacks interface.

Parameters

[in]	unused	unused
[in]	tag	the tag of the DMA that completed

Definition at line 340 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_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_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_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.

Variable Documentation

◆ pointer_to_simulation_time

uint32_t* pointer_to_simulation_time

static

the pointer to the simulation time used by application models

Definition at line 37 of file simulation.c.

◆ pointer_to_infinite_run

uint32_t* pointer_to_infinite_run

static

the pointer to the flag for if it is a infinite run

Definition at line 40 of file simulation.c.

◆ pointer_to_current_time

uint32_t* pointer_to_current_time

static

the pointer to the current simulation time

Definition at line 43 of file simulation.c.

◆ stored_provenance_function

prov_callback_t stored_provenance_function = NULL

static

the function call to run when extracting provenance data from the chip

Definition at line 46 of file simulation.c.

◆ stored_exit_function

exit_callback_t stored_exit_function = NULL

static

the function call to run when received a exit command.

Definition at line 49 of file simulation.c.

◆ stored_resume_function

resume_callback_t stored_resume_function = NULL

static

the function call to run just before resuming a simulation

Definition at line 52 of file simulation.c.

◆ stored_start_function

start_callback_t stored_start_function = NULL

static

the function call to run at the start of simulation

Definition at line 55 of file simulation.c.

◆ prov

struct simulation_provenance* prov = NULL

static

the region ID for storing provenance data from the chip

Definition at line 58 of file simulation.c.

◆ sdp_callback

callback_t sdp_callback[NUM_SDP_PORTS]

static

the list of SDP callbacks for ports

Definition at line 61 of file simulation.c.

◆ dma_complete_callbacks

callback_t dma_complete_callbacks[MAX_DMA_CALLBACK_TAG]

static

the list of DMA callbacks for DMA complete callbacks

Definition at line 64 of file simulation.c.

◆ uses_timer

bool uses_timer = true

static

Whether the simulation uses the timer or not (default true)

Definition at line 67 of file simulation.c.

◆ n_sync_steps

uint32_t n_sync_steps

static

The number of steps to run before synchronisation.

Definition at line 70 of file simulation.c.

◆ next_sync_step

uint32_t next_sync_step

static

The number simulation timestep at the next synchronisation.

Definition at line 73 of file simulation.c.

◆ simulation_paused

bool simulation_paused = false

static

Whether the simulation has been manually "paused".

Definition at line 76 of file simulation.c.

Functions

Variables

Detailed Description

Function Documentation

◆ resume_wait()

◆ simulation_store_provenance_data()

◆ execute_provenance_storage()

◆ simulation_run()

◆ simulation_handle_pause_resume()

◆ simulation_exit()

◆ simulation_ready_to_read()

◆ send_ok_response()

◆ wait_before_run()

◆ synchronise_start()

◆ set_cpu_wait_state()

◆ simulation_control_scp_callback()

◆ simulation_sdp_callback_handler()

◆ simulation_sdp_callback_on()

◆ simulation_sdp_callback_off()

◆ simulation_dma_transfer_done_callback()

◆ simulation_dma_transfer_done_callback_on()

◆ simulation_dma_transfer_done_callback_off()

◆ simulation_initialise()

◆ simulation_set_provenance_data_address()

◆ simulation_set_provenance_function()

◆ simulation_set_exit_function()

◆ simulation_set_start_function()

◆ simulation_set_uses_timer()

◆ simulation_set_sync_steps()

◆ simulation_is_finished()

Variable Documentation

◆ pointer_to_simulation_time

◆ pointer_to_infinite_run

◆ pointer_to_current_time

◆ stored_provenance_function

◆ stored_exit_function

◆ stored_resume_function

◆ stored_start_function

◆ prov

◆ sdp_callback

◆ dma_complete_callbacks

◆ uses_timer

◆ n_sync_steps

◆ next_sync_step

◆ simulation_paused