simulation.c File Reference

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>

Go to the source code of this file.

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.

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 77 of file simulation.c.

execute_provenance_storage()

static void execute_provenance_storage ( void  )

static

Run the provenance data storage.

Definition at line 94 of file simulation.c.

simulation_run()

void simulation_run

(

void

)

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

Definition at line 105 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 110 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 124 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 128 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 134 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 149 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 162 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 171 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 184 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 285 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 296 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 306 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 313 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 319 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 339 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:

1. 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;
2. setting the simulation SDP port code that supports multiple runs of the executing code through front end calls.
3. 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 343 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 387 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 391 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 398 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 402 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 406 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 410 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 417 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.