SIM_call_python_function — call a Python named function
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
attr_value_t
SIM_call_python_function(const char *NOTNULL func, attr_value_t *NOTNULL args);
import simics
simics.SIM_call_python_function(...)
Calls the Python function named func with arguments in args, which must be a list.
The namespace searched for func is the same as the Simics commands @ and python use; i.e., the Python module __main__. You may want to use a module-relative name for func such as __builtin__.repr when calling functions not defined at the Simics command-line. This avoids calling any local redefinition of that function.
SimExc_Type Thrown if args is not list or cannot be converted to Python or if func is not callable or if the return value cannot be converted to an attr_value_t.
SimExc_Lookup Thrown if func does not exist.
SimExc_General Thrown if there was an error executing Python code.
SimExc_Break Thrown on user interrupt.
Return value of the Python function
Cell Context
SIM_call_python_module_function, SIM_pyfunref_import, SIM_pyfunref_call, SIM_pyfunref_free — call a Python function
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
attr_value_t
SIM_call_python_module_function(
const char *NOTNULL module, const char *func, unsigned nargs, ...);
pyfunref_t *
SIM_pyfunref_import(const char *NOTNULL module, const char *NOTNULL func);
attr_value_t
SIM_pyfunref_call(pyfunref_t *NOTNULL func, unsigned nargs, ...);
void
SIM_pyfunref_free(pyfunref_t *func);
The function SIM_pyfunref_import imports a function from a Python module. The function SIM_pyfunref_call calls a previously imported function. The function SIM_pyfunref_free disposes a function reference previously returned from SIM_pyfunref_import. SIM_call_python_module_function is a convenience function that does all three.
The SIM_call_python_module_function function is the easiest and most straightforward way to cover most use cases, but it can only be called from Global Context. If you need to call Python functions from Cell Context or Threaded Context, then you need to import the function in advance, typically when your module is loaded, using SIM_pyfunref_import. This allows you to call the Python function from Threaded Context using the SIM_pyfunref_call function.
The SIM_pyfunref_free function is provided for completeness; in most cases, python functions are imported by a Simics module upon load, and since Simics modules cannot be unloaded the function never needs to be disposed.
The functions SIM_pyfunref_import and SIM_call_python_module_function describe the Python function using two strings, module and func, where module is the fully qualified name of a Python module, and func is the name of a function within that module. Both strings can be dot-delimited, as in "importable.module" and "object.attr".
In the functions SIM_pyfunref_call and SIM_call_python_module_function, the positional arguments of the Python function are specified with a variable number of attr_value_t values, using the same varargs format as the SIM_make_attr_list function. The returned value of the Python function is converted to a value of attr_value_t type. The function arguments are automatically freed, whereas ownership of the return value is passed to the caller.
The called function needs to fulfill certain criteria:
attr_value_t type, such as bool, int, str, bytes, float, the value None, or nested lists thereof.attr_value_t.It is considered an error if any one of these is not fulfilled; if this happens, then an error message is printed in an intrusive manner, with a traceback if applicable, and an invalid attribute value is returned. There is no graceful way to handle errors.
If a Python function does not fulfill the above criteria, then the function should not be called directly by this function. Instead it can be wrapped in another function that does fulfill them, e.g. by translating exceptions into an explicit out-of-band return value, or by transforming arguments or the return value to a supported format.
| Function | Context |
|---|---|
SIM_call_python_module_function | Global Context |
SIM_pyfunref_call | Cell Context |
SIM_pyfunref_free | Threaded Context |
SIM_pyfunref_import | Global Context |
SIM_get_api_function, GET_API_FUNCTION, api_function_t — return an API function by name
#include <simics/device-api.h> // in C
// always available in DML
api_function_t
SIM_get_api_function(const char *function);
typedef void (*api_function_t)(void);
// not available in DML
GET_API_FUNCTION(v, f);
Looks up a C function in the Simics API based on its name and returns a pointer to it. Typically used to access a function added to the Simics API in an update release (minor version) while remaining binary compatible with older versions of Simics.
The pre-processor macro GET_API_FUNCTION provides wrapping of SIM_get_api_function for simpler type casting.
SIM_get_api_function is neither available nor needed in Python. Code examples showing how to access a new function in a backward compatible in Python are provided below.
A new function SIM_foo is introduced in the Simics release with build id 5234. Since older versions of Simics do not have this function, a module writer that wants to use it while remaining compatible with old Simics versions, can write the following:
GET_API_FUNCTION(tmp_SIM_foo, SIM_foo);
if (tmp_SIM_foo != nullptr)
tmp_SIM_foo(1);
else
// code for older versions
Once compatibility with versions before build id 5234 can be dropped, the code in the example is simply replaced with a direct call to SIM_foo.
In Python, one can check whether the function is present like this:
if hasattr(simics, 'SIM_foo'):
simics.SIM_foo(1)
else:
# code for older versions
Another alternative for Python code is to check the build id value:
if conf.sim.build_id >= 5234:
simics.SIM_foo(1)
else:
# code for older versions
Returns a pointer to the API function if it exists or zero.
Cell Context
SIM_get_batch_mode — return setting of the batch-mode
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
bool
SIM_get_batch_mode();
import simics
simics.SIM_get_batch_mode(...)
This function returns the current value of Simics’s batch-mode flag.
Cell Context
SIM_get_debugger — return the debugger object
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
conf_object_t *
SIM_get_debugger();
import simics
simics.SIM_get_debugger(...)
Returns the Simics Debugger. The returned object is the object which implements the Simics Debugger API. The debugger object is created if it does not already exist. Returns nullptr and signals an exception if the debugger could not be created.
Returns the debugger object
SimExc_General Thrown if the debugger could not be created.
Global Context
SIM_load_target — load Simics target from file
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
attr_value_t
SIM_load_target(const char *NOTNULL target,
const char *ns, attr_value_t presets,
attr_value_t cmdline_args);
import simics
simics.SIM_load_target(...)
Load the target target into Simics. This can either be a file name or a target name, as returned by the list-targets command.
This function is functionally equivalent to invoking the script by passing it as a command line argument or to running the script with the load-target or run-script command, with the local flag set.
The ns and presets arguments have the same semantics as namespace and presets arguments to the run-script command. Each preset can be specified either as a file path or as a preset name, as returned by list-presets.
The cmdline_args argument should be a list of 2-element lists of target parameters [name, value].
SimExc_Break Thrown if the script was interrupted by the user.
SimExc_General Thrown if the script was interrupted by an error.
SimExc_IOError Thrown if the target or a preset could not be found or opened.
Global Context
SIM_quit — quit Simics
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
void
SIM_quit(int exit_code);
import simics
simics.SIM_quit(...)
Quit Simics in an orderly fashion. The Simics process will return the value exit_code & 0xFF, since the exit(3) call from the C standard library is used (see its man page). See the Core_Clean_At_Exit and Core_At_Exit haps for ways to run user code when Simics exits. Callbacks for the Core_Clean_At_Exit hap will only run if SIM_quit is called from Global Context, while Core_At_Exit is always called.
Cell Context. Global Context if possible.
SIM_run_command — evaluate a CLI command
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
attr_value_t
SIM_run_command(const char *NOTNULL line);
import simics
simics.SIM_run_command(...)
Runs a CLI command and returns the value, if any, as an attr_value_t.
When called from C, the returned value should be deallocated using SIM_attr_free.
SimExc_General Thrown if there was an error executing the CLI command.
SimExc_Type Thrown if the return value could not be converted to an attr_value_t.
Global Context
SIM_run_command_file_params, SIM_run_command_file — read CLI commands from file
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
void
SIM_run_command_file_params(const char *NOTNULL file, bool local,
attr_value_t params);
void
SIM_run_command_file(const char *NOTNULL file, bool local);
import simics
simics.SIM_run_command_file_params(...)
simics.SIM_run_command_file(...)
Read and execute the script file file; i.e., execute each line in the file as if it was typed at the Simics prompt.
This function is functionally equivalent to invoking the script by passing it as a command line argument or to running the script with the run-command-file command.
If local is true, the script will run with its own copy of all global CLI variables. When the script has finished executing, the previous variable set is restored.
The params argument can be used to pass parameters to the script. It must be a list of name-value pairs of strings, for example, from Python it could be [["num_cores", "4"], ["memory_megs", "1024"]].
SimExc_Break Thrown if the script was interrupted by the user.
SimExc_General Thrown if the script was interrupted by an error.
SimExc_IOError Thrown if the script file could not be opened.
Global Context
SIM_run_python — run a Python expression
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
attr_value_t
SIM_run_python(const char *NOTNULL line);
import simics
simics.SIM_run_python(...)
SIM_run_python runs a Python expression or statement. The return value, if any, is converted to a Simics attribute value. If line is a statement, a NIL attribute is returned.
SimExc_General Thrown if there was an error executing Python code.
SimExc_Type Thrown if the return value could not be converted to an attr_value_t.
SimExc_Break Thrown on user interrupt.
Cell Context
SIM_shutdown — shutdown Simics
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
void
SIM_shutdown();
import simics
simics.SIM_shutdown(...)
Perform the same clean up as SIM_quit, but do not exit the process. After having called this function, no Simics API function can be called.
Cell Context. Global Context if possible.
SIM_source_python, SIM_source_python_in_module — execute Python source file
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
void
SIM_source_python(const char *NOTNULL file);
void
SIM_source_python_in_module(const char *NOTNULL file,
const char *NOTNULL module);
import simics
simics.SIM_source_python(...)
simics.SIM_source_python_in_module(...)
SIM_source_python executes Python from file in the global Python scope. SIM_source_python_in_module is similar but executes the file contents in a named Python module.
SimExc_General Thrown if there was an error executing Python code.
SimExc_IOError Thrown if there was an error opening the file.
SimExc_Break Thrown on user interrupt.
Global Context