Embedding Simics

Name

SIM_get_init_arg_string, SIM_get_init_arg_boolean — get an argument that the Simics core was initialized with

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

const char *
SIM_get_init_arg_string(const char *name, const char *default_value);

bool
SIM_get_init_arg_boolean(const char *name, bool default_value);

Python

import simics

simics.SIM_get_init_arg_string(...)
simics.SIM_get_init_arg_boolean(...)

Description

Returns the value of init argument name previously supplied to Simics using SIM_init_simulator2. Arguments are either strings (char *) or booleans (bool).

This function is only needed when directly embedding libsimics-common in another application, which is deprecated.

Return Value

The argument value or default_value if the argument was not supplied to SIM_init_simulator2 or if the argument value was nullptr.

Exceptions

SimExc_General Thrown if the argument is of the wrong type.

Execution Context

Global Context

See Also

SIM_init_simulator2

Name

SIM_init_command_line — initialize the Simics command line

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

void
SIM_init_command_line();

Python

import simics

simics.SIM_init_command_line(...)

Description

SIM_init_command_line initializes the Simics command line used when running from a Linux shell or the Windows Command Prompt.

This function must be called after the Simics Python module has been loaded and should only be called when embedding Simics in another application.

Exceptions

SimExc_General Thrown if the function already has been called once.

Execution Context

Global Context

See Also

SIM_main_loop

Name

SIM_init_environment — perform early initialization of the simulator

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

void
SIM_init_environment(char **NOTNULL argv,
                     bool handle_signals, bool allow_core_dumps);

Description

The SIM_init_environment function should be called as early as possible when Simics is embedded in another application, before any other Simics API function. It will initialize Simics dynamic memory handling VTMEM, set up signal handling and perform some other early initialization.

The argv argument is a nullptr terminated list of strings. It must not be nullptr. It must contain at least one element, which will be used as the program name. Often you can use the argv that main receives as the value of this argument.

If handle_signals is true, Simics will install its handler for Control-C, e.g. the SIGINT signal on Linux and ConsoleCtrlHandler on Windows. Set this value to false if the embedding application handles signals itself.

If allow_core_dumps is true, Simics will not install handlers for fatal signals but instead let the application crash possibly generating a core dump on Linux systems. If the argument is false, no core dump is generated and Simics will try to catch fatal signals and return control to the command line again.

This function is only needed when directly embedding libsimics-common in another application, which is deprecated.

Execution Context

Global Context

Name

SIM_init_simulator2 — perform initialization of the simulator

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

void
SIM_init_simulator2(init_arg_t *NOTNULL init_args);

Description

SIM_init_simulator2 initializes the simulator core and should only be called when embedding Simics in another application. It has to be called after SIM_init_environment but before using most other parts of the Simics API. The init_args argument is an array with init_arg_t structs, where the last entry has NULL in the name field.

Each entry in the init_args array contains an argument name and an associated value that is either a string or a boolean. Simics has a number of pre-defined arguments that are used to configure the simulator.

It is possible to provide additional arguments in the call to SIM_init_simulator2. Such arguments are ignored by Simics and assumed to be used-defined. Their values can be obtained using the SIM_get_init_arg_string and SIM_get_init_arg_boolean functions in the Simics API.

List of pre-defined parameters and their types:

Internal or deprecated:

This function is only needed when directly embedding libsimics-common in another application, which is deprecated.

Exceptions

None

Execution Context

Global Context

See Also

SIM_init_environment, SIM_get_init_arg_string, SIM_get_init_arg_boolean.

Name

SIM_main_loop — run the Simics main loop

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

void
SIM_main_loop();

Python

import simics

simics.SIM_main_loop(...)

Description

SIM_main_loop enters the main loop of Simics and never returns. It should only be called when embedding Simics in another application that wishes to transfer full control of the simulation to Simics.

The main loop waits for work requests to be posted by notifiers, SIM_thread_safe_callback and SIM_realtime_event. If the command line has been initialized it will be active as well.

If the embedding application do not wish to transfer the control to Simics while the simulation is not advancing should use the SIM_process_work or SIM_process_pending_work to make sure that Simics can process any pending idle work.

Exceptions

SimExc_General Thrown if the function is called recursively.

Execution Context

Global Context

See Also

SIM_init_command_line, SIM_realtime_event, SIM_thread_safe_callback, SIM_process_work

Name

SIM_process_work, SIM_process_pending_work — run the Simics main loop

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

int
SIM_process_work(int (*done)(lang_void *done_data), lang_void *done_data);

int
SIM_process_pending_work();

Python

import simics

simics.SIM_process_work(...)
simics.SIM_process_pending_work(...)

Description

SIM_process_work and SIM_process_pending_work processes work posted by SIM_register_work, SIM_thread_safe_callback and SIM_realtime_event and related functions to be run in Global Context. They do not process work posted with run_in_thread set. Such work is processed in worker threads.

These process work functions are typically called when embedding Simics in another application to allow periodic and asynchronous Simics work to run while the simulation is not advancing. They can also be used as part of running the simulation to wait for events coming from external sources.

SIM_process_pending_work runs all work that has been queued up since the last call and returns immediately after.

SIM_process_work is similar but waits for new work to arrive. Each time all work that has been queued up has been processed the supplied done callback, which must be non-NULL, is called with done_data as its only argument. A return value of 1 tells SIM_process_work to stop processing work and return control to the caller again while 0 tells it to continue.

The SIM_process_work functions return -1 if the user has pressed the interrupt key before or while they were running, provided that the simulator core was initialized to catch signals. Otherwise the return value is 0. The function checks for user interrupt at the same time as it checks the done predicate and only if such a predicate is provided.

Execution Context

Global Context

See Also

SIM_main_loop, SIM_realtime_event, SIM_thread_safe_callback

Name

SIM_set_frontend_context — register a stack context buffer for Simics to longjmp back to

Synopsis

C and DML

#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML

void
SIM_set_frontend_context(void *context);

Description

When Simics encounters a fatal error that it cannot handle, it uses longjmp() to give control back to the main loop. The longjmp destination depends on the stack context buffer registered by the embedding application using SIM_set_frontend_context. The main loop run by SIM_main_loop already sets up the stack context. You only need to set up the stack context manually if you write your own main loop.

A stack context buffer is created by calling sigsetjmp() on Linux and setjmp() on Windows.

Execution Context

Global Context

See Also

SIM_main_loop, SIM_process_work