address_profiler — interface used to get statistics out of profilers
#include <simics/simulator-iface/address-profiler.h> // in C
import "simics/simulator-iface/address-profiler.dml"; // in DML
SIM_INTERFACE(address_profiler) {
addr_prof_iter_t *(*iter)(conf_object_t *prof_obj, unsigned view,
generic_address_t start,
generic_address_t stop);
uint64 (*sum)(conf_object_t *prof_obj, unsigned view,
generic_address_t start, generic_address_t end);
uint64 (*max)(conf_object_t *prof_obj, unsigned view,
generic_address_t start, generic_address_t end);
unsigned (*granularity_log2)(conf_object_t *prof_obj, unsigned view);
int (*address_bits)(conf_object_t *prof_obj, unsigned view);
int (*physical_addresses)(conf_object_t *prof_obj, unsigned view);
const char *(*description)(conf_object_t *prof_obj, unsigned view);
unsigned (*num_views)(conf_object_t *prof_obj);
};
#define ADDRESS_PROFILER_INTERFACE "address_profiler"
import simics
class simics.address_profiler_interface_t(iter=None, sum=None, max=None,
granularity_log2=None, address_bits=None, physical_addresses=None,
description=None, num_views=None)
Interface for getting statistics out of profilers. The target is some kind of profiler whose data can be meaningfully viewed as counts per address.
The function num_views returns the number k of different ways you can view the data of this object. The view selection parameter view to all other functions in the interface accepts values between 0 and k - 1.
description returns a short string that explains what the data means. physical_addresses returns true if the profiler works with physical addresses, or false if it uses virtual addresses. address_bits returns the number of bits in an address.
granularity_log2 returns the base 2 logarithm of the size, in bytes, of the address intervals that the counters are associated to. For example, if the data is instruction execution count and each instruction is 4 bytes long, one would expect the granularity to be at least 4 bytes since that is the smallest interval containing a whole instruction (but it might be more, if the profiler is less fine-grained for some reason). And for a 4-byte granularity, granularity_log2 would return 2.
sum returns the sum of all counters between start and stop, inclusive. max returns the maximum value of any counter in the range.
iter returns an address profile iterator that will visit all nonzero counters in the range precisely once, in some order. In C, you can use the functions SIM_iter_next, SIM_iter_addr and SIM_iter_free to operate the iterator. In Python, it works just like any other iterator, and returns (count, address) pairs. Note that you may not continue to use the iterator after the underlying address profiler has been modified.
Cell Context for all methods.
branch_arc_t, branch_arc_iter_t, branch_recorder_direction_t, branch_arc — interface for getting branch arcs out profilers
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
typedef struct {
uint64 addr_from;
uint64 addr_to;
int64 count;
branch_arc_type_t type;
} branch_arc_t;
typedef struct branch_arc_iter {
branch_arc_t *(*next)(struct branch_arc_iter *i);
void (*destroy)(struct branch_arc_iter *i);
} branch_arc_iter_t;
typedef enum {
BR_Direction_From,
BR_Direction_To
} branch_recorder_direction_t;
#include <simics/simulator-iface/address-profiler.h> // in C
import "simics/simulator-iface/address-profiler.dml"; // in DML
SIM_INTERFACE(branch_arc) {
branch_arc_iter_t *(*iter)(conf_object_t *prof_obj,
generic_address_t start,
generic_address_t stop,
branch_recorder_direction_t dir);
};
#define BRANCH_ARC_INTERFACE "branch_arc"
import simics
class simics.branch_arc_t
class simics.branch_arc_iter_t
simics.BR_Direction_From
simics.BR_Direction_To
class simics.branch_arc_interface_t(iter=None)
Interface for getting branch arcs out profilers. The target is some kind of profiler whose data can be meaningfully viewed as branch arcs (usually a branch profiler).
iter returns a branch arc iterator that will visit all branch arcs in the range precisely once, in order of selected address (to or from, selected with dir), other address and type. In Python, it works just like any other iterator, and returns (from, to, counter, type) tuples. Note that you may not continue to use the iterator after the underlying profiler has been modified.
branch_arc_type_t defines the branch types returned by a branch arc iterator.
Branch_Arc_BranchBranch_Arc_ExceptionBranch_Arc_Exception_ReturnCell Context for all methods.
break_string_cb_t, break_strings_v2 — interface used with console breakpoints
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
typedef int (*break_string_cb_t)(conf_object_t *obj,
const char *str, int64 break_id,
lang_void *arg);
SIM_INTERFACE(break_strings_v2) {
int64 (*add)(conf_object_t *NOTNULL obj, const char *str,
break_string_cb_t cb, lang_void *arg);
int64 (*add_single)(conf_object_t *NOTNULL obj, const char *str,
break_string_cb_t cb, lang_void *arg);
int64 (*add_regexp)(conf_object_t *NOTNULL obj, const char *str,
break_string_cb_t cb, lang_void *arg);
void (*remove)(conf_object_t *NOTNULL obj, int64 bp_id);
attr_value_t (*get_state)(conf_object_t *NOTNULL obj, int64 bp_id);
char *(*set_state)(conf_object_t *NOTNULL obj, int64 bp_id, attr_value_t data);
};
#define BREAK_STRINGS_V2_INTERFACE "break_strings_v2"
import simics
class simics.break_strings_v2_interface_t(add=None, add_single=None,
add_regexp=None, remove=None, get_state=None, set_state=None)
The break_strings_v2 interface facilitates management of string breakpoints. It is implemented by the text console and the graphics console (but will only function when in text mode).
The text console tries to match each break string on the stream of characters coming from the attached serial device, and if a match occurs, the given callback function will be called. If no callback is given, the simulation will be stopped. The graphics console behaves in the same way, but in this case the character stream is defined by what is sent to the console via the vga_text_update interface. Break strings only lives during a single Simics session, they are not checkpointed.
The add method registers a breakpoint string str, and returns a breakpoint ID, unique during the Simics session, which is also passed to cb when the breakpoint matches. If cb is not NULL, then this function will be called on breakpoint match, otherwise a match stops the simulation.
The add_single method is similar to add, but the breakpoint is removed automatically after the first match.
The add_regexp method is similar to add, but the given string is interpreted as a regular expression. The support regular expression syntax is that of the Hyperscan library.
The remove method deactivates a previously activated breakpoint.
The get_state and set_state functions can be used to serialize and deserialize string matchers: For instance, consider a breakpoint on the string ABC, where the characters A and B have already been matched. If you call get_state to retrieve the current state, then you can later call set_state with this state on any active breakpoint that waits for ABC, which will put that breakpoint in a state where its callback is triggered by the character C.
The get_state function returns an attribute value of data kind. It is only allowed to call set_state with a value returned by get_state, for a breakpoint waiting for the same string or regexp. The set_state function returns NULL on success, and an error message if the state cannot be restored. The caller is responsible for deallocating the error message using MM_FREE.
The methods get_state and set_state were both added in version 6.0.250 of the Simics Base package; any code that uses it will break if used with older base packages.
The break_string_cb_t callback function type is used by the string breakpoint system, called when the associated string breakpoint has matched. The obj parameter is the console where the breakpoint matched, str is the break string that matched, break_id is the associated breakpoint id, returned by the add or add_single method in the interface, and arg is the callback data passed to that method. The return value is ignored.
Global Context
breakpoint_manager — internal interface used by the breakpoint manager
#include <simics/simulator-iface/breakpoint-manager.h> // in C
import "simics/simulator-iface/breakpoint-manager.dml"; // in DML
SIM_INTERFACE(breakpoint_manager) {
/* Return a list of the breakpoint ids of all breakpoints. */
attr_value_t (*list_breakpoints)(conf_object_t *NOTNULL mgr);
void (*delete_breakpoint)(conf_object_t *NOTNULL mgr, uint64 id);
/* Return a dictionary with the properties for a specific breakpoint */
attr_value_t (*get_properties)(conf_object_t *NOTNULL mgr, uint64 id);
bool (*set_enabled)(conf_object_t *NOTNULL mgr,
uint64 id, bool enabled);
bool (*set_temporary)(conf_object_t *NOTNULL mgr, uint64 id,
bool temporary);
bool (*set_ignore_count)(conf_object_t *NOTNULL mgr, uint64 id,
uint64 ignore_count);
};
#define BREAKPOINT_MANAGER_INTERFACE "breakpoint_manager"
import simics
class simics.breakpoint_manager_interface_t(list_breakpoints=None,
delete_breakpoint=None, get_properties=None, set_enabled=None,
set_temporary=None, set_ignore_count=None)
An internal interface used by the breakpoint manager. Can be changed at any time.
Internal.
breakpoint_type — interface that allows implementing a custom breakpoint type
#include <simics/simulator-iface/breakpoint-manager.h> // in C
import "simics/simulator-iface/breakpoint-manager.dml"; // in DML
SIM_INTERFACE(breakpoint_type) {
/* Returns false if type is already registered. */
bool (*register_type)(conf_object_t *NOTNULL mgr,
const char *NOTNULL name,
conf_object_t *NOTNULL provider,
/* CLI command arguments as a list */
attr_value_t args,
/* Class and/or iface for command */
const char *cls,
const char *iface,
/* 8-element list with short and long
command help texts */
attr_value_t docs,
/* Is an object required
(or can it default to something) */
bool object_required,
/* Should breakpoints be temporary by default? */
bool temporary_default,
/* Set to true to allow all objects in 'object' argument */
bool recursive);
/* Notify manager that breakpoint has triggered, given ID returned by
add_bp. Returns true if simulation was stopped or otherwise the
breakpoint action happened. Optionally provide trigger object and
message, used if the simulation is stopped. */
bool (*trigger)(conf_object_t *NOTNULL mgr,
conf_object_t *NOTNULL provider, uint64 bp_id,
conf_object_t *trigger, const char *msg);
/* Return provider ID from breakpoint manager ID. */
uint64 (*get_break_id)(conf_object_t *NOTNULL mgr, uint64 bm_id);
uint64 (*get_manager_id)(conf_object_t *NOTNULL mgr,
conf_object_t *NOTNULL provider, uint64 bp_id);
};
#define BREAKPOINT_TYPE_INTERFACE "breakpoint_type"
import simics
class simics.breakpoint_type_interface_t(register_type=None, trigger=None,
get_break_id=None, get_manager_id=None)
The breakpoint_type interface is implemented by the breakpoint manager and facilitates registering breakpoint types.
This interface is currently a tech preview and can be changed at any time.
The register_type method registers a breakpoint type and creates CLI commands for this type. The name parameter should be the unique name for the type, which is also used in the names of any commands registered on interfaces or class. The provider parameter should be the provider object, which must implement the breakpoint_type_provider interface.
The commands break, run-until, wait-for and trace are registered on the provider class. If cls or iface are non-NULL, commands are also registered on that class or interface. These commands are bp-break-{name}, bp-run-until-{name}, bp-wait-for-{name} and bp-trace-{name}, where {name} is the name parameter.
The cls and iface parameters cannot both be non-NULL.
The args parameter is a list that defines the CLI command arguments. It should be a list of lists where each inner list contains the name of the cli.Arg_type subclass, such as str_t, flag_t etc, and then all parameters to its constructor (including values for parameters that have default values).
The docs parameter should be an 8-element list with short and long command documentation texts for the four commands break, run-until, wait-for and trace.
The object_required parameter indicates if the commands registered on the provider class (as opposed to the commands on the class or interface) should require an object (or if the command can use a default object). Note that there will only be an object parameter if cls or iface are non-NULL.
The temporary_default parameter indicates if the breakpoints of this type should be temporary by default. This also results in the generated break command not having a -once flag.
Setting recursive to true will append a ‘-recursive’ flag to both global and object commands, and for the global command, the ‘object’ argument will have no specified class or iface.
The trigger method must be called by the provider every time a breakpoint triggers, both breakpoints added with register_bp method and those added with add_bp method of the breakpoint_type_provider interface.
Global Context
breakpoint_type_provider — interface implemented by breakpoint providers
#include <simics/simulator-iface/breakpoint-manager.h> // in C
import "simics/simulator-iface/breakpoint-manager.dml"; // in DML
SIM_INTERFACE(breakpoint_type_provider) {
/* Register breakpoint in manager.
Return breakpoint manager ID, or 0 on error. */
uint64 (*register_bp)(conf_object_t *NOTNULL obj, uint64 bp_id);
/* Add breakpoint and return provider specific ID, or 0 on error. */
uint64 (*add_bp)(conf_object_t *NOTNULL obj,
int flags, attr_value_t data);
/* Remove breakpoint, given ID returned by add_bp. */
void (*remove_bp)(conf_object_t *NOTNULL obj, uint64 bp_id);
/* Return trace message, given ID returned by add_bp. */
char *(*trace_msg)(conf_object_t *NOTNULL obj, uint64 bp_id);
/* Message returned by break command, given ID returned by add_bp. */
char *(*break_msg)(conf_object_t *NOTNULL obj, uint64 bp_id);
/* Script branch wait message, given ID returned by add_bp. */
char *(*wait_msg)(conf_object_t *NOTNULL obj, uint64 bp_id);
/* Optional return value from wait-for and run-until commands,
given ID returned by add_bp. */
attr_value_t (*break_data)(conf_object_t *NOTNULL obj, uint64 bp_id);
/* Return possible values for command argument.
Optional unless expanders used. */
attr_value_t (*values)(conf_object_t *NOTNULL obj,
const char *arg, attr_value_t prev_args);
/* Optional trace output function. The default is to log on the
provider with level 1 and group 0. */
void (*trace)(conf_object_t *NOTNULL obj, const char *msg);
};
#define BREAKPOINT_TYPE_PROVIDER_INTERFACE "breakpoint_type_provider"
import simics
class simics.breakpoint_type_provider_interface_t(register_bp=None, add_bp=None,
remove_bp=None, trace_msg=None, break_msg=None, wait_msg=None,
break_data=None, values=None, trace=None)
The breakpoint_type_provider interface should be implemented by objects that wish to act as breakpoint type providers towards the breakpoint manager. An object that is passed to the breakpoint manager via the register_type method in the breakpoint_type interface must implement breakpoint_type_provider.
This interface is currently a tech preview and can be changed at any time.
The register_bp and add_bp methods receives the command arguments, corresponding to what the breakpoint manager received in the register_type. The register_bp method should set up a breakpoint, register it with the breakpoint manager via the breakpoint_registration interface, and return the breakpoint manager ID for that breakpoint. The add_bp method should set up an internal breakpoint, which is not registered with the breakpoint manager, and return a provider-specific ID for this breakpoint. The breakpoint manager will use this ID to remove the breakpoint via the remove_bp method, and this ID should also be used when calling the trigger method in the breakpoint_type interface.
The register_bp and add_bp methods should return 0 to indicate an error in setting up the breakpoint.
The break_msg method should return the message that should be printed by the bp.break command after the breakpoint is set up. It receives the breakpoint manager ID for the breakpoint.
The trace_msg method should return the message that should be printed when an (internal) trace breakpoint has hit. It receives the provider specific ID for the breakpoint.
The wait_msg method should return the message that is attached to the script branch while waiting for a breakpoint to hit (displayed by e.g. list-script-branches). It receives the provider specific ID for the breakpoint.
The optional method break_data can be implemented to make the wait-for and run-until commands return something. It receives the provider specific ID for the breakpoint.
The method values must be implemented if the provider has specified that CLI command expanders should be used, when registering the breakpoint type. Otherwise the method is not called by the breakpoint manager. It should return the possible values for the command argument arg, which will be one of the argument names used when registering the type. The parameter prev_args will be the list of preceding argument values.
The deleted method is typically optional. If implemented, it is called by the deleted function of the breakpoint_registration interface. Normally, breakpoint manager registered breakpoints are deleted using the function that was given to the register_breakpoint method of the breakpoint_registration interface, which is used by the bp.delete, but if the breakpoint can be removed by other means, then this method can be implemented.
Global Context
checkpoint — interface used with checkpointing
#include <simics/simulator-iface/checkpoint.h> // in C
import "simics/simulator-iface/checkpoint.dml"; // in DML
SIM_INTERFACE(checkpoint) {
void (*save)(conf_object_t *obj, const char *NOTNULL path);
void (*finish)(conf_object_t *obj, int success);
int (*has_persistent_data)(conf_object_t *obj);
void (*save_v2)(conf_object_t *obj, const char *NOTNULL path,
save_flags_t flags);
};
#define CHECKPOINT_INTERFACE "checkpoint"
import simics
class simics.checkpoint_interface_t(save=None, finish=None,
has_persistent_data=None, save_v2=None)
The save function in this interface is called when a checkpoint is saved, right before the attributes of an object is read. If defined, it should prepare the object for checkpointing, saving any state to path that is not directly included in the attributes. Default behavior is image to be compressed craff and config to be compressed too. Errors are signalled through exceptions.
The save_v2 function is same as save but take an extra parameter with the type of save_flags_t to control format of files in the checkpoint other than defaults.
The path argument may be the empty string, which indicates that the checkpoint bundle directory is the same as the current working directory while the checkpoint is being saved.
The finish function is called after the checkpoint has been saved, for all objects that save was called for. If success is nonzero, the checkpoint was saved successfully; otherwise there was a failure. This permits the object to clean up temporary data structures and files in either case. In particular, any files written to path in the save method must be removed in finish if success is zero.
The function has_persistent_data, if implemented, should return 0 if the object only has volatile attributes, 1 otherwise. This overrides Sim_Attr_Persistent on individual attributes.
Global Context for all methods.
con_input_code — interface for sending key events to target through a console
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(con_input_code) {
void (*input)(conf_object_t *NOTNULL obj, sim_key_t code, bool down);
};
#define CON_INPUT_CODE_INTERFACE "con_input_code"
import simics
class simics.con_input_code_interface_t(input=None)
The con_input_code interface facilitates sending simulated key events to the simulation. It is implemented by the graphics console.
Simulated key events are passed through the associated recorder object and then sent to the keyboard connected to the console.
The input method sends the key code, either a key press or a release, depending on the down parameter.
Global Context
con_input — interface for sending data to target through a console
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(con_input) {
void (*input_str)(conf_object_t *NOTNULL obj, const char *str);
void (*input_data)(conf_object_t *NOTNULL obj, bytes_t data);
};
#define CON_INPUT_INTERFACE "con_input"
import simics
class simics.con_input_interface_t(input_str=None, input_data=None)
The con_input interface facilitates sending simulated input to the target system. It is implemented by the text console.
Simulated input is passed through the associated recorder object and then sent to the serial device connected to the console. The console will not perform VT100 input handling or BS/DEL conversion.
The input_str method allows input of a NUL-terminated string. The input_data allows sending a buffer, which can include NUL characters.
Global Context
context_handler — interface for working with contexts
#include <simics/processor-api.h> // in C
import "simics/processor-api.dml"; // in DML
SIM_INTERFACE(context_handler) {
conf_object_t *(*get_current_context)(conf_object_t *obj);
int (*set_current_context)(conf_object_t *obj, conf_object_t *ctx);
};
#define CONTEXT_HANDLER_INTERFACE "context_handler"
import simics
class simics.context_handler_interface_t(get_current_context=None,
set_current_context=None)
This interface is not supported, and may change in the future.
Get and set current context. The set_current_context function returns zero if the passed object is not of the context class, otherwise one is returned.
Cell Context for all methods.
debug_notification — get notifications for debugger events
#include <simics/simulator-iface/debugger.h> // in C
import "simics/simulator-iface/debugger.dml"; // in DML
SIM_INTERFACE(debug_notification) {
attr_value_t (*notify_context_creation)(
conf_object_t *NOTNULL obj, const char *query,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id, bool updated),
cbdata_register_t data);
attr_value_t (*notify_context_destruction)(
conf_object_t *NOTNULL obj, const char *query,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id), cbdata_register_t data);
attr_value_t (*notify_location)(
conf_object_t *NOTNULL obj, const char *query,
const char *NOTNULL location, unsigned size, access_t access,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id, conf_object_t *cpu,
uint64 instruction_address, uint64 data_address,
unsigned size), cbdata_register_t data);
attr_value_t (*notify_address)(
conf_object_t *NOTNULL obj, const char *query, uint64 address,
unsigned size, access_t access, bool physical,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id, conf_object_t *cpu,
uint64 instruction_address, uint64 data_address,
unsigned size), cbdata_register_t data);
attr_value_t (*notify_line)(
conf_object_t *NOTNULL obj, const char *query,
const char *NOTNULL file, unsigned line, unsigned column,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id, conf_object_t *cpu,
uint64 instruction_address, uint64 data_address,
unsigned size), cbdata_register_t data);
attr_value_t (*notify_activated)(
conf_object_t *NOTNULL obj, const char *query,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id, conf_object_t *cpu),
cbdata_register_t data);
attr_value_t (*notify_deactivated)(
conf_object_t *NOTNULL obj, const char *query,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
const char *ctx_id, conf_object_t *cpu),
cbdata_register_t data);
attr_value_t (*notify_callbacks_done)(
conf_object_t *NOTNULL obj,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
attr_value_t (*cancel)(conf_object_t *NOTNULL obj,
debug_cancel_id_t cid);
};
#define DEBUG_NOTIFICATION_INTERFACE "debug_notification"
import simics
class simics.debug_notification_interface_t(notify_context_creation=None,
notify_context_destruction=None, notify_location=None,
notify_address=None, notify_line=None, notify_activated=None,
notify_deactivated=None, notify_callbacks_done=None, cancel=None)
This interface is used to get notifications from events in the debugger. Examples of events are when certain functions, addresses or code lines are hit.
In order to be able to get notifications for symbols, the symbol file containing the debug information must have been added using the debug_setup interface or in some other way.
All notifications take callback functions that are called when the debugger event occurs. The notifications will not stop the simulation, to do so SIM_break_simulation can be called in the callback.
For all functions that return an attr_value_t, that return value will consists of a list with two elements. The first element is an error code of debugger_error_t type. The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.
notify_context_creation provides a callback when a new context that matches the context query query is created or renamed. The callback will also be triggered when a context is renamed, so if the context query matches both the name before and after the context was renamed then there will be two creation callbacks for the same context. When the callback is triggered because of a rename the updated argument of the callback will be true, otherwise if it is triggered because a new context was created the updated argument will be false.
notify_context_destruction provides a callback when a context that matches the context query query is destroyed.
The callbacks for notify_context_creation and notify_context_destruction will contain an ID to the context that was created, updated or destroyed, ctx_id, the tcf_agent object obj and some custom data.
The
notify_context_creationandnotify_context_destructioncallbacks will only trigger for contexts that have state, this is most commonly the leaf nodes in an OS Awareness node tree.
notify_location will give a callback when a memory access of type access is done at the address specified by location, for contexts matching query. The size argument is used to specify the width of the symbol provided by location. For execution notifications a size of 1 is usually used. The maximum value of size is 0x7fffffff. Notifying on location will only work for global symbols. For symbols that are not global, no errors will be given, and no callback will be triggered.
notify_address will provide a callback when an address is hit with a certain access type for contexts matching query. The size argument specifies the width of the breakpoint for the notification, with a maximum value of 0x7fffffff. The notification can be set to notify on physical breakpoints instead of virtual, but for that to work a processor or memory space context must be covered by the query. For process related contexts physical should be false.
notify_line will provide a callback when a specific line and column in a specific source file for a context matching query is executed. The column argument can be set to 0 to not care about column.
The notification functions notify_location, notify_address and notify_line will all provide callbacks on the same format. They will pass the context ID, ctx_id, for which the access occurred. A processor, cpu, which did the access is provided. The instruction_address is the address of the instruction that performed the access. For execution callbacks the callback will occur before the instruction has run, but for read or write accesses the callback will occur after the instruction has run. The data_address will provide which data address was accesses, for execution accesses this is the same as instruction_address but for read or write accesses this is where the actual access was. And size specifies the actual size of the access that was made to trigger the notification, for execution this size is 1.
notify_activated and notify_deactivated are used to notify when a context, that matches the query, gets activated or deactivated. The callback for this will include which context, ctx_id, was (de)activated and on what processor, cpu.
For all notifications functions in this interface, on success, the returned value of a notification function will be a cancel ID which can be used to cancel the notification.
If several callbacks occur on the same cycle, then the order for which the callbacks are called is not determined. This means that a notify_activated callback for one processor can occur before a notify_deactivated callback on the same processor.
notify_callbacks_done will be called once all other callbacks that happen because of the same event are done. For example when a move to and a move from is done in the same step then this callback can be used to keep grouped notifications together that occurred at the same time. This will always be called after one or more callbacks have been called.
cancel is used to cancel a notification by providing it with a cancel ID, cid, that was returned from the notification function. When this goes well the returned value will be nil.
Errors specific to this function:
Debugger_Unknown_Id - The cancel ID, cid, is unknown.All callbacks except notify_location, notify_address, and notify_line, with execution access, will occur after the instruction triggering the callbacks has executed. For the callbacks specified here, when using execution access, the callback will occur before the instruction at that location, address or line has executed.
In order to get contexts for processes, OS Awareness with a properly configured tracker has to exist. A context will then be created for each OS Awareness node. Without any OS Awareness tracker enabled for the system, contexts will only be available for processors and some memory spaces. The
notify_activatedandnotify_deactivatedfunctions will only give callbacks when a tracker is used, because processor contexts are always active. More information about configuring and using OS Awareness and trackers can be found in theAnalyzer User's Guide.
For functions that take
queryas argument, having this set to nil will work the same way as for"*". A bad context query will result in aDebugger_Incorrect_Context_Queryerror.
Global Context for all methods.
debug_query — query the debugger for debug contexts
#include <simics/simulator-iface/debugger.h> // in C
import "simics/simulator-iface/debugger.dml"; // in DML
typedef enum {
Debugger_No_Error = 0,
Debugger_Not_Allowed_In_Execution_Context,
Debugger_Unknown_Context,
Debugger_Not_Supported_For_Context,
Debugger_Context_Does_Not_Have_State,
Debugger_Context_Is_Not_Active,
Debugger_Lookup_Failure,
Debugger_Failed_To_Get_Stack_Frame,
Debugger_Failed_To_Get_PC,
Debugger_Failed_To_Read,
Debugger_Failed_To_Write,
Debugger_Frame_Outside_Of_Known_Stack,
Debugger_Failed_To_Evaluate_Expression,
Debugger_Incorrect_Type,
Debugger_Incorrect_Size,
Debugger_Incorrect_Context_Query,
Debugger_Unknown_Id,
Debugger_Source_Not_Found,
Debugger_File_Not_Found,
Debugger_Unrecognized_File_Format,
Debugger_Unsupported_For_File_Format,
Debugger_Failed_To_Open_File,
Debugger_Not_Relocatable,
Debugger_Segment_Info_Missing,
Debugger_Section_Info_Missing,
Debugger_Segment_Not_Found,
Debugger_Section_Not_Found,
Debugger_Already_Running,
Debugger_Failed_To_Continue,
Debugger_No_Context_For_Object,
Debugger_Invalid_Path,
Debugger_Missing_Object,
Debugger_Unexpected_Error,
Debugger_Step_Interrupted,
} debugger_error_t;
SIM_INTERFACE(debug_query) {
attr_value_t (*matching_contexts)(conf_object_t *NOTNULL obj,
const char *query);
attr_value_t (*get_context_group)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*get_context_parent)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*get_context_children)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*query_for_context_group)(conf_object_t *NOTNULL obj,
const char *ctx_id);
attr_value_t (*query_for_context_id)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*query_for_context_tree)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*context_name)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*context_id_for_object)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL ctx_obj);
attr_value_t (*object_for_context)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*context_has_state)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*get_active_processor)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
};
#define DEBUG_QUERY_INTERFACE "debug_query"
import simics
simics.Debugger_Unknown_Id
simics.Debugger_Section_Info_Missing
simics.Debugger_Section_Not_Found
simics.Debugger_Invalid_Path
simics.Debugger_Already_Running
simics.Debugger_Context_Does_Not_Have_State
simics.Debugger_Incorrect_Context_Query
simics.Debugger_Failed_To_Continue
simics.Debugger_Not_Supported_For_Context
simics.Debugger_Segment_Not_Found
simics.Debugger_Unsupported_For_File_Format
simics.Debugger_Not_Allowed_In_Execution_Context
simics.Debugger_Incorrect_Type
simics.Debugger_Missing_Object
simics.Debugger_Unexpected_Error
simics.Debugger_Incorrect_Size
simics.Debugger_Unrecognized_File_Format
simics.Debugger_Unknown_Context
simics.Debugger_Failed_To_Evaluate_Expression
simics.Debugger_Source_Not_Found
simics.Debugger_Failed_To_Read
simics.Debugger_Frame_Outside_Of_Known_Stack
simics.Debugger_Not_Relocatable
simics.Debugger_No_Context_For_Object
simics.Debugger_Failed_To_Open_File
simics.Debugger_Failed_To_Get_PC
simics.Debugger_Lookup_Failure
simics.Debugger_Failed_To_Get_Stack_Frame
simics.Debugger_File_Not_Found
simics.Debugger_Context_Is_Not_Active
simics.Debugger_No_Error
simics.Debugger_Step_Interrupted
simics.Debugger_Segment_Info_Missing
simics.Debugger_Failed_To_Write
class simics.debug_query_interface_t(matching_contexts=None,
get_context_group=None, get_context_parent=None,
get_context_children=None, query_for_context_group=None,
query_for_context_id=None, query_for_context_tree=None,
context_name=None, context_id_for_object=None,
object_for_context=None, context_has_state=None,
get_active_processor=None)
This interface provides functions for querying the debugger for contexts and their information. Functions here will be used to find specific contexts or to create context-queries, that can be used with other functions in debugger interfaces.
Most functions in this interface take a Context ID, ctx_id, as argument. This ID is passed as an argument to most callback functions in the debug_notification interface and returned by some functions in this interface.
All functions return an attr_value_t consisting of a list with two elements. The first element is an error code of debugger_error_t type. The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.
matching_contexts returns a list of context IDs matching the specified context-query, query. The returned list can be empty if there are no matching contexts.
get_context_group returns a context ID for the context marked as the group leader for the specified context, ctx_id. As example in a Linux tracker the process node will be the group leader for all threads belonging to that process. A context that lacks a specific group leader will return itself.
get_context_parent returns an ID to the parent context for the specified context.
Errors specific to this function:
Debugger_Not_Supported_For_Context - The context does not have a parent.get_context_children returns a list of context IDs for the children of the specified context. This list can be empty if the context has no children.
query_for_context_group, query_for_context_id and query_for_context_tree will return context-queries which can be used for matching all contexts in a group, the context that matches an ID or contexts in the tree that starts with the specified context. The latter context-query will match the context itself plus all its child contexts, the children of those contexts and so on. The result of these functions should be used with functions that take a context-query as argument.
context_name returns the name of the specified context.
Errors specific to this function:
Debugger_Not_Supported_For_Context - If the he context lacks a name.context_id_for_object returns a context ID for the specified Simics object, ctx_obj, if that has an associated context. In general, processors and some memory spaces usually have contexts associated with them.
Errors specific to this function:
Debugger_No_Context_For_Object - The object does not have any associated context.context_has_state returns a boolean that tells whether the specified context has state or not. That a context has state will mean that callbacks in the debug_notification will trigger for this context. The contexts that have state are usually leaf nodes in the OS Awareness node tree or processor objects.
object_for_context is used to get a Simics object that matches the context for ctx_id, if such an object exists.
Errors specific to this function:
Debugger_Missing_Object - The context does not match a Simics object.get_active_processor is used check if a context is active and in that case return the Simics processor object that the node is active on.
Errors specific to this function:
Debugger_Context_Is_Not_Active - Context is not active.For functions that take
queryas argument, having this set to nil will work the same way as for"*". A bad context query will result in aDebugger_Incorrect_Context_Queryerror.
Global Context for all methods.
debug_setup — configure the debugger with symbol files and paths
#include <simics/simulator-iface/debugger.h> // in C
import "simics/simulator-iface/debugger.dml"; // in DML
typedef int64 debug_setup_id_t;
SIM_INTERFACE(debug_setup) {
attr_value_t (*add_symbol_file)(conf_object_t *NOTNULL obj,
const char *query,
const char *NOTNULL symbol_file,
uint64 address, bool absolute_address);
attr_value_t (*add_symbol_segment)(conf_object_t *NOTNULL obj,
const char *query,
const char *NOTNULL symbol_file,
unsigned segment, uint64 address,
bool absolute_address);
attr_value_t (*add_symbol_section)(conf_object_t *NOTNULL obj,
const char *query,
const char *NOTNULL symbol_file,
const char *NOTNULL section,
uint64 address,
bool absolute_address);
attr_value_t (*remove_symbol_file)(conf_object_t *NOTNULL obj,
debug_setup_id_t id);
void (*clear_symbol_files)(conf_object_t *NOTNULL obj);
attr_value_t (*symbol_files)(conf_object_t *NOTNULL obj);
attr_value_t (*symbol_files_for_ctx)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*list_all_mappings)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*add_path_map_entry)(conf_object_t *NOTNULL obj,
const char *query,
const char *NOTNULL source,
const char *NOTNULL dest);
attr_value_t (*remove_path_map_entry)(conf_object_t *NOTNULL obj,
debug_setup_id_t id);
void (*clear_path_map_entries)(conf_object_t *NOTNULL obj);
attr_value_t (*path_map_entries)(conf_object_t *NOTNULL obj);
attr_value_t (*path_map_entries_for_ctx)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*apply_path_map)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
const char *NOTNULL filename);
};
#define DEBUG_SETUP_INTERFACE "debug_setup"
import simics
class simics.debug_setup_interface_t(add_symbol_file=None,
add_symbol_segment=None, add_symbol_section=None,
remove_symbol_file=None, clear_symbol_files=None, symbol_files=None,
symbol_files_for_ctx=None, list_all_mappings=None,
add_path_map_entry=None, remove_path_map_entry=None,
clear_path_map_entries=None, path_map_entries=None,
path_map_entries_for_ctx=None, apply_path_map=None)
Functions in the debug_setup interfaces are used to provide the debugger with symbol files and paths. There are also functions for listing what symbol files and paths have been added.
For all functions that return an attr_value_t, that return value will consists of a list with two elements. The first element is an error code of debugger_error_t type. The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.
Upon success, all functions for adding symbols will return an id that can be used with remove_symbol_file.
add_symbol_file adds a symbol file, symbol_file, used for debugging contexts that match the context-query query. The address argument specifies the address that the file should be mapped to. If absolute_address is set then the given address will be the absolute address of the first relocatable segment and other segments will be added with their given offsets to that segment.
Errors specific to this function:
Debugger_Failed_To_Open_File - File cannot be opened.Debugger_Unrecognized_File_Format - The file format is not recognized.Debugger_Segment_Info_Missing - If an ELF file is being added, but no valid segments can be found.add_symbol_segment adds symbols from the specified segment of an ELF symbol file. Other arguments are the same as for add_symbol_file. The address of the segment is specified with the address argument. If absolute_address is set this address will be an absolute address otherwise it will be an offset to the address found in the symbol file for that segment.
Errors specific to this function:
Debugger_Segment_Not_Found - Segment not found when adding a segment.Debugger_Segment_Info_Missing - Segment information is missing or incomplete.Debugger_Not_Relocatable - The segment is not relocatable.Debugger_Unsupported_For_File_Format - File format is not ELF.add_symbol_section adds symbols from the specified section of an ELF symbol file. Other arguments are the same as for add_symbol_file. The address of the section is specified with the address argument. If absolute_address is set this address will be an absolute address otherwise it will be an offset to the address found in the symbol file for that section.
Errors specific to this function:
Debugger_Section_Not_Found - Section not found when adding a section.Debugger_Section_Info_Missing - Section information is missing or incomplete.Debugger_Not_Relocatable - The section is not relocatable.Debugger_Unsupported_For_File_Format - File format is not ELF.Adding the same symbol file, section or segment more than once might result in unexpected behavior and is not supported.
remove_symbol_file removes the debugger’s knowledge of symbols that was added with any of the functions for adding symbols. The id argument is the id returned from the add function.
Errors specific to this function:
Debugger_Unknown_Id - The id is unknown.clear_symbol_files removes the debugger’s knowledge about all symbol files added by add_symbol_file.
symbol_files lists all added symbol files. A dictionary, with id as key will be returned. An id is always bound to one query and one symbol file, but it can contain several memory maps. The listed id is the argument passed to remove_symbol_file. The dictionary values have the following format:
query (string) - The context query the symbol is valid for.relocation (uint64) - The relocation address provided when the symbol file was added.symbol-file (string) - The file containing the symbol information.memory-maps ([<dict>, ...]) - A list of memory maps that are added togheter as the same id, see format below:The dictionary describing a memory map has the following format:
address (uint64) - The address of the section in memory.size (uint64) - The section size in memory.flags (uint64) - Format specific flags describing the section.section (string) - The name of the section.file-offset (uint64) - Offset in symbol file for the section.file-size (uint64) - Size of the section in the symbol file.symbol_files_for_ctx is the same as symbol_files except that it only returns symbol files that are valid for the given context id, ctx_id.
list_all_mappings lists all symbol mappings for a certain context ctx_id. This will be all mappings from symbol files added by users plus any symbol mappings added elsewhere, from trackers for example. The returned value is a dictionary on the following format:
filename (string) - The file backing the memory map.query (string) - The query the map is valid for.address (uint64) - The map’s address in context memory.size (uint64) - The size of the map in memory.flags (uint64) - Read, write, and execute flags, bit 0 is set if readable, bit 1 if writeable and bit 2 if executable. If this value is 0 this is the same as if all flags are set.section-name (string) - The section name, or NIL.file-offset (int64) - Offset into the backing file.file-size (uint64) - Size of the map in the backing file.relocation (uint64) - The offset from the address in the symbol file to where the mappings is actually loaded in memory. This is not always present in the dictionary.Some other internal entries could possibly also be present in the dictionary.
add_path_map_entry adds a path math entry that maps a source file from the source in the symbol file to the actual destination, dest, where it is located on disk. The query argument specifies for which context- queries the mapping should apply. The returned id can be used with remove_path_map_entry to remove the added path map. The source path may not be empty or be just "." or "./".
Errors specific to this function:
Debugger_Invalid_Path - The source path is not valid.remove_path_map_entry removes an entry that was added with add_path_map_entry. The id is the value returned from the add function.
Errors specific to this function:
Debugger_Unknown_Id - The provided id is unknown.clear_path_map_entries removes all knowledge about all path map entries added with add_path_map_entry.
path_map_entries lists all path map entries that have been added with add_path_map_entry, that matches the given context id. If the context id is nil, then all path maps will be listed. The format of the entries in the returned list are dictionaries, with an id of type debug_setup_id_t as key:
query (string) - The context query the path map is valid for.source (string) - The source to translate from.destination (string) - The destination to translate to.path_map_entries_for_ctx is the same as path_map_entries except that it only lists path maps that are valid for the given context id, ctx_id.
apply_path_map applies any added path map to a file path, filename, for a given context with ID ctx_id. The path with the path map applied will be returned. The path map will only apply if the destination file exists and if the path given in filename does not, otherwise the provided file will be returned. The returned path will always contain forward slashes as path separator, regardless of what the host system uses, or if any path map was applied or not.
For functions that take
queryas argument, having this set to nil will work the same way as for"*". A bad context query will result in aDebugger_Incorrect_Context_Queryerror.
Global Context for all methods.
debug_step — perform stepping with the debugger
#include <simics/simulator-iface/debugger.h> // in C
import "simics/simulator-iface/debugger.dml"; // in DML
SIM_INTERFACE(debug_step) {
attr_value_t (*instruction_into)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*into)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*instruction_over)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*over)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*out)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*reverse_instruction_into)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*reverse_into)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*reverse_instruction_over)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*reverse_over)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*reverse_out)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
};
#define DEBUG_STEP_INTERFACE "debug_step"
import simics
class simics.debug_step_interface_t(instruction_into=None, into=None,
instruction_over=None, over=None, out=None,
reverse_instruction_into=None, reverse_into=None,
reverse_instruction_over=None, reverse_over=None, reverse_out=None)
This interface is used to perform stepping with the debugger, on a specified debug context.
All functions return an attr_value_t consisting of a list with two elements. The first element is an error code of debugger_error_t type. The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.
instruction_into and instruction_over runs one step forward for the specified context. instruction_into will enter subroutine calls while instruction_over will step over subroutine calls.
into and over will run one source line forward for the specified context. into will enter function calls while over will skip over functions.
out will run until the currently active function returns.
All function take a context ID, ctx_id, as argument. This context ID is passed as an argument to callbacks for functions in the debug_notification interface. The context, that is passed to functions in this interface, has to have state (see context_has_state in the debug_query interface) otherwise a Debugger_Context_Does_Not_Have_State error will be returned.
Calling functions in this interface can only be done when simulation is stopped, otherwise a Debugger_Already_Running error will be returned.
For all functions in this interface, if another stop reason occurs before a function finishes the simulation will stop at that point instead.
Stepping for a context that is not active will run until that context becomes active and then take the step.
Global Context for all methods.
debug_symbol_file — for symbol file operations
#include <simics/simulator-iface/debugger.h> // in C
import "simics/simulator-iface/debugger.dml"; // in DML
SIM_INTERFACE(debug_symbol_file) {
attr_value_t (*open_symbol_file)(conf_object_t *NOTNULL obj,
const char *NOTNULL filename,
uint64 address, bool absolute_address);
attr_value_t (*close_symbol_file)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*symbol_file_info)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*sections_info)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*segments_info)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*open_symbol_section)(conf_object_t *NOTNULL obj,
const char *NOTNULL filename,
const char *NOTNULL section,
uint64 address,
bool absolute_address);
};
#define DEBUG_SYMBOL_FILE_INTERFACE "debug_symbol_file"
import simics
class simics.debug_symbol_file_interface_t(open_symbol_file=None,
close_symbol_file=None, symbol_file_info=None, sections_info=None,
segments_info=None, open_symbol_section=None)
This interface has functions for operating directly on symbol files, instead of using contexts related to processes or processors. Files opened with this interface can be used together with functions in the debug_symbol interface that do not require any stack or location information. There are also functions for getting information about the symbol file, such as listing sections or segments.
All functions return an attr_value_t consisting of a list with two elements. The first element is an error code of debugger_error_t type. The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.
All function but open_symbol_file has to act on a context id, ctx_id, that has been returned by open_symbol_file, otherwise a Debugger_Not_Supported_For_Context error will be returned.
open_symbol_file opens a symbol file, specified by the filename argument, as a context so that this can be used with many of the symbol lookup functions in the debug_symbol interface. The address is the offset for which to load the symbol file if absolute_address is false. If absolute_address is true, address will instead be the absolute address to load the symbol file on. The returned value will be a context id that can be used as argument where a ctx_id is required. Functions that take a stack frame can only be accessed with no stack (value -1) when used with a symbol file context. Files that read or write memory cannot be used.
Errors specific to this function:
Debugger_Unrecognized_File_Format - The file format of the file is not ELF or PE.Debugger_Unsupported_For_File_Format - If the symbol file is of PE format then the address cannot be 0 as the internal handling does not support that.open_symbol_section opens a symbol file in the same way as open_symbol_file, but only adds symbols from the specified section. Other arguments and return value are as for open_symbol_file. The symbol section is closed using close_symbol_file. This method can only handle ELF binaries. In addition to errors reported by open_symbol_file this function can report Debugger_Section_Not_Found if the section cannot be found.
close_symbol_file closes a symbol file that was opened with open_symbol_file. The ctx_id should be the context id returned from that function. The returned value will just be nil when this goes well.
symbol_file_info returns a list containing a string describing the file format and a dictionary with information about the file. The ctx_id argument should be the context id returned from the open_symbol_file. The returned information depends on which file format the file has. For ELF files the string is “ELF” and the returned entries are:
big-endian (uint64) - Set to 1 if the binary is built for big endian, otherwise 0.elf-machine-id (uint64) - The ELF machine identifier number (e_machine) in the ELF header. This is usually prefixed with EM_ in headers. For example EM_386 = 3 and EM_X86_64 = 62.For PE files the string is “PE” and the returned entries are:
image-size (uint64) - The size of the PE image in memory.image-base (uint64) - The recommended address for the image to be loaded at.Both PE and ELF files will include the following entries:
entry-address (uint64) - The program counter for where the execution in the file should begin.file-size (uint64) - The file size in bytes.machine (string) - The type of machine the binary is built for, for example "X86-64", "X86" or "ARM".address-width (uint64) - The address width the file was built for, should be 32 or 64, but 0 specifies unknown.sections_info provides information about the sections in the symbol file. The ctx_id must be an id for a file opened with open_symbol_file or open_symbol_section in this interface. The returned result is a list with two elements, the first a string specifying the format of the file, “ELF” or “PE”, and the second a list of dictionaries where each dictionary contains information about the section. If an id from open_symbol_section is used then only the opened section will be included in the list. The following keys exist in the dictionary:
name (string) - The name of the section. This key could potentially be left out if the sections does not have a name.address (uint64) - The address in memory.offset (uint64) - The offset in the file.size (uint64) - The section size in the file image.executable (boolean) - A boolean telling if the section is executable or not.index (uint64) - Only available for ELF files. The section index.flags (uint64) - Only available for ELF files. The value of sh_flags in the ELF section header.characteristics (uint64) - Only available for PE files. The value of Characteristics in the PE section IMAGE_SECTION_HEADER structure.segments_info provides information about the segments in the symbol file, this is only supported for ELF. The ctx_id must be an id for a file opened with open_symbol_file in this interface. The returned result is a list where each entry represent a segment. Each entry is in turn a dictionary with the following keys:
address (uint64) - Virtual address in memory.size (uint64) - The segment size in memory, specified in bytes.offset (uint64) - Offset into the segment location on file.flags (uint64) - Flags, depending on segment type, corresponds to p_flags in the ELF program header table.type (uint64) - The type of the segment, corresponds to p_type in the ELF program header table.physical-address (uint64) - Physical address in memory, if applicable.file-size (uint64) - The size of the segment in file.sections ([string,...]) - A list of sections included in the segment, presented by the section name.Global Context for all methods.
debug_symbol — get symbol and source information
#include <simics/simulator-iface/debugger.h> // in C
import "simics/simulator-iface/debugger.dml"; // in DML
SIM_INTERFACE(debug_symbol) {
attr_value_t (*address_source)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address, uint64 size,
void (*cb)(cbdata_call_t data,
attr_value_t code_area),
cbdata_register_t data);
attr_value_t (*source_address)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
const char *NOTNULL filename,
uint32 line, uint32 column,
void (*cb)(cbdata_call_t data,
attr_value_t code_area),
cbdata_register_t data);
attr_value_t (*address_symbol)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address);
attr_value_t (*stack_depth)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*stack_frames)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id, int min,
int max);
attr_value_t (*local_variables)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id, int frame);
attr_value_t (*local_arguments)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id, int frame);
attr_value_t (*expression_value)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
int32 frame, uint64 address_scope,
const char *NOTNULL expr);
attr_value_t (*expression_type)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
int32 frame, uint64 address_scope,
const char *NOTNULL expr);
attr_value_t (*type_info)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address_scope,
const char *NOTNULL type);
attr_value_t (*type_to_string)(conf_object_t *NOTNULL obj,
attr_value_t type);
attr_value_t (*symbol_address)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id, int32 frame,
const char *NOTNULL symbol);
attr_value_t (*address_string)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address, int maxlen);
attr_value_t (*lvalue_write)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id, int32 frame,
const char *NOTNULL symbol,
attr_value_t value);
attr_value_t (*address_write)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address, attr_value_t value);
attr_value_t (*address_read)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id, uint64 address,
unsigned size);
attr_value_t (*struct_members)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address_scope,
const char *NOTNULL struct_name);
attr_value_t (*struct_field)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id,
uint64 address_scope,
const char *NOTNULL struct_name,
const char *NOTNULL field);
attr_value_t (*list_functions)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*list_global_variables)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
attr_value_t (*list_source_files)(conf_object_t *NOTNULL obj,
const char *NOTNULL ctx_id);
};
#define DEBUG_SYMBOL_INTERFACE "debug_symbol"
import simics
class simics.debug_symbol_interface_t(address_source=None, source_address=None,
address_symbol=None, stack_depth=None, stack_frames=None,
local_variables=None, local_arguments=None, expression_value=None,
expression_type=None, type_info=None, type_to_string=None,
symbol_address=None, address_string=None, lvalue_write=None,
address_write=None, address_read=None, struct_members=None,
struct_field=None, list_functions=None, list_global_variables=None,
list_source_files=None)
This interface contains functions for retrieving various symbol information for a debug context, ctx_id. There are also a few functions for updating symbol information.
Prior to using functions in this interface, symbol file(s) containing symbol information should have been added using the debug_setup interface, for a context-query that matches the context ID provided to the function here. Symbol files can also be added in other ways such as from a tracker or from Eclipse.
Some functions, that do read values or stack, can also be used directly with symbol files opened with the debug_symbol_file interface.
All functions in this interface take a context ID ctx_id as argument. This is the ID passed as an argument to debug_notification callbacks or returned from some debug_query interface functions.
All functions return an attr_value_t consisting of a list with two elements. The first element is an error code of debugger_error_t type. The second element depends on the first. If the first element is Debugger_No_Error, meaning that the function went well, then the second element will contain the expected return value that is specified per function below. If the first element is another error code, then the second element will be a string describing the error that occurred.
All addresses used in this interface are virtual addresses.
For functions that take frame as argument, providing frame = -1 means no frame. This can be used when finding symbols for functions or global variables. When using other frame than -1 the context has to be active, otherwise no frame will exists and a Debugger_Context_Is_Not_Active error will be returned. If the specified frame cannot be found, then error code Debugger_Frame_Outside_Of_Known_Stack will be returned.
Functions that handle stack can only be used with an active context, otherwise error code Debugger_Context_Is_Not_Active or Debugger_Context_Does_Not_Have_State will be returned depending on if the context has state or not.
address_source will provide callbacks, cb, with source information for the range specified by address and size. The range must not wrap around the 64-bit limit. Source information will be provided as code areas, which is the source information for a range of continuous addresses matching the same file and line. User data can be passed to the callback using the data argument and will be passed as the first argument in the callback. Each code area matching the range will get a callback with information about the code area in the code_area argument, which is a dictionary with the following elements:
filename (string) - File name of the source file where the specified address is found.start-line, end-line (int64) - Starting and ending lines in the source file for the address. end-line is inclusive so if the address just matches one source line start-line and end-line will be the same.start-column, end-column (int64) - Starting and ending columns on the line for address. If column information is not available in debug information the value will be 0. end-column is inclusive so the column is included for address.start-address, end-address (uint64) - Starting and ending addresses that correspond to the returned line and column information. end-address is inclusive so this matches the last byte of the last instruction of this code area. If the code area is empty then, then end-address will not be present. This can happen when asking for a line prior to the first executable line.Errors specific to this function:
Debugger_Source_Not_Found - There are no matching code areas.Debugger_Incorrect_Size - Incorrect size provided. The size cannot be zero and it cannot make the end address exceed 64 bits.Debugger_Lookup_Failure - Address lookup failure. Can occur if the address is not in the debug information or the lookup failed for some other reason. The error message explains more what went wrong.source_address will provide callbacks, with source information for the line specified by filename, line and column. The column argument will only be useful for binaries with column information in the debug information.
One call to this function will provide as many callbacks as there are code areas matching that source information. The code_area provided to the callback is a dictionary with the same format as for the callback from address_source.
Errors specific to this function:
Debugger_File_Not_Found - There is no matching source file, filename, in the debug information.Debugger_Source_Not_Found - The line or column is not found in the debug information.Debug_Lookup_Failure - Some problem with the lookup other than that file, line or column was not found. Error described in error message.For binaries without column information, a line is executable if the start-line in the callback matches the asked line.
For binaries with column information one can say that the line is executable if any code area can be found with start-line matching the asked line. When asking for a line and column and the start-line matches a previous line, but the end-line matches the asked line, then one should ask for the column just after end-column to see if the start-line of that code area matches the asked line and if it does then the asked line is considered executable.
stack_depth returns the current stack depth.
Errors specific to this function:
Debugger_Failed_To_Get_Stack_Frame - Failed to get stack frames.stack_frames returns a list of dictionaries with information about each frame. The executing frame is at position zero in the list. The elements of the stack frame dictionary are:
address (uint64) - For the executing frame this is the address of the program counter, for all other frames this is the address that the function will return to.source-file (string) - The source file for the frame. Can be nil if no matching file is found.source-line (uint64) - The source line in the file for the frame. Will be nil if source-file is nil.function-name (string) - The function that is executing in the frame. Can be nil if no function is found.Errors specific to this function:
Debugger_Failed_To_Get_Stack_Frame - If there are problems getting stack depth or getting frame info.Debugger_Failed_To_Read - If a register cannot be read for some frame.Debugger_Failed_To_Get_PC - If the program counter definition cannot be found for the context.local_variables returns a list of names for local variables in the specified frame.
local_arguments returns a list of names of arguments to the function in the specified frame.
Both local_variables and local_arguments can return an empty list if no local variables or arguments are found. If something goes wrong while looking up variables or arguments they will return a Debugger_Lookup_Failure with more information in the error string.
expression_value returns the value of an expression, expr, in the specified frame. See note about address_scope further down. The returned value will be of integer type if the expression is of integer type, including if it is an address. Floating-point types will be returned as such. If the expression is a structure, union, class or an array a list containing the elements of that type will be returned.
Errors specific to this function:
Debugger_Failed_To_Evaluate_Expression - The expression could not be evaluated, more information in the error message.expression_type returns the type of an expression, expr, in the specified frame. See note about address_scope further down. For most types the return value will be a string containing the type, for example "int", "double", "char" or "my_own_type_t".
For pointers the return value will be a list with "*" as the first argument followed by the type of the pointer, for example ["*", "void"] or ["*", ["*", "char"]].
For qualifiers (const, volatile or restrict) these will be added as an element to the list, such as ["const", "char"] or ["volatile", ["*", "int"]].
Functions are returned with a "()" string as the first element of a list, followed by the return type, followed by a list of arguments to the function. Example: ["*", ["()", "int", ["int", ["*", ["*", "char"]]]]] for a function of type int (*)(int, char **).
A struct or union will return a string "struct", followed by the struct name, if available, then followed by a list of lists containing the struct member type and name ["struct", "my_struct", [["int", "i"], ["float", "f"]]] as example. If the struct has been assigned a type with typedef then the output will be "typedef" followed by the name of the assigned type, then the list of members. An example: ["typedef", "mytype_t", [["int", "age"], [["*", "char"], "name"]]]. For unions the string "struct" will be replace with the string "union".
A bit field will return a list containing a string "bitfield" followed by the basic type of the bit field, followed by the size of the bit field. An example: ["bitfield", "int", 5] for a variable declared as int var:5.
For array types expression_type will return a list, ["[]", array size, array type], where the array type is of the same format as other types for this function. An example: ["[]", 10, "char"] for a variable declared as char x[10];.
Enumerations will be displayed as a list: ["enum", enum name, members]. The enum name is the declared name for the enumeration, if no such name exists this list field will be left out. The members field will contain a list of [name, value] lists for all the members of the enumeration. An example: ["enum", "my_enum", [["My_Val_0", 0], ["My_Val_1", 1]]].
There are some limitations for symbols from PE files that can depend on the version of
dbghelp.dll.
- Type defined types might get shown as the base type instead of the
"typedef"type.- Variables with a
constqualifier might be shown without that qualifier.- Members of anonymous structures within a base structure are shown as being part of the base structure.
Errors specific to this function:
Debugger_Failed_To_Evaluate_Expression - Could not evaluate the expression, more information in the error message.type_info returns information about what base type a type that has been added with typedef has. See note about address_scope further down. The returned value will be a list on the same format as for expression_value.
Errors specific to this function:
Debugger_Incorrect_Type - If the type asked for is not a valid type.Debugger_Lookup_Failure - Finding the symbol failed or the type of symbol cannot be retrieved. More information in the error string.type_to_string converts the return value from expression_type or type_info to a readable string and returns that.
Errors specific to this function:
Debugger_Incorrect_Type - The format of type is incorrect.symbol_address takes a frame and a symbol as arguments and returns a list of addresses that matches that symbol name. If a single symbol address is wanted near a provided instruction pointer then the expression_value function can be used with the expression set as &<symbol>.
Errors specific to this function:
Debugger_Lookup_Failure - The address for the symbol cannot be found. This can be because the symbol was not found or if evaluation failed. More information will be found in the error message.address_string returns the string at the specified address. The maxlen is used to specify the maximum length of a string to read from memory. If the string at address exceeds the given length the truncated string will be returned, and a terminating null character will be added if needed. A maxlen value of zero means no maximum string length.
Errors specific to this function:
Debugger_Failed_To_Read - Failed to read memory at address.lvalue_write writes a value to a symbol in the specified frame. The value can be of integer types or floating-point type if the type of the lvalue is of floating-point type. The returned value when the write goes well is nil.
Errors specific to this function:
Debugger_Incorrect_Type - The type of value is incorrect.Debugger_Failed_To_Evaluate_Expression - The provided symbol could not be found or evaluated as an expression.Debugger_Failed_To_Write - Failed to write to symbol.address_write writes an attr_value_t of data type, value, to the specified address. Returned value is nil when the write goes well.
Errors specific to this function:
Debugger_Incorrect_Type - The type of value is incorrect.Debugger_Failed_To_Write - The memory at address cannot be written to.address_read reads size number of bytes from the specified address. The read data is returned as an attr_value_t of data type.
Errors specific to this function:
Debugger_Failed_To_Read - The address cannot be read.struct_members returns a list of all members of a struct, struct_name. See note about address_scope further down. Each element of the returned list will be on the format [name, offset, size]. The size and offset elements are usually integers representing the offset into the struct and the size of the variable. If the struct member is a bit field then size will be a list on the format [base size, bits], where base size is the number of bytes for the declared base type and bits is the number of bits the declared for the bit field. For bit fields offset will be a list on the format [byte offset, bit offset], where byte offset is the offset of in bytes into the structure and bit offset is the offset in bits from the byte offset to where the bit field starts. If some member, size or offset cannot be retrieved then that element will be set as nil. This can for example occur if a struct member is an anonymous struct or union.
Errors specific to this function:
Debugger_Incorrect_Type - The provided symbol, struct_name, is not a structure.Debugger_Lookup_Failure - Failed to find the symbol or its type.struct_field returns a list of [offset, size] for a field of a given structure, struct_name. The offset and size are usually integers, but if the field is a bit field then the returned size and offset will be on the same format as for struct_members. See note about address_scope below.
This function can return the same error codes, for the same reasons, as the struct_members function.
The address_scope argument that is provided for several functions can be used to specify where to find the symbol if there are several matches for the provided symbol name or expression. This argument is used to provide an address that tells the function in which scope to search for the symbol. This is only taken in account when no frame (-1) is given as frame. This address can be an address that belongs to a loaded symbol file to prioritize finding symbols from that symbol file.
list_functions and list_global_variables lists all function or global variable symbols. The symbols included are the known symbols from added symbol files that match ctx_id, for example symbol files added using the debug_setup interface. The returned format is a list of dictionaries with the dictionary elements on the format:
symbol (string) - The name of the symbol.address (uint64) - The address in memory of the symbol.size (uint64) - The size of the symbol in memory.list_source_files lists all source files provided by the debug information of the symbol files for the given context.
Global Context for all methods.
disasm_instr_t, disassemble — interface used with disassembling
#include <simics/simulator-iface/disassemble.h> // in C
import "simics/simulator-iface/disassemble.dml"; // in DML
typedef struct {
int start; /* Where the instructions starts in the buffer */
int length; /* Length of instruction, or -1 if incomplete */
char *string; /* Disassembly string (allocated) */
} disasm_instr_t;
SIM_INTERFACE(disassemble) {
/* Set up new block to disassemble */
void (*init)(conf_object_t *obj, uint8 *buff,
int buff_len, uint64 address);
/* Disassemble the next instruction */
disasm_instr_t (*next)(conf_object_t *obj);
};
#define DISASSEMBLE_INTERFACE "disassemble"
The disassemble interface can be used to disassemble code from a buffer in memory. It is typically used to disassemble code for the host architecture independent of the target architecture implemented in a particular version of Simics.
init is used to initialize a new disassemble session. You should provide a buffer in buff, the buffer length in bytes in buff_len and the base address for this chunk in address. The address parameter is used to calculate program counter relative offsets (for branches and other program counter relative constructs).
next returns a structure with the next disassembled instruction. Repeated use of next will disassemble additional instructions.
Cell Context for all methods.
follower_agent — interface used with follower agents
#include <simics/simulator-iface/follower.h> // in C
// not available in DML
SIM_INTERFACE(follower_agent) {
void (*accept)(conf_object_t *obj, bytes_t msg);
void (*accept_async)(conf_object_t *obj, bytes_t msg);
};
#define FOLLOWER_AGENT_INTERFACE "follower_agent"
This interface is intended to be implemented by a follower agent to accept data from the follower.
The accept method delivers a deterministic message from the follower to the agent.
The accept_async method delivers an asynchronous (non-deterministic) message from the follower to the agent.
Cell Context for all methods.
gfx_break_cb_t, gbp_header_t, gfx_break — interface used with graphical breakpoints
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
typedef int (*gfx_break_cb_t)(conf_object_t *obj,
int64 break_id, lang_void *arg);
typedef struct {
uint32 magic;
uint32 format;
uint64 bytes;
uint32 minx;
uint32 miny;
uint32 maxx;
uint32 maxy;
} gbp_header_t;
SIM_INTERFACE(gfx_break) {
bool (*store)(conf_object_t *NOTNULL obj,
const char *file,
uint32 minx, uint32 miny, uint32 maxx, uint32 maxy);
int64 (*add)(conf_object_t *NOTNULL obj,
const char *file, const char *name,
bool oneshot, double interval,
gfx_break_cb_t cb, lang_void *arg);
bool (*remove)(conf_object_t *NOTNULL obj, int64 break_id);
int (*match)(conf_object_t *NOTNULL obj, const char *file);
gbp_header_t (*info)(conf_object_t *NOTNULL obj, const char *file);
bool (*export_png)(conf_object_t *NOTNULL obj, const char *file,
const char *png_file);
int64 (*add_bytes)(conf_object_t *NOTNULL obj,
bytes_t data, const char *name,
bool oneshot, double interval,
gfx_break_cb_t cb, lang_void *arg);
bytes_t (*store_bytes)(conf_object_t *NOTNULL obj,
uint32 minx, uint32 miny,
uint32 maxx, uint32 maxy);
int (*match_bytes)(conf_object_t *NOTNULL obj, bytes_t data);
};
#define GFX_BREAK_INTERFACE "gfx_break"
import simics
class simics.gfx_break_interface_t(store=None, add=None, remove=None, match=None,
info=None, export_png=None, add_bytes=None, store_bytes=None,
match_bytes=None)
The gfx_break interface facilitates management of graphical breakpoints. It is implemented by the graphics console.
A graphical breakpoint is defined by an image patch and a location on the screen, stored in a file using a bespoke format. Such a file can be created using the store method.
A breakpoint can then be activated using the add method. The console will check if the breakpoint matches the screen data every interval seconds in virtual time, using the clock that is associated to the console. Graphical breakpoints are therefore deterministic.
Note that the coordinates of the image patch is stored in the graphical breakpoint, and the breakpoint will only match on those coordinates.
The store method stores the specified rectangle on the screen in the given file. It returns false if the rectangle is invalid or on I/O error.
The add method activates a previously stored graphical breakpoint, and returns a breakpoint ID, which is also passed to cb when the breakpoint matches. The parameter name is the breakpoint name that will appear in log messages. If name is NULL then the file name is used. If oneshot is true, the breakpoint will be removed automatically after the first match. The interval parameter specifies how often the breakpoint is tested, in seconds of simulated time. If cb is not NULL, then this function will be called on breakpoint match, otherwise a match stops the simulation. If the breakpoint file cannot be loaded, the method returns -1.
The remove method deactivates a previously activated breakpoint.
The store and remove functions log error messages on failure.
The match method determines if a stored graphical breakpoint matches the current screen. It returns -1 if the breakpoint could not be loaded, 1 on match or 0 otherwise.
The info method returns the header of a stored graphical breakpoint, including the image patch coordinates. If the given file cannot be read or has invalid data, then a header containing all 0’s is returned.
The export_png method converts the image data in a graphical breakpoint file to PNG format.
The add_bytes method behaves as add but reads the breakpoint data from memory instead of a file.
The store_bytes method behaves as store but writes the breakpoint data to memory and returns it, instead of writing a file. On failure, errors are logged and the return value is an empty bytes_t.
The match_bytes method behaves as match but reads the breakpoint data from memory instead of a file.
The gbp_header_t type is returned by the info method. The fields magic and format are always GBP_MAGIC and GBP_FMT_V3_32, respectively. The field bytes is the size of the image data in the file, not including the header. The other fields specify the breakpoint image patch location on the screen.
The gfx_break_cb_t callback function type is used by the graphics breakpoint system and called when the associated graphical breakpoint has matched. The obj parameter is the graphics console where the breakpoint matched, break_id is the associated breakpoint id, returned by the add method in the interface, and arg is the callback data passed to that method.
| Function | Context |
|---|---|
| match | Cell Context |
| match_bytes | Cell Context |
| all other methods | Global Context |
host_serial — interface used to control connection to host serial port
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(host_serial) {
bool (*setup)(conf_object_t *NOTNULL obj, const char *name);
const char *(*name)(conf_object_t *NOTNULL obj);
void (*shutdown)(conf_object_t *NOTNULL obj);
};
#define HOST_SERIAL_INTERFACE "host_serial"
import simics
class simics.host_serial_interface_t(setup=None, name=None, shutdown=None)
The host_serial interface is used to control the text console host serial connection.
The setup method will set up a host serial connection on a pty (Linux) or COM port (Windows). On Linux, name can be NULL in which case a new pty is opened.
The name method returns the name of any opened pty or COM port, or NULL.
The shutdown closes any opened pty or COM port.
Global Context
instrumentation_connection — interface used with instrumentation tools
#include <simics/simulator-iface/instrumentation-tool.h> // in C
import "simics/simulator-iface/instrumentation-tool.dml"; // in DML
SIM_INTERFACE(instrumentation_connection) {
void (*enable)(conf_object_t *obj);
void (*disable)(conf_object_t *obj);
};
#define INSTRUMENTATION_CONNECTION_INTERFACE "instrumentation_connection"
import simics
class simics.instrumentation_connection_interface_t(enable=None, disable=None)
This interface is intended to be implemented by instrumentation connections using the instrumentation framework. This interface is used to request that instrumentation should be temporarily disabled and then re-enabled. That is, the connection should not collect any data when it is being disabled. How this is achieved is up to the tool, it could tell the provider to stop sending information, or simply throw away anything it sends. This interface can be used with high frequency while simulation is running, so it should be implemented with performance in mind.
Cell Context for all methods.
instrumentation_filter_master — interface used with instrumentation filter
#include <simics/simulator-iface/instrumentation-filter.h> // in C
import "simics/simulator-iface/instrumentation-filter.dml"; // in DML
SIM_INTERFACE(instrumentation_filter_master) {
void (*set_source_id)(conf_object_t *obj, unsigned source_id);
bool (*add_slave)(conf_object_t *obj, conf_object_t *slave,
conf_object_t *provider_obj);
void (*remove_slave)(conf_object_t *obj, conf_object_t *slave,
conf_object_t *provider_obj);
char *(*short_filter_config)(conf_object_t *obj);
};
#define INSTRUMENTATION_FILTER_MASTER_INTERFACE "instrumentation_filter_master"
import simics
class simics.instrumentation_filter_master_interface_t(set_source_id=None,
add_slave=None, remove_slave=None, short_filter_config=None)
This interface is intended to be implemented by instrumentation filters. Instrumentation filters should enable the associated slaves, which themselves are associated with instrumentation connections.
The set_source_id method supplies the filter with an unique source number for the filter. This function should only be called once, the filter needs to store this number so it can be used when calling the instrumentation_filter_slave interface methods.
The add_slave method informs the filter that it should enable or disable this slave too. The slave object should implement the instrumentation_filter_slave interface which should be used. The provider_obj parameter is the provider object that is located behind the slave and its connection. Depending on how the filter works, it may or may not make use of this parameter. For example, the process-filter might detect that the filtered process is now running on a particular processor, then it can enable this particular connection only, given that it can match the provider_obj with the processor currently running the tracked process.
The remove_slave method removes a slave from the filter, so it should not call it anymore.
The short_filter_config method should return a short textual description on how the filter is currently set up. This information is used in various print commands.
Global Context for all methods.
instrumentation_filter_slave — interface used with instrumentation filter
#include <simics/simulator-iface/instrumentation-filter.h> // in C
import "simics/simulator-iface/instrumentation-filter.dml"; // in DML
SIM_INTERFACE(instrumentation_filter_slave) {
void (*disable)(conf_object_t *obj, unsigned source_id);
void (*enable)(conf_object_t *obj, unsigned source_id);
};
#define INSTRUMENTATION_FILTER_SLAVE_INTERFACE "instrumentation_filter_slave"
import simics
class simics.instrumentation_filter_slave_interface_t(disable=None, enable=None)
This interface is implemented by the instrumentation_filter_aggregator class objects, here referred to as “aggregator”. The interface should be called by instrumentation filters to enable or disable a connection. The aggregator object is located between the filters and the connection, keeping the connections unaware of multiple filters that might be disabling them.
The disable method tells the aggregator that the unique source_id currently wants to disable the connection. As long as there is one source_id that is disabled, the connection is disabled. Only when all sources are enabled the connection is enabled.
Similarly, the enable method enables the connection. That is, the filter is now in a state when it thinks the connection should be enabled.
Cell Context for all methods.
instrumentation_filter_status — interface used with instrumentation filter
#include <simics/simulator-iface/instrumentation-filter.h> // in C
import "simics/simulator-iface/instrumentation-filter.dml"; // in DML
SIM_INTERFACE(instrumentation_filter_status) {
attr_value_t (*get_disabled_sources)(conf_object_t *obj);
};
#define INSTRUMENTATION_FILTER_STATUS_INTERFACE "instrumentation_filter_status"
import simics
class simics.instrumentation_filter_status_interface_t(get_disabled_sources=None)
This interface is implemented by the instrumentation_filter_aggregator class objects. This interface should only be used by Simics instrumentation framework itself. The get_disabled_sources method returns an attr_value_t list of integers representing the source_ids that currently causing the connection to be disabled.
Global Context for all methods.
instrumentation_tool — interface used with instrumentation tools
#include <simics/simulator-iface/instrumentation-tool.h> // in C
import "simics/simulator-iface/instrumentation-tool.dml"; // in DML
SIM_INTERFACE(instrumentation_tool) {
conf_object_t *(*connect)(
conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL provider,
attr_value_t args);
void (*disconnect)(
conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL conn_obj);
};
#define INSTRUMENTATION_TOOL_INTERFACE "instrumentation_tool"
import simics
class simics.instrumentation_tool_interface_t(connect=None, disconnect=None)
This interface is intended to be implemented by instrumentation tools using the instrumentation framework. The instrumentation framework handles setting up, controlling and removing the connection between providers and tools, but the actual communication is handled by instrumentation specific interfaces.
When a connection with a provider is being established, the connect method is called. The provider argument specifies the provider which should be connected. The args are tool specific arguments that can be used allowing the connection to be configured a certain way. The tool should create a new dedicated connection object, which register itself with the provider using the dedicated interface. The connection object created is returned by the connect function. If, for any reason, the tool cannot successfully connect to the provider, NULL should be returned to indicate failure.
If a connection should be removed, the disconnect method is called. The conn_obj argument is the connection object returned earlier in connect. It is up to the tool to delete the created object which should unregister itself from the provider.
Global Context for all methods.
leader_message — interface used with follower agents
#include <simics/simulator-iface/follower.h> // in C
// not available in DML
SIM_INTERFACE(leader_message) {
void (*send)(conf_object_t *obj,
follower_time_t time, uint64 skey, bytes_t msg);
void (*send_async)(conf_object_t *obj, bytes_t msg);
};
#define LEADER_MESSAGE_INTERFACE "leader_message"
This interface is implemented by the leader, and is used from a follower agent to send data to the follower.
The send method sends a deterministic message to the follower to be delivered at time. If several messages will be delivered at same time, an increasing skey determines the sort order.
The send_async method sends a non-deterministic (asynchronous) message to the follower to be delivered as soon as possible.
Cell Context for all methods.
osa_component — get information about OS awareness objects
#include <simics/simulator-iface/osa-component-interface.h> // in C
import "simics/simulator-iface/osa-component-interface.dml"; // in DML
SIM_INTERFACE(osa_component) {
conf_object_t *(*get_admin)(conf_object_t *NOTNULL obj);
maybe_node_id_t (*get_root_node)(conf_object_t *NOTNULL obj);
cancel_id_t (*notify_tracker)(conf_object_t *NOTNULL obj,
void (*cb)(cbdata_call_t data),
cbdata_register_t data);
void (*cancel_notify)(conf_object_t *NOTNULL obj,
cancel_id_t cancel_id);
bool (*has_tracker)(conf_object_t *NOTNULL obj);
attr_value_t (*get_processors)(conf_object_t *NOTNULL obj);
};
#define OSA_COMPONENT_INTERFACE "osa_component"
import simics
class simics.osa_component_interface_t(get_admin=None, get_root_node=None,
notify_tracker=None, cancel_notify=None, has_tracker=None,
get_processors=None)
get_admin returns the osa_admin object associated with the component.
get_root_node returns a maybe_node_id_t with the valid field set to true and id set to the current root node if a root node exists. If no root node exists the valid field will be set to false.
It is only valid to call get_admin or get_root_node on instantiated components.
notify_tracker registers a callback function cb that will be called when a tracker is added to the component using the insert-tracker command. Returns a cancel id that can be used to cancel the callback using cancel_notify. It is a one time notification and will automatically be canceled once it has been called. The data argument will be passed on to the callback.
cancel_notify cancels a callback made by notify_tracker.
has_tracker returns true if the component has a tracker inserted, otherwise false.
get_processors returns a list of processors to use for the software domain.
Cell Context for all methods.
osa_control — enable and disable the OS awareness framework
#include <simics/simulator-iface/osa-control-interface.h> // in C
import "simics/simulator-iface/osa-control-interface.dml"; // in DML
SIM_INTERFACE(osa_control) {
request_id_t (*request)(conf_object_t *NOTNULL obj,
const char *initiator);
void (*release)(conf_object_t *NOTNULL obj, request_id_t id);
};
#define OSA_CONTROL_INTERFACE "osa_control"
import simics
class simics.osa_control_interface_t(request=None, release=None)
Note: The osa_control_v2 interface should be used instead of this one.
request is used to register clients that are interested in using the tracker framework and activates the tracker framework if it is not already activated. The initiator argument is a string which should describe the client that requests to activate the OS Awareness framework. The return value is an ID that should be passed to the release function to signal that the client no longer needs the OS Awareness framework.
Upon a failure while initializing the OS Awareness framework, OSA_Request_Error_ID will be returned.
release removes a client that has previously requested to use the tracker framework. The id argument is the returned value from request. The tracker framework will be disabled when there are no more registered users.
Global Context for all methods.
osa_control_v2 — enable and disable the OS awareness framework
#include <simics/simulator-iface/osa-control-v2-interface.h> // in C
import "simics/simulator-iface/osa-control-v2-interface.dml"; // in DML
SIM_INTERFACE(osa_control_v2) {
attr_value_t (*request)(conf_object_t *NOTNULL obj,
const char *initiator);
void (*release)(conf_object_t *NOTNULL obj, request_id_t id);
attr_value_t (*clear_state)(conf_object_t *NOTNULL obj);
};
#define OSA_CONTROL_V2_INTERFACE "osa_control_v2"
import simics
class simics.osa_control_v2_interface_t(request=None, release=None,
clear_state=None)
request is used to register clients that are interested in using the tracker framework and activates the tracker framework if it is not already activated. The initiator argument is a string which should describe the client that requests to activate the OS Awareness framework. The return format is [bi|s]. If the first element is True, then the second element will contain the request_id, which can be passed to the release function to signal that the client no longer needs the OS Awareness framework. If the first element is False, the second element will be an error message.
release removes a client that has previously requested to use the tracker framework. The id argument is the returned value from request. The tracker framework will be disabled when there are no more registered users.
clear_state can be called to clear the state in the tracker framework that could exist after loading a checkpoint. This can only be called while the tracker is disabled. The return value will be on the format [bi|s]. If the first element is True then clearing state succeeded and the second element can be ignored. If the first element is False then clearing state failed and the second element will contain a string with a message of what went wrong.
Global Context for all methods.
osa_machine_notification — get notifications for cpu updates in an OS awareness tracker
#include <simics/simulator-iface/osa-machine-interfaces.h> // in C
import "simics/simulator-iface/osa-machine-interfaces.dml"; // in DML
SIM_INTERFACE(osa_machine_notification) {
cancel_id_t (*notify_mode_change)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu,
void (*cb)(cbdata_call_t data, conf_object_t *cpu,
processor_mode_t old_mode,
processor_mode_t new_mode),
cbdata_register_t data);
cancel_id_t (*notify_exception)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, int exc_num,
void (*cb)(cbdata_call_t data, conf_object_t *cpu, int exc_num),
cbdata_register_t data);
cancel_id_t (*notify_control_reg)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, int reg_num,
void (*cb)(cbdata_call_t data, conf_object_t *cpu, int reg_num,
uint64 value),
cbdata_register_t data);
cancel_id_t (*notify_exec_breakpoint)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, uint64 address, uint64 len,
bool virt,
void (*cb)(cbdata_call_t data, conf_object_t *cpu,
uint64 address),
cbdata_register_t data);
cancel_id_t (*notify_read_breakpoint)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, uint64 address, unsigned len,
bool virt,
void (*cb)(cbdata_call_t data, conf_object_t *NOTNULL cpu,
uint64 address, unsigned len),
cbdata_register_t data);
cancel_id_t (*notify_write_breakpoint)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, uint64 address, unsigned len,
bool virt,
void (*cb)(cbdata_call_t data, conf_object_t *NOTNULL cpu,
uint64 address, unsigned len, uint64 old_val,
uint64 new_val),
cbdata_register_t data);
void (*cancel)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL tracker, cancel_id_t cancel_id);
cancel_id_t (*notify_control_reg_read)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, int reg_num,
void (*cb)(cbdata_call_t data, conf_object_t *cpu, int reg_num),
cbdata_register_t data);
};
#define OSA_MACHINE_NOTIFICATION_INTERFACE "osa_machine_notification"
import simics
class simics.osa_machine_notification_interface_t(notify_mode_change=None,
notify_exception=None, notify_control_reg=None,
notify_exec_breakpoint=None, notify_read_breakpoint=None,
notify_write_breakpoint=None, cancel=None,
notify_control_reg_read=None)
notify_mode_change registers a callback function that will be called when processor cpu changes processor mode. The callback function will be called with the processor that changed mode cpu, the mode previous to the change old_mode and the mode after the change new_mode.
notify_exception registers a callback function that will be called when processor cpu takes an exception with exception number exc_num. The callback function cb will be called with the processor cpu causing the exception and exception number exc_num of that exception.
notify_control_reg registers a callback function that will be called when a control register, with register number reg_num, in processor cpu is updated. The callback function cb will be called with the processor cpu, register number reg_num and the written register value (see Core_Control_Register_Write for more details) as arguments. The register number for a certain register can be retrieved with the get_register_number function.
notify_control_reg_read registers a callback function that will be called when a control register, with register number reg_num, in processor cpu is read. The callback function cb will be called with the processor cpu and register number reg_num as arguments. The register number for a certain register can be retrieved with the get_register_number function.
notify_exec_breakpoint, notify_read_breakpoint and notify_write_breakpoint plant breakpoints of length len for processor cpu on address. The breakpoint is of type execution, read, write respectively. The virt argument specifies if address is a virtual or physical address. The callback function cb is called when the breakpoint is hit. The arguments of the callback functions are the processor that the breakpoint hit on cpu and the address (virtual or physical depending on what the breakpoint was registered as) that was hit. Callbacks functions for notify_read_breakpoint and notify_write_breakpoint also gets the access size len of the read or write. The callback function for notify_write_breakpoint additionally has the previous value old_val at the address written and the new value new_val that is being written passed as arguments. Reading the actual memory from the callback will result in reading the new value that has been written as the callback is called after the write is done. On x86 virtual breakpoints use linear addresses (as opposed to logical addresses).
For all functions, the tracker argument should be the tracker calling this interface. This makes it possible for a hypervisor tracker to handle guests differently.
All methods that register a notification callback take data as an argument which will be passed on to callback function. These methods return a cancel ID to be used with the cancel method to cancel the callback. A returned value of 0 means that an error occurred and no callback was registered, in which case the caller is responsible for freeing the callback data.
cancel cancels the callback function with ID cancel_id and will free the callback data associated with the notification. This ID will have been returned from the function that registered the callback.
Cell Context for all methods.
osa_machine_query — get cpu state and read memory in an OS awareness tracker
#include <simics/simulator-iface/osa-machine-interfaces.h> // in C
import "simics/simulator-iface/osa-machine-interfaces.dml"; // in DML
typedef enum {
OSA_Read_One_Byte = 1,
OSA_Read_Two_Byte = 2,
OSA_Read_Four_Byte = 4,
OSA_Read_Eight_Byte = 8,
} osa_read_len_t;
SIM_INTERFACE(osa_machine_query) {
uint64 (*read_register)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, int reg);
int (*get_register_number)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, const char *reg);
attr_value_t (*read_phys_memory)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, physical_address_t addr,
osa_read_len_t len);
attr_value_t (*read_phys_bytes)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, physical_address_t paddr,
unsigned len);
attr_value_t (*virtual_to_physical)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, uint64 vaddr);
processor_mode_t (*cpu_mode)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu);
attr_value_t (*get_all_processors)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL tracker);
int (*get_exception_number)(
conf_object_t *NOTNULL obj, conf_object_t *NOTNULL tracker,
conf_object_t *NOTNULL cpu, const char *name);
};
#define OSA_MACHINE_QUERY_INTERFACE "osa_machine_query"
import simics
simics.OSA_Read_Four_Byte
simics.OSA_Read_Eight_Byte
simics.OSA_Read_One_Byte
simics.OSA_Read_Two_Byte
class simics.osa_machine_query_interface_t(read_register=None,
get_register_number=None, read_phys_memory=None,
read_phys_bytes=None, virtual_to_physical=None, cpu_mode=None,
get_all_processors=None, get_exception_number=None)
read_register reads the register with number reg (number can be retrieved with get_register_number) from processor cpu and returns the value of that register.
get_register_number returns the register number of the register with name reg from processor cpu or -1 upon error.
read_phys_memory reads len bytes of memory from physical address addr of processor cpu. The returned value is an uint64 with the value if the read succeeded, otherwise nil. The len argument should use one of the lengths declared in the osa_read_len_t enum.
read_phys_bytes reads len bytes of memory from physical address addr. The length to read can be up to 1024 bytes. The returned value is of data type containing the bytes read upon success or nil otherwise.
virtual_to_physical translates the virtual address vaddr of processor cpu to a physical address as translation would be for a data read. The returned value is the physical address as an uint64 upon success, otherwise nil. For x86 this uses linear to physical translation (as opposed to the logical to physical variant).
cpu_mode returns the current processor mode of cpu.
get_all_processors returns all available processors. For example, when detecting parameters, a tracker should use its known processors if the system is enabled, otherwise it can get them via get_all_processors. For hypervisor configurations, the tracker framework must be enabled in order to detect parameters for a guest.
get_exception_number returns the exception number of the exception with name name from processor cpu. Returns -1 if no exception with the given name exists.
For all functions, the tracker argument should be the tracker calling this interface. This makes it possible for a hypervisor tracker to handle guests differently.
Cell Context for all methods.
osa_mapper_admin — implemented by OS awareness mappers to receive updates
#include <simics/simulator-iface/osa-mapper-interfaces.h> // in C
import "simics/simulator-iface/osa-mapper-interfaces.dml"; // in DML
SIM_INTERFACE(osa_mapper_admin) {
void (*tracker_updated)(conf_object_t *NOTNULL obj,
conf_object_t *initiator,
attr_value_t changeset);
};
#define OSA_MAPPER_ADMIN_INTERFACE "osa_mapper_admin"
import simics
class simics.osa_mapper_admin_interface_t(tracker_updated=None)
tracker_updated is called from the node tree when entities are added, modified or removed. To receive such an update, the mapper must subscribe to tracker updates by calling subscribe_tracker in the osa_tracker_state_notification interface. The initiator argument is the processor object that initiated the transaction. This can be nil if the transaction was not initiated by a processor (for example, enable or disable tracker). The format of changeset is a dictionary with tracker objects that were updated as keys and other dictionaries as values.
The dictionary that is set as the value for each tracker contains the following keywords: added, modified, removed and events.
The value for added is a dictionary which contains the added entity IDs as keys and the attributes of those entities as values.
An example of added where two entities were added:
"added": {0x1000: {"name": "task1", "pid": 1},
0x2000: {"name": "task2", "pid": 2}}
The value for modified is a dictionary which contains the modified entity IDs as keys and a dictionary with the attribute name as key and a list of old and new values for that attribute as its value. Only the attributes that have changed will be included. If an attribute is removed that will be set so that it changed to nil. If an attribute was added that will be set so that it changed from nil.
An example of modified, entity 0x1000 had name changed and entity 0x2000 had tgid added and pid removed:
"modified": {0x1000: {"name": ["task1", "new_name"]},
0x2000: {"tgid": [None, 4], "pid": [2, None]}}
The value for removed is a list which contains the entity IDs for the entities that have been removed.
The value for events is a dictionary indexed by the entity id. Each value is a list of lists, each inner list is an event. The first element of the inner list is the event name and the second element is user defined data associated with the event.
An example of events where entity 0x1000 has two associated events and entity 0x2000 has one associated event:
"events": {0x1000: [["event1", {}], ["event2", {}]],
0x2000: [["syscall", {'sys_num': 0x10, 'sys_name': "open"}]]}
An example of how the complete changeset might look like:
{<the tracker 'tracker1_obj>: {"added": {0x1000: {"name": "task"}},
"modified": {0x2000: {"dummy": [1, 2]}},
"removed": [0x3000, 0x3100]},}
Cell Context for all methods.
osa_mapper_control — for the OS awareness framework to control a mapper
#include <simics/simulator-iface/osa-mapper-interfaces.h> // in C
import "simics/simulator-iface/osa-mapper-interfaces.dml"; // in DML
SIM_INTERFACE(osa_mapper_control) {
void (*disable)(conf_object_t *NOTNULL obj);
bool (*enable)(conf_object_t *NOTNULL obj);
void (*clear_state)(conf_object_t *NOTNULL obj);
};
#define OSA_MAPPER_CONTROL_INTERFACE "osa_mapper_control"
import simics
class simics.osa_mapper_control_interface_t(disable=None, enable=None,
clear_state=None)
The disable function is called when the mapper should be disabled. The mapper should then clean-up the node tree and stop listening to changes from trackers.
The enable function is called when the mapper should be enabled. The mapper should then create the node tree and start listening to changes from trackers.
The clear_state is called to clear the mapper’s state. The mapper should clear all its internal data when this is called, so that enable can be called again. This call can only occur while the mapper is disabled.
Cell Context for all methods.
osa_mapper_query — for querying an OS awareness mapper about it’s nodes
#include <simics/simulator-iface/osa-mapper-interfaces.h> // in C
import "simics/simulator-iface/osa-mapper-interfaces.dml"; // in DML
SIM_INTERFACE(osa_mapper_query) {
attr_value_t (*get_process_list)(conf_object_t *NOTNULL obj);
conf_object_t *(*get_mapper)(conf_object_t *NOTNULL obj,
node_id_t node_id);
};
#define OSA_MAPPER_QUERY_INTERFACE "osa_mapper_query"
import simics
class simics.osa_mapper_query_interface_t(get_process_list=None, get_mapper=None)
The optional get_process_list function provides data for the ‘list’ command. It should return a two-element list, where the first element is a list of column headers, and the second element is a list of (row, subtable) two- element lists. All rows should have the same number of elements as the header list (this is the number of columns in the resulting table).
The elements of the header list and row lists—that is, the individual elements in the table—should be of type string or integer. Integers will be formatted by the system, so in order to force a specific base, such as decimal or hexadecimal, convert them to strings.
The subtables paired with each row should either be None (meaning no subtable) or a nested list such as that returned by get_process_list(), in which case that list will be printed, slightly indented, below the row. This makes it possible for the list command to handle stacked trackers. An example of how a complete return value from get_process_list function can look like:
[["Process", "Pid"], [[["ls", 1], None], [["cat", 2], None]]]
If the function is not implemented, the function pointer should be set to NIL.
The optional get_mapper function returns the mapper that is responsible for the given node. A mapper that has guest mappers should forward the request to the guests as well if the node belongs to one of the guests. If the function is not implemented by the mapper, it is assumed that the node is owned by the mapper.
If this function is not implemented, the function pointer should be set to NIL. Stacked trackers, which support guest trackers must implement this function.
Global Context for all methods.
osa_micro_checkpoint — get notifications when restoring of state starts and finishes
#include <simics/simulator-iface/osa-micro-checkpoint-interface.h> // in C
import "simics/simulator-iface/osa-micro-checkpoint-interface.dml"; // in DML
SIM_INTERFACE(osa_micro_checkpoint) {
void (*started)(conf_object_t *NOTNULL obj);
void (*finished)(conf_object_t *NOTNULL obj);
};
#define OSA_MICRO_CHECKPOINT_INTERFACE "osa_micro_checkpoint"
import simics
class simics.osa_micro_checkpoint_interface_t(started=None, finished=None)
This interface is used to get information when resting of a snapshot starts and finishes. The functions will only be called when the tracker framework is enabled.
started is called when a saved state is about to be restored, before any attributes have been set.
finished is called once all attributes have been set for all objects. At this point callbacks calls to the machine interfaces can be done.
It is allowed to implement only one of these functions if notification are only wanted before or after setting attributes of a snapshot.
This interface is optional and can be implemented by either a tracker or a mapper.
Global Context for all methods.
osa_node_path — OS Awareness node path handling
#include <simics/simulator-iface/osa-node-path-interface.h> // in C
import "simics/simulator-iface/osa-node-path-interface.dml"; // in DML
SIM_INTERFACE(osa_node_path) {
attr_value_t (*matching_nodes)(conf_object_t *NOTNULL obj,
node_id_t root_id,
attr_value_t node_path_pattern);
attr_value_t (*node_path)(conf_object_t *NOTNULL obj,
node_id_t node_id);
};
#define OSA_NODE_PATH_INTERFACE "osa_node_path"
import simics
class simics.osa_node_path_interface_t(matching_nodes=None, node_path=None)
matching_nodes function returns a list of all nodes rooted at root_id that matches the given node_path_pattern. The node_path_pattern should be either an integer representing a node id or a string, see Analyzer User's Guide for more details.
Upon success, the return value is a list where the first entry is true and the second entry is a list containing all the matching node ids.
Upon failure, the return value is a list where the first entry is false and the second entry is a string describing the error.
node_path function translates a node id into a fully qualified node path string. See Analyzer User's Guide for more details.
Upon success, the return value is a list where the first entry is true and the second entry is the node path string.
Upon failure, the return value is a list where the first entry is false and the second entry is a string describing the error.
Global Context for all methods.
osa_node_tree_admin — used by mapper to communicate with OS awareness framework
#include <simics/simulator-iface/osa-node-tree-admin-interface.h> // in C
import "simics/simulator-iface/osa-node-tree-admin-interface.dml"; // in DML
SIM_INTERFACE(osa_node_tree_admin) {
transaction_id_t (*begin)(conf_object_t *NOTNULL obj,
conf_object_t *initiator);
void (*end)(conf_object_t *NOTNULL obj,
transaction_id_t transaction_id);
node_id_t (*create)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL mapper, attr_value_t props);
node_id_t (*add)(conf_object_t *NOTNULL obj,
node_id_t parent_id, attr_value_t props);
void (*update)(conf_object_t *NOTNULL obj, node_id_t node_id,
attr_value_t props);
void (*remove)(conf_object_t *NOTNULL obj, node_id_t node_id);
void (*event)(conf_object_t *NOTNULL obj, node_id_t node_id,
const char *event_name, attr_value_t event_data);
void (*activate)(conf_object_t *NOTNULL obj, node_id_t node_id,
conf_object_t *NOTNULL cpu);
void (*deactivate)(conf_object_t *NOTNULL obj, node_id_t node_id,
conf_object_t *NOTNULL cpu);
cancel_id_t (*register_formatter)(
conf_object_t *NOTNULL obj, node_id_t node_id,
const char *NOTNULL key,
bool recursive, attr_value_t (*formatter)(attr_value_t val));
void (*unregister_formatter)(
conf_object_t *NOTNULL obj, cancel_id_t node_id);
void (*reset)(conf_object_t *NOTNULL obj,
node_id_t node_id, attr_value_t props);
void (*set_property)(conf_object_t *NOTNULL obj, node_id_t node_id,
const char *key, attr_value_t value);
};
#define OSA_NODE_TREE_ADMIN_INTERFACE "osa_node_tree_admin"
import simics
class simics.osa_node_tree_admin_interface_t(begin=None, end=None, create=None,
add=None, update=None, remove=None, event=None, activate=None,
deactivate=None, register_formatter=None, unregister_formatter=None,
reset=None, set_property=None)
begin is called from the mapper to start a transaction when adding, updating or removing nodes in the node tree. The initiator argument specifies the initiator processor, this can be nil if the transaction is not initiated by a processor. The initiator will be passed as cpu argument to callback functions in the osa_node_tree_notification interface. The function returns an ID to be used when calling end.
end is called from the mapper to end a transaction. This should be called at the end of a transaction when all modifications to the node tree are complete. The transaction_id argument should be the value returned from the begin method that started the transaction. Stacked calls to begin and end are possible, then the transaction will be ended when the first begin is ended. The begin methods must be ended in the opposite order that they were called. For stacked calls to begin only the initiator of the first call to begin will be used.
create creates a new node tree and associates mapper with it. The properties of the root node for the new tree are set through props which is a dictionary. The returned value is the node ID of the created root node.
add adds a new node rooted at parent_id. The new node gets the properties specified by props which is a dictionary. The returned value is the node ID of the newly added node.
update updates the properties of a node in the node tree. node_id specifies the node to be updated and props is a dictionary of the properties that should be updated.
set_property updates one property of a node in the node tree. This is similar to update but there is no need to build up a dictionary. node_id specifies the node to be updated, key the key of the property to be updated and value the value to update the property with.
reset resets a node, node_id, to the properties specified by props. All the children for the node will be removed and all properties except the ones in props will be removed. If the reset node was previously active it will be deactivated.
All methods have the limitation that data and dictionary types are not supported as the value of a property. The keys of the props dictionary must all be of string type.
remove removes the node with the ID specified by node_id from the node tree.
event registers a new event, associated with the given node_id. The event_name argument is the name of the event, this name can also be used by a user to only listen to a specific event type per node tree. The event_data argument is the data associated with the event and it is up to the responsible tracker to document its exact form. An event differes from other properties in the way that they are not persistent.
activate sets node_id as the active node for processor cpu in the node tree where node_id exists. All the ancestors of node_id will also be set as active. Any previously active node for cpu will be deactivated.
deactivate deactivates processor cpu in the node tree where node_id exists. The node_id argument should be set to the node that was previously active on cpu in the node tree.
register_formatter registers a callback function which will be called when the property specified by the key argument should be formatted in a specific way. This is typically called from "get_formatted_properties" in the osa_node_tree_query interface. This is useful for systems where an integer property should be formatted in hexadecimal to make a closer match to the target OS mapper of that property. For example, a node with the following properties:
{"name": "foo", "tid": 4711}
could then be formatted as:
{"name": "foo", "tid": "0x1267"}
The function itself must return a string, given as an attr_value_t. The mapper must have been registered by calling the create function in the osa_node_tree_admin interface before registering a formatter.
The register_formatter function returns a cancel id that can be passed to the unregister_formatter function to unregister the formatting function. Registering a new formatter on the same node_id and key as a previous formatter will override the previous formatter with the new one. This is useful when dealing with stacked trackers and a sub-tracker needs to register a formatter for a node that already have a registered formatter.
unregister_formatter unregisters a previously registered formatter function using the register_formatter function.
Cell Context for all methods.
osa_node_tree_notification — listen to OS awareness node tree updates
#include <simics/simulator-iface/osa-node-tree-interfaces.h> // in C
import "simics/simulator-iface/osa-node-tree-interfaces.dml"; // in DML
SIM_INTERFACE(osa_node_tree_notification)
{
cancel_id_t (*notify_create)(conf_object_t *NOTNULL obj,
node_id_t node_id, bool recursive,
void (*cb)(cbdata_call_t data,
conf_object_t *obj,
conf_object_t *cpu,
node_id_t node_id),
cbdata_register_t data);
cancel_id_t (*notify_destroy)(conf_object_t *NOTNULL obj,
node_id_t node_id, bool recursive,
void (*cb)(cbdata_call_t data,
conf_object_t *obj,
conf_object_t *cpu,
node_id_t node_id),
cbdata_register_t data);
cancel_id_t (*notify_property_change)(
conf_object_t *NOTNULL obj, node_id_t node_id,
const char *key, bool recursive,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, node_id_t node_id,
const char *key, attr_value_t old_val,
attr_value_t new_val),
cbdata_register_t data);
cancel_id_t (*notify_cpu_move_from)(
conf_object_t *NOTNULL obj, node_id_t node_id,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, attr_value_t node_path),
cbdata_register_t data);
cancel_id_t (*notify_cpu_move_to)(
conf_object_t *NOTNULL obj, node_id_t node_id,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, attr_value_t node_path),
cbdata_register_t data);
cancel_id_t (*notify_event)(
conf_object_t *NOTNULL obj, node_id_t node_id,
const char *event_name, bool recursive,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, node_id_t node_id,
const char *event_name, attr_value_t event_data),
cbdata_register_t data);
cancel_id_t (*notify_enable)(
conf_object_t *NOTNULL obj,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
cancel_id_t (*notify_disable)(
conf_object_t *NOTNULL obj,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
void (*cancel_notify)(conf_object_t *NOTNULL obj,
cancel_id_t cancel_id);
cancel_id_t (*notify_callbacks_done)(
conf_object_t *NOTNULL obj, uint64 node_id,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
};
#define OSA_NODE_TREE_NOTIFICATION_INTERFACE "osa_node_tree_notification"
import simics
class simics.osa_node_tree_notification_interface_t(notify_create=None,
notify_destroy=None, notify_property_change=None,
notify_cpu_move_from=None, notify_cpu_move_to=None,
notify_event=None, notify_enable=None, notify_disable=None,
cancel_notify=None, notify_callbacks_done=None)
notify_create and notify_destroy register callbacks to be called when the node is created and destroyed, respectively. The node_id argument specifies for which node the callback should be installed. By specifying both the node_id and the recursive arguments it is possible to get notifications for all nodes in a subtree. It is safe to read the node with get_node in the osa_node_tree_query interface from within the callback function.
Calling notify_create without recursive being set is only useful when the node ID of a node that is to be created later is known, for example when re-running the same simulation after restoring a snapshot.
notify_property_change registers a callback that is triggered when the given property key changes on the node (or any property, if key is nil). The callback function will receive the name of the property that was changed in the key argument and the old and new values of that property in the old_val and new_val arguments.
notify_event register a callback cb to be called when an event occurs for the given node_id. If the event_name argument is nil the callback will be associated with all events, by providing a specific event name instead the callback will only trigger for that particular event type. The event_data argument passed to the callback contains tracker specific data associated with the event. See specific tracker documentation for details.
If recursive, the callback will be triggered for the given node’s descendants as well as the node itself.
Most callbacks have cpu and obj arguments. The cpu argument specifies the processor that caused the event, but may be nil if the event was not caused by a processor. The obj will contain the object that implements the interface. The node_id argument passed to the callback specifies the node ID for the node that has been created, destroyed, modified or has triggered an event.
notify_cpu_move_from and notify_cpu_move_to register callbacks that are triggered when a processor moves from one node path to another—but only if either path lies in the subtree rooted at the given node node_id.
Since a single update to the node tree can result in several different callbacks being triggered, reading nodes with get_node from a callback function may yield a result containing updates whose callbacks have not yet been run. For example, if two nodes change their name attributes simultaneously, the final state of both nodes may be visible to both property change callbacks. With notify_callbacks_done, you can register a callback that will run when all other callbacks pertaining to a particular change in the node tree are finished.
notify_enable register a callback cb to be called when the tracker framework is enabled.
notify_disable register a callback cb to be called when the tracker framework is disabled.
The functions that install callbacks return an integer ID. This ID can be passed to cancel_notify in order to uninstall the callback. In case of error in a notification function the returned cancel ID from that function will be 0.
New callbacks registered inside a registered callback will not be called until the next transaction they trigger for. Canceled callbacks are canceled immediately.
Cell Context for all methods.
osa_node_tree_query — query OS awareness node trees
#include <simics/simulator-iface/osa-node-tree-interfaces.h> // in C
import "simics/simulator-iface/osa-node-tree-interfaces.dml"; // in DML
SIM_INTERFACE(osa_node_tree_query) {
attr_value_t (*get_root_nodes)(conf_object_t *NOTNULL obj);
attr_value_t (*get_node)(conf_object_t *NOTNULL obj, node_id_t node_id);
attr_value_t (*get_current_nodes)(conf_object_t *NOTNULL obj,
node_id_t base_id,
conf_object_t *cpu);
attr_value_t (*get_current_processors)(conf_object_t *NOTNULL obj,
node_id_t node_id);
attr_value_t (*get_all_processors)(conf_object_t *NOTNULL obj);
conf_object_t *(*get_mapper)(conf_object_t *NOTNULL obj,
node_id_t node_id);
attr_value_t (*get_parent)(conf_object_t *NOTNULL obj,
node_id_t node_id);
attr_value_t (*get_children)(conf_object_t *NOTNULL obj,
node_id_t node_id);
attr_value_t (*get_formatted_properties)(conf_object_t *NOTNULL obj,
uint64 node_id);
};
#define OSA_NODE_TREE_QUERY_INTERFACE "osa_node_tree_query"
import simics
class simics.osa_node_tree_query_interface_t(get_root_nodes=None, get_node=None,
get_current_nodes=None, get_current_processors=None,
get_all_processors=None, get_mapper=None, get_parent=None,
get_children=None, get_formatted_properties=None)
get_root_nodes returns a list of node IDs for the root nodes.
get_node returns a dictionary for a given node, containing all the node’s properties; or nil if no such node exists.
get_current_nodes returns the current node path of the given processor. That is, a list of node IDs of all nodes that are currently running on the processor, the first node being the root node, and every subsequent node a child of the node before it. If the tracker is not tracking the given processor, the return value is nil.
get_current_processors returns a list of processors that are currently active on the given node, or one of it’s descendants. The list will be empty if there is no active processor. Nil will be returned if the given node does not exist.
get_all_processors returns a list of all processors that are available for the OS Awareness framework.
get_parent returns the node ID of the specified node’s parent; or nil if the node has no parent.
get_children returns a list of node IDs for the children of the specified node, this will be an empty list if the node does not have any children. The method will return nil if the node does not exist.
The get_formatted_properties function returns a dictionary containing all properties for a node, formatted as strings or integers. It will return nil upon a failure. For example, a tracker could format the value of property pid to show the value in hexadecimal form.
{'name': "Our OS", 'pid': "0x1234"}
Cell Context for all methods.
osa_parameters — get and set OS awareness tracker parameters
#include <simics/simulator-iface/osa-parameters-interface.h> // in C
import "simics/simulator-iface/osa-parameters-interface.dml"; // in DML
SIM_INTERFACE(osa_parameters) {
attr_value_t (*get_parameters)(conf_object_t *NOTNULL obj,
bool include_children);
attr_value_t (*set_parameters)(conf_object_t *NOTNULL obj,
attr_value_t parameters);
bool (*is_kind_supported)(conf_object_t *NOTNULL obj,
const char *kind);
};
#define OSA_PARAMETERS_INTERFACE "osa_parameters"
import simics
class simics.osa_parameters_interface_t(get_parameters=None, set_parameters=None,
is_kind_supported=None)
Interface implemented by tracker components that support getting and setting their parameters.
If either method fails it returns a (false, error-string) pair. If get_parameters succeed it returns (true, parameters). If set_parameters succeed it returns (true, nil).
The parameters you pass to set_parameters and thare are returned by get_parameters should be a pair (tracker-kind, parameters-value), where tracker-kind is a string identifying the kind of tracker and parameters-value is the parameters for that kind of tracker. The parameters for an unconfigured tracker are (tracker-kind, nil).
The include_children argument of get_parameters is only used for stacked tracker and specifies if parameters for guest trackers should be included or filtered out.
The is_kind_supported method returns true if the tracker-kind in a parameter set is of the right kind for the tracker. This is no guarantee that setting these parameters will succeed. If the method returns false the parameters will not work.
Global Context for all methods.
osa_tracker_component — get associated OS awareness trackers or mappers
#include <simics/simulator-iface/osa-tracker-component-interface.h> // in C
import "simics/simulator-iface/osa-tracker-component-interface.dml"; // in DML
SIM_INTERFACE(osa_tracker_component) {
conf_object_t *(*get_tracker)(conf_object_t *NOTNULL obj);
conf_object_t *(*get_mapper)(conf_object_t *NOTNULL obj);
};
#define OSA_TRACKER_COMPONENT_INTERFACE "osa_tracker_component"
import simics
class simics.osa_tracker_component_interface_t(get_tracker=None, get_mapper=None)
get_tracker returns the tracker object associated with the component or nil if no such tracker exists.
get_mapper returns the mapper object associated with the component or nil if no such mapper exists.
Cell Context for all methods.
osa_tracker_control — control OS awareness trackers
#include <simics/simulator-iface/osa-tracker-control-interface.h> // in C
import "simics/simulator-iface/osa-tracker-control-interface.dml"; // in DML
SIM_INTERFACE(osa_tracker_control) {
void (*disable)(conf_object_t *NOTNULL obj);
bool (*enable)(conf_object_t *NOTNULL obj);
void (*clear_state)(conf_object_t *NOTNULL obj);
bool (*add_processor)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL cpu);
bool (*remove_processor)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL cpu);
};
#define OSA_TRACKER_CONTROL_INTERFACE "osa_tracker_control"
import simics
class simics.osa_tracker_control_interface_t(disable=None, enable=None,
clear_state=None, add_processor=None, remove_processor=None)
enable and disable are called from the OS Awareness framework, for all trackers that have been set in the top_trackers attribute for the node_tree object, when OS Awareness is enabled or disabled, respectively.
clear_state is called to clear the trackers state. The tracker should clear all its internal data and its data in the node tree when this is called. This call can only occur while the tracker is disabled.
add_processor and remove_processor are called to add or remove a processor cpu to/from the tracker which the tracker should start/stop tracking. If the tracker is registered as a top level tracker these methods will be called by the OS Awareness framework for all processors available to the framework when it is enabled or disabled. If the tracker is a guest under a hypervisor the hypervisor should call these methods when a processor becomes available or unavailable to the guest. These functions should return true if a processor was successfully added or removed, otherwise the function should return false.
Global Context for enable, disable and clear_state. Cell Context for add_processor and remove_processor.
osa_tracker_state_admin — used by OS awareness trackers to modify state in framework
#include <simics/simulator-iface/osa-tracker-state-interfaces.h> // in C
import "simics/simulator-iface/osa-tracker-state-interfaces.dml"; // in DML
SIM_INTERFACE(osa_tracker_state_admin) {
transaction_id_t (*begin)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL tracker,
conf_object_t *initiator);
void (*end)(conf_object_t *NOTNULL obj, transaction_id_t txid);
void (*add)(conf_object_t *NOTNULL obj, entity_id_t entity_id,
attr_value_t attributes);
void (*remove)(conf_object_t *NOTNULL obj, entity_id_t entity_id);
void (*remove_all)(conf_object_t *NOTNULL obj);
void (*set_attribute)(conf_object_t *NOTNULL obj, entity_id_t entity_id,
const char *key, attr_value_t val);
void (*update)(conf_object_t *NOTNULL obj, entity_id_t entity_id,
attr_value_t attributes);
void (*event)(conf_object_t *NOTNULL obj, entity_id_t entity_id,
const char *event_name, attr_value_t event_data);
};
#define OSA_TRACKER_STATE_ADMIN_INTERFACE "osa_tracker_state_admin"
import simics
class simics.osa_tracker_state_admin_interface_t(begin=None, end=None, add=None,
remove=None, remove_all=None, set_attribute=None, update=None,
event=None)
begin is called from the tracker to start a transaction when modifying an entity in the node tree. The tracker argument specifies the tracker object for which the updates are done for. The initiator argument specifies the processor that initiated the transaction, this can be nil if it was not a processor that caused the transaction to begin, when enabling the tracker as an example. The initiator is passed as an argument to the tracker_updated function in the osa_mapper_admin interface. The function returns an ID that is used when calling end.
end is called from the tracker to end a transaction. This should be called at the end of a transaction when all entity modifications are done. The transaction_id argument should be the value returned from begin that started the transaction. Stacked calls to begin and end are possible, then the transaction will be ended when the first begin is ended. The begin methods must be ended in the opposite order that they were called. For stacked calls to begin only the initiator of the first call to begin will be used.
add adds a new entity with ID entity_id to the node tree. The new entity’s attributes are set in the attributes argument, which is a dictionary.
remove removes the entity with ID entity_id for the current tracker from the node tree.
remove_all removes all entities for the current tracker from the node tree.
set_attribute adds or updates an attribute key for the entity with ID entity_id. The new value is specified in val.
update updates or adds one or more attributes for the entity with ID entity_id. The attributes argument is a dictionary with the attributes to be updated.
In order to remove a property, set the property value to nil when calling update or set_attribute.
event registers a new event, associated with the given entity_id argument. The event_name argument is the name of the event. The event_data argument is the data associated with the event and it is up to the responsible tracker to document its exact form. An event differes from other properties in the way that they are not persistent.
Entity attributes have the limitation that the value of the attribute can not be of type data or dictionary. The keys of entity attributes must be of string type.
Cell Context for all methods.
osa_tracker_state_notification — for OS awareness mappers to get tracker updates from framework
#include <simics/simulator-iface/osa-tracker-state-interfaces.h> // in C
import "simics/simulator-iface/osa-tracker-state-interfaces.dml"; // in DML
SIM_INTERFACE(osa_tracker_state_notification) {
void (*subscribe_tracker)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL mapper,
conf_object_t *NOTNULL tracker);
void (*unsubscribe_tracker)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL mapper,
conf_object_t *NOTNULL tracker);
};
#define OSA_TRACKER_STATE_NOTIFICATION_INTERFACE \
"osa_tracker_state_notification"
import simics
class simics.osa_tracker_state_notification_interface_t(subscribe_tracker=None,
unsubscribe_tracker=None)
subscribe_tracker is called to make mapper receive updates for entities of tracker. When such an update occurs, the function tracker_updated in interface osa_mapper_admin will be called.
unsubscribe_tracker cancels a subscription of entity updates to mapper that was started by subscribe_tracker for the specified tracker. A tracker without guest trackers does not need to call this, as it will be automatically done when the framework is disabled. However, a tracker with guest trackers, must call this function when a guest is removed.
Cell Context for all methods.
osa_tracker_state_query — query OS awareness framework for tracker state
#include <simics/simulator-iface/osa-tracker-state-interfaces.h> // in C
import "simics/simulator-iface/osa-tracker-state-interfaces.dml"; // in DML
SIM_INTERFACE(osa_tracker_state_query) {
attr_value_t (*_deprecated)(conf_object_t *NOTNULL obj);
attr_value_t (*get_entities)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL tracker);
attr_value_t (*get_entity)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL tracker,
entity_id_t id);
};
#define OSA_TRACKER_STATE_QUERY_INTERFACE "osa_tracker_state_query"
import simics
class simics.osa_tracker_state_query_interface_t(_deprecated=None,
get_entities=None, get_entity=None)
get_entities returns a dictionary of entities that are stored for tracker. The dictionary maps entity id to properties, which in turn is a dictionary, mapping property name to property value. Returns nil if tracker is not known.
get_entity returns the properties for the given entity id and tracker, as a dictionary that maps property name to property value. Returns nil if the entity can not be found.
Cell Context for all methods.
probe_array — defines multiple probes with array access
#include <simics/simulator-iface/probe-interface.h> // in C
import "simics/simulator-iface/probe-interface.dml"; // in DML
SIM_INTERFACE(probe_array) {
int (*num_indices)(conf_object_t *obj);
attr_value_t (*value)(conf_object_t *obj, int idx);
attr_value_t (*all_values)(conf_object_t *obj);
attr_value_t (*properties)(conf_object_t *obj, int idx);
};
#define PROBE_ARRAY_INTERFACE "probe_array"
import simics
class simics.probe_array_interface_t(num_indices=None, value=None,
all_values=None, properties=None)
This interface is similar to the probe_index interface, except that an additional all_values() method returns an attr_value_t list of values as individually returned when calling value(idx) on each indexed probe. Using all_values() instead of looping over value(idx) can provide a significant improvement in performance, depending on the number of probes whose values need to be read, starting from a couple of probes. The probe_sampler objects, provided in the probe-monitor extension, make use of the all_values() method to boost their performance when sampling probes implemented with the probe_array interface.
Global Context for all methods.
probe_index — defines multiple probes
#include <simics/simulator-iface/probe-interface.h> // in C
import "simics/simulator-iface/probe-interface.dml"; // in DML
SIM_INTERFACE(probe_index) {
int (*num_indices)(conf_object_t *obj);
attr_value_t (*value)(conf_object_t *obj, int idx);
attr_value_t (*properties)(conf_object_t *obj, int idx);
};
#define PROBE_INDEX_INTERFACE "probe_index"
import simics
class simics.probe_index_interface_t(num_indices=None, value=None,
properties=None)
This interface is similar to the probe interface, except that the indexed version allows multiple probes to be defined with a single interface. The same index corresponds to the same probe for value and properties methods. The amount of probes that the interfaces supports is returned through the num_indices() method, which should be static.
Global Context for all methods.
probe_key_t, probe — defines a probe in the system
#include <simics/simulator-iface/probe-interface.h> // in C
import "simics/simulator-iface/probe-interface.dml"; // in DML
typedef enum {
Probe_Key_Kind = 0, /* Identifier of the probe */
Probe_Key_Name = 0, /* Old name of Probe_Key_Kind,
kept for compatibility */
Probe_Key_Type = 1, /* string, any of: {
"int", "float", "fraction",
"histogram", "int128", "string"
} */
Probe_Key_Categories = 2, /* list of strings */
Probe_Key_Cause_Slowdown = 3, /* bool */
Probe_Key_Owner_Object = 4, /* object: owner object */
Probe_Key_Display_Name = 5, /* string: short narrow name */
Probe_Key_Description = 6, /* string */
Probe_Key_Float_Percent = 7,
Probe_Key_Float_Decimals = 8,
Probe_Key_Metric_Prefix = 9,
Probe_Key_Unit = 10,
Probe_Key_Binary_Prefix = 11,
Probe_Key_Time_Format = 12,
Probe_Key_Width = 13,
Probe_Key_Value_Notifier = 14,
Probe_Key_Aggregates = 17, /* Defines new probes which aggregate
over this probe:
[list of [list properties]]
Invalid for Type: "string"
*/
Probe_Key_Aggregate_Scope = 18, /* Aggregate over all probes in the
cells or all probes in the system.
String and of ["global", "cell"] */
Probe_Key_Aggregate_Function = 19, /* How the aggregation should be
done:
"sum",
"weighted-arith-mean",
- only fractions
*/
Probe_Key_Definition = 20, /* string: how the probe is
calculated */
Probe_Key_Histogram_Options = 21, /* list: histogram presentation
options */
} probe_key_t;
SIM_INTERFACE(probe) {
attr_value_t (*value)(conf_object_t *obj);
attr_value_t (*properties)(conf_object_t *obj);
};
#define PROBE_INTERFACE "probe"
import simics
simics.Probe_Key_Description
simics.Probe_Key_Metric_Prefix
simics.Probe_Key_Float_Decimals
simics.Probe_Key_Cause_Slowdown
simics.Probe_Key_Kind
simics.Probe_Key_Aggregate_Function
simics.Probe_Key_Display_Name
simics.Probe_Key_Histogram_Options
simics.Probe_Key_Binary_Prefix
simics.Probe_Key_Categories
simics.Probe_Key_Value_Notifier
simics.Probe_Key_Unit
simics.Probe_Key_Width
simics.Probe_Key_Aggregate_Scope
simics.Probe_Key_Owner_Object
simics.Probe_Key_Time_Format
simics.Probe_Key_Float_Percent
simics.Probe_Key_Type
simics.Probe_Key_Aggregates
simics.Probe_Key_Definition
class simics.probe_interface_t(value=None, properties=None)
This interface defines a probe in the system. A probe is a mechanism that lets a model expose values of interest to a user. By using this interface, generic tools can extract these values and present them in different forms, like tables and graphs. A probe should always have a meaningful value that can be read at any time during the simulation.
Probes should be used for user observable values and are not intended for model to model communication.
The properties() method is typically called once for each tool or use-case to get information about the probe. It should return a key/value attr_value_t list, i.e., list of lists of two values, with probe specific properties. The first value of the inner list represents the property key as an integer using the enum probe_key_t type, and the second value is a key specific data item described below.
The value() method should return the data for the probe as an attr_value_t in accordance of how the property type has been defined. This method is called each time a tool/user wants to read the latest probe value.
The property keys are describes here as follows:
Probe_Key_KindSets the kind of the probe, as a string. The probe-kinds are what uniquely define the probes in the system.
There can be many probes associated with the same kind, but they should all represent the same type of measured data.
The kind should be named so it is humanly possible to understand what you get back when you read it.
To avoid conflicts, the kind should be an hierarchical name where each level is separated with a dot. Probes falling into the same domain should have logical names according to this. Currently, there are some defined names on the first level that can be used to build the hierarchy. Among them are: cpu. that collects probes related to a CPU, dev. that collects probes for devices, cell. that collects probes related to cells, host. collects probes related to the host environment, and sim. that collects probes having to do with the overall simulation environment.
Some examples, include: cpu.cycles, cpu.exec_mode.jit_steps, dev.io_access_count, cell.steps, host.swap.used, and sim.slowdown.
Several objects implementing this interface can use the same probe-kind, for similar probe values. The probe’s unique identifier is a string containing the object name then a colon, followed by the probe-kind, e.g., “board.mb.cpu0.cpu[0][0]:cpu.cycles”.
Probe_Key_Display_NameSets a display name for the probe as a string (Sim_Val_String). This is a more human friendly name than the probe name, and a tool can use this name in table headings or graph legends.
Probe_Key_TypeSets the type of the probe as a string (Sim_Val_String). The following types are defined: “int”, “float”, “string”, “fraction”, “int128” and “histogram”. The attr_value_t value that should be returned by the value method for these types are as follows:
For the int type, an attr_value_t of type Sim_Val_Integer should be returned.
For the float type, return a Sim_Val_Floating value.
The string type is returned by a Sim_Val_String value. The string typically represents some momentarily state. Due to nature of a string, a tool cannot do any calculation on the probe value, only show the current string content.
The fraction type should use a attr_value_t list of two Sim_Val_Integer or Sim_Val_Floating values. This represent a mathematical fraction value, where the first one is the numerator and and the second value is the denominator value. Note however that a float value can be used for both of them. To get the proper value for this probe the tool/user should divide the numerator with the denominator. Using fraction makes it possible for the tool to calculate a mean value for this probe between any point in time where the probe was read, e.g., say you have a probe that reads the frequency of a simulated processor that varies over time. Then this probe can be defined as a fraction between the cycle count and the elapsed virtual time (cycles/time = frequency). If the tool saves the cycle difference and the time difference between to points in time, it can calculate the mean frequency between those point by dividing the differences.
For very large numbers the int128 type can be used, the type is represented as a attr_value_t list of two value; the high 64-bit number followed by the low 64-bit number.
The histogram type is represented by a attr_value_t list of lists of two values. Where the inner list is used as a tuple of a named group as a Sim_Val_String, and its corresponding value as a Sim_Val_Integer or Sim_Val_Floating. A tool can then display an histogram of these groups and/or calculate the difference between two histograms over time and display that.
Probe_Key_CategoriesThe key is a list of string that defines some categories for the probe. This information can be used to search for probes of a specific use case.
Probe_Key_Cause_SlowdownThe value for this key is a Sim_Val_Boolean. True means that using the probe can cause a significant slowdown of the simulation. False means it does not cause any particular slowdown.
Probe_Key_Owner_ObjectThe value for this key is a Sim_Val_Object that should be regarded as the owner of the probe instead of the object that implements this interface (which is default). This can be useful if some other objects implements functionality for the main object.
Probe_Key_DescriptionThe value for this key is a Sim_Val_String that documents this probe in details.
Probe_Key_Definition“Function” definition string, explaining how the probe is being calculated out from other probes. This is automatically created for probe aggregates and derivatives. Default is an empty string.
Probe_Key_Float_DecimalsThe value for this key is a Sim_Val_Integer that sets the preferred number of decimals of this is float probe when a value is displayed.
Probe_Key_Float_PercentThe value for this key is a Sim_Val_Boolean that sets the preferred representation of a float probe as a percent representation, e.g., a value of 0.176 will be displayed as 17.6% if the number of decimals are one.
Probe_Key_Metric_PrefixThe value for this key is a Sim_Val_String describing a unit name. This sets the preferred representation of a float probe to be displayed with a metric prefix for the unit given. Supported metric prefixes are: k, M, G, T, P, E, Z, Y, for values > 1 and m, µ, n, p, f, a, z, y for values <
Probe_Key_Binary_PrefixThe value for this key is a Sim_Val_String describing a unit name. This sets the preferred representation of an integer probe to be displayed with a binary prefix for the unit given. Supported prefixes are: ki, Mi, Gi, Ti, Pi, Ei, Zi, and Yi. For example if the unit is set to “B” (representing bytes), and the integer value is 10485760 (1010241024), then the displayed representation should be “10 MiB”.
Probe_Key_UnitThe value for this key is a Sim_Val_String that sets the unit for the value. A tool can use this to display the unit for the value.
Probe_Key_Time_FormatThe value for this key is a Sim_Val_Boolean that sets the preferred representation for a float value to a time format, hh:mm:ss.d, where h is hours, m minutes, s seconds, and d is fractions of a seconds. The raw value returned by the value method is the number of seconds. The Probe_Key_Float_Decimals key/value pair controls the number of digits in the fraction. If the number of seconds represents more than 99 hours, it should continue adding digits for the hours, e.g., 100:44:10.123
Probe_Key_WidthThe value for this key is a Sim_Val_Integer that sets the preferred width of a probe value in characters. This can be used to determine the best width of columns in a table tool, for instance.
Probe_Key_Histogram_OptionsThe value for this key is a list of key/value pairs that controls histogram presentation. The supported option is percent, a boolean specifying whether tools should show a percentage column and combine omitted values when truncating output. It defaults to true. If false, tools should omit percentages and report only the number of omitted rows.
Probe_Key_Value_NotifierThe value for this key is a Sim_Val_String that describes a notifier that is triggered when the value changes. This can be used by a tool to track all changes of the value. For performance reasons the value should be changes infrequently.
Probe_Key_Global_SumDeprecated, use Probe_Key_Aggregates instead.
Probe_Key_Cell_SumDeprecated, use Probe_Key_Aggregates instead.
Probe_Key_AggregatesDefines lists of new probes which are aggregates of the probe defined. Each list-element defines a new probe, specified as a list of the key-value properties for the aggregate probe. All properties are inherited from the probe being aggregated, except the new name of the aggregate probe which must be defined. Probe keys can be redefined if they appear in the aggregate scope. For example, it is advisable to change the description making it clear what value that is being returned by the aggregate.
Only in the aggregate scope, the Probe_Key_Aggregate_Scope and Probe_Key_Aggregate_Function key-value pairs are used to further define how the aggregation is done. Note that aggregates depend on the the type of the underlying probe. Some probe types can only be aggregated with certain functions.
Probe_Key_Aggregate_ScopeDefines the scope for the aggregate probe. That is, which objects that implements the probe, should be part of the aggregation. Valid values are “cell” or “global”. Default is “global”, which means that all objects which implements the probe will be part of the aggregate and put in the singleton owner object, such as the ‘sim’ or ‘host’ objects.
Cell-aggregates are put under the available cell objects and will aggregate the probe which belongs to the respective cell object.
Probe_Key_Aggregate_FunctionDefines how the aggregate should be generated. Valid values are “sum”, “min”, “max”, “arith-mean”, “weighted-arith-mean”, “median”, “object-histogram” and “class-histogram”. Default is “sum”.
For probes of the fraction type, if any denominator contains a zero value (division by zero), the calculated value is undefined and [0, 0] is returned. This applies to all fraction aggregates except weighted-arith-mean, where the zero denominator can be handled.
sumAll probe values are summed together. Not supported on “string” probes.
minThe lowest value among the probe values is returned. Not supported on “string” and “histogram” probes. For fraction-probes, if any denominator contains a zero value, the calculated sum returned is [0, 0].
maxThe highest value among probe values is returned. Not supported on “string” and “histogram” probes.
arith-meanThe arithmetic mean is calculated for all the probe values. Not supported on “string” and “histogram” probes.
weighted-arith-meanOnly supported in fraction type probes. The denominators are used as weights.
Using these weights implies that the weighted arithmetic mean can be calculated by adding all numerators and denominators, producing a new fraction of these sums.
For example, when calculating the mean instruction per cycles (IPC) on all processors (where the IPC per processor is represented as a fraction: instructions / cycles). With two processors having [20/30] and [40/50], the total IPC becomes [(20+40)/(30+50)] or [60/80] and the IPC value of 0.75.
medianThe median among the probe values is returned. Not supported on “fraction”, “string” and “histogram” probes.
object-histogramA histogram probe is created using the probe-owner-objects as key and their probe-values value. The type of this aggregate probe must be set to “histogram”. Only supported on “int” and “float” probes types.
class-histogramSimilar to the object-histogram, but here the histogram uses the classname of the owner-object as key, and the value is the sum of the probe-values with the same class. The type of this aggregate probe must be set to “histogram”. Only supported on “int” and “float” probes types.
All key/value pairs except the Probe_Key_Kind and Probe_Key_Type are optional.
Global Context for all methods.
probe_sampler_cache — enable and disable probe caching
#include <simics/simulator-iface/probe-interface.h> // in C
import "simics/simulator-iface/probe-interface.dml"; // in DML
SIM_INTERFACE(probe_sampler_cache) {
void (*enable)(conf_object_t *obj);
void (*disable)(conf_object_t *obj);
uint64 (*get_generation)(conf_object_t *obj);
};
#define PROBE_SAMPLER_CACHE_INTERFACE "probe_sampler_cache"
import simics
class simics.probe_sampler_cache_interface_t(enable=None, disable=None,
get_generation=None)
This interface is implemented by the singleton probes object, created by the enable-probes command. The interface is expected to be used by either probe-samplers (enable and disable) or by a probe which supports caching (get_generation_id).
When a probe-sampler calls the enable method, caching can start. Caching depends on a generation id, this is automatically increased by enable.
With caching enabled, probes can return the previous value back, avoiding expensive calculation, if they are read multiple times (either directly, or indirectly from other probes). It can also be used to avoid probe values to return a slightly different value the next time in the same sample, such as wallclock time.
A probe which wants to use caching needs to call the get_generation_id method. As long as the generation id is the same as the last time the probe-value was returned, the same probe-value can be returned. Otherwise a new value needs to be returned. Generation id zero is special, it means that caching is not currently enabled.
When sampling is finished the probe_sampler calls the disable which will cause the generation id zero to be returned until the next sample begins again.
Global Context for all methods.
probe_subscribe — subscribe and unsubscribe to a probe
#include <simics/simulator-iface/probe-interface.h> // in C
import "simics/simulator-iface/probe-interface.dml"; // in DML
SIM_INTERFACE(probe_subscribe) {
void (*subscribe)(conf_object_t *obj);
void (*unsubscribe)(conf_object_t *obj);
int (*num_subscribers)(conf_object_t *obj);
};
#define PROBE_SUBSCRIBE_INTERFACE "probe_subscribe"
import simics
class simics.probe_subscribe_interface_t(subscribe=None, unsubscribe=None,
num_subscribers=None)
This is an optional additional probe interface. This interface should be implemented to prevent any slowdown or unwanted side-effects if there are no listener on the probe. The subscribe() method should increment a reference count on how many subscribers there are, and do any kind of preparation to activate the probe when it is being used.
Similarly, the unsubscribe() method should decrement the reference count and disable the feature when there is no subscribers left.
The num_subscribers() method should return the current reference count.
Global Context for all methods.
recorder_v2 — interfaces used to help with recording of external interactions
#include <simics/simulator-iface/recorder.h> // in C
import "simics/simulator-iface/recorder.dml"; // in DML
SIM_INTERFACE(recorder_v2) {
void (*record)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL sender, bytes_t data);
bool (*playback)(conf_object_t *NOTNULL obj);
};
#define RECORDER_V2_INTERFACE "recorder_v2"
import simics
class simics.recorder_v2_interface_t(record=None, playback=None)
The recorder_v2 interface is implemented by the recorder, and can be used by any object interacting with the outside world in order to make re-runs of the same simulation behave identically. This is a requirement for reverse execution to work. Objects using this interface must implement the recorded interface themselves.
An object uses it by calling the record method with itself and the data it wishes to record as parameters. The recorder will then save the data and call the input method in the recorded interface on the object.
The playback method returns whether the recorder is currently playing back recorded data. It may be used by the object to determine if output to the outside world should be dropped or not.
The recorded interface is implemented by objects that wish to use the recorder_v2 interface.
The input method is called with data that has been recorded. The playback parameter is set if the data came from a previous recording, and clear if the data came directly from a call to record in recorder_v2 with live data.
Cell Context
screenshot — interface used with graphics console
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(screenshot) {
bool (*save_png)(conf_object_t *NOTNULL obj, const char *filename);
bool (*save_bmp)(conf_object_t *NOTNULL obj, const char *filename);
};
#define SCREENSHOT_INTERFACE "screenshot"
import simics
class simics.screenshot_interface_t(save_png=None, save_bmp=None)
The screenshot interface facilitates storing screenshots. It is implemented by the graphics console.
All screenshots store current screen data, using 24-bit RGB pixel format.
Global Context
serial_console_frontend — interface for serial console communication
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(serial_console_frontend) {
void (*write)(conf_object_t *NOTNULL obj, uint8 value);
};
#define SERIAL_CONSOLE_FRONTEND_INTERFACE "serial_console_frontend"
import simics
class simics.serial_console_frontend_interface_t(write=None)
The serial_console_frontend interface can be implemented by devices that want to retrieve the character stream passing through the text console. Objects implementing this interface can be attached to a text console and will receive output in the same way as a telnet connection.
Cell Context
table_key_t, column_key_t, extra_header_key_t, table — interface to help present table data
#include <simics/simulator-iface/table.h> // in C
import "simics/simulator-iface/table.dml"; // in DML
typedef enum {
/* Table property keys */
Table_Key_Name = 1,
Table_Key_Description,
Table_Key_Default_Sort_Column,
Table_Key_Columns,
Table_Key_Extra_Headers,
Table_Key_Stream_Header_Repeat,
/* Additional properties might be added in the future.
Thus, unknown values should be silently ignored. */
} table_key_t;
typedef enum {
/* Column property keys */
Column_Key_Name = 1000, /* Other number series than table-keys */
Column_Key_Description,
Column_Key_Alignment,
Column_Key_Int_Radix,
Column_Key_Float_Percent,
Column_Key_Float_Decimals,
Column_Key_Sort_Descending,
Column_Key_Hide_Homogeneous,
Column_Key_Generate_Percent_Column,
Column_Key_Generate_Acc_Percent_Column,
Column_Key_Footer_Sum,
Column_Key_Footer_Mean,
Column_Key_Int_Grouping,
Column_Key_Int_Pad_Width,
Column_Key_Metric_Prefix,
Column_Key_Binary_Prefix,
Column_Key_Time_Format,
Column_Key_Unique_Id,
Column_Key_Width,
Column_Key_Word_Delimiters,
/* Additional properties might be added in the future.
Thus, unknown values should be silently ignored. */
} column_key_t;
typedef enum {
/* Header property keys */
Extra_Header_Key_Row = 2000,
Extra_Header_Key_Name,
Extra_Header_Key_Description,
Extra_Header_Key_First_Column,
Extra_Header_Key_Last_Column,
} extra_header_key_t;
SIM_INTERFACE(table) {
/* Returns all rows and columns in the following format:
[[[i|f|s|o|n*]*]] where the outer list is the row
and the inner list is the data for each column. */
attr_value_t (*data)(conf_object_t *obj);
/* Defines the table structure and meta-data for the table
using a list of key/value pairs.
[[[ia]*]*] where the integer is the key taken from the
table_properties_t. The value is key-specific. */
attr_value_t (*properties)(conf_object_t *obj);
};
#define TABLE_INTERFACE "table"
import simics
simics.Table_Key_Description
simics.Table_Key_Extra_Headers
simics.Table_Key_Stream_Header_Repeat
simics.Table_Key_Columns
simics.Table_Key_Name
simics.Table_Key_Default_Sort_Column
simics.Column_Key_Name
simics.Column_Key_Time_Format
simics.Column_Key_Width
simics.Column_Key_Metric_Prefix
simics.Column_Key_Generate_Acc_Percent_Column
simics.Column_Key_Alignment
simics.Column_Key_Int_Pad_Width
simics.Column_Key_Generate_Percent_Column
simics.Column_Key_Int_Radix
simics.Column_Key_Sort_Descending
simics.Column_Key_Footer_Sum
simics.Column_Key_Word_Delimiters
simics.Column_Key_Hide_Homogeneous
simics.Column_Key_Float_Percent
simics.Column_Key_Int_Grouping
simics.Column_Key_Float_Decimals
simics.Column_Key_Description
simics.Column_Key_Binary_Prefix
simics.Column_Key_Footer_Mean
simics.Column_Key_Unique_Id
simics.Extra_Header_Key_Description
simics.Extra_Header_Key_First_Column
simics.Extra_Header_Key_Last_Column
simics.Extra_Header_Key_Name
simics.Extra_Header_Key_Row
class simics.table_interface_t(data=None, properties=None)
The table interface can be implemented by objects holding data which can be presented in a table by the user interface (through Simics CLI command outputs, Eclipse etc.)
By properly implementing the table interface, less object specific code is needed to provide the data to the user. Generic Simics commands (associated with the table interface) allows the data to sorted on the desired column and printed in a uniform way. Similarly, the data can be exported to a comma separated value (.csv) file, making it possible to process the result in a spreadsheet program.
The data method returns the data as an attr_value_t array where the outer list contains each row and the inner list contains the columns for that row. The number of columns in each row must be exactly the same. The data only holds the actual data, not the headers for each column, which instead is specified in the properties method. The data can be unsorted, it is up to the user of the interface to sort it in a suitable way.
The data itself is sufficient for producing a table, but to customize the table layout the properties method can return hints on how the table should be presented more in detail. For example, specifying which column the table should be sorted on by default, or if a column preferably should be printed with hexadecimal numbers instead of decimals. In addition, the properties also contains the name of the columns as well as additional meta-data such as what each column represents, or what the entire table represents.
The properties also returns an attr_value_t type as a list of key/value pairs. Thus, each list-entry should be exactly two elements long, but the value part can itself be a new list of key/value pairs for some keys.
The table property keys are of table_key_t type.
This is the definition for each table property:
Table_Key_Name StringTable_Key_Description StringTable_Key_Default_Sort_Column StringTable_Key_Extra_Headers List of additional header rowsThe format is: list of additional header rows, each identified as a Extra_Header_Key_Row. Each row is defined by a list of the header-elements where each element is a list of the header’s key/value pair properties.
The header property keys are of extra_header_key_t type.
Extra_Header_Key_Row List of header elementsExtra_Header_Key_Name StringExtra_Header_Key_Description StringExtra_Header_Key_First_Column StringExtra_Header_Key_Last_Column StringIf there is only one header element on a row, and neither Extra_Header_Key_First_Column and Extra_Header_Key_Last_Column are set, the header will span the entire table, even if additional columns has been added by the system. In all other cases first/last column always needs to be specified.
Table_Key_Columns List of columns, with key/value pairsThe column property keys are of column_key_t type.
This is the definition for each column property:
Column_Key_Name StringColumn_Key_Description StringColumn_Key_Alignment String: [“left”, “right”, “center”]Column_Key_Word_Delimiters String" -_:,.".Column_Key_Int_Radix Integer: [2,10,16]output-radix command.Column_Key_Int_Grouping Booleanoutput-radix command.Column_Key_Pad_Width IntegerColumn_Key_Float_Percent BooleanColumn_Key_Float_Decimals IntegerColumn_Key_Metric_Prefix StringColumn_Key_Binary_Prefix StringColumn_Key_Time_Format BooleanHH:MM:SS.ss, where only the used parts are shown. The number of seconds decimals formatted is can be controlled by Column_Key_Float_Decimals property. To compact the width, decimals are dropped when hours are displayed.Column_Key_Unique_Id StringColumn_Key_Sort_Descending BooleanColumn_Key_Hide_Homogeneous Integer/Float/StringColumn_Key_Footer_Mean Boolean If True, an arithmetic mean of the column values are calculated and displayed in a footer row, below the actual table.
Column_Key_Generate_Percent_Column List of key/value pairs for new column.Column_Key_Generate_Acc_Percent_Column List of key/value pairs for new column.Global Context
telnet_connection_v2 — interface used to control the telnet server
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(telnet_connection_v2) {
bool (*listening)(conf_object_t *NOTNULL obj);
bool (*connected)(conf_object_t *NOTNULL obj);
void (*disconnect)(conf_object_t *NOTNULL obj);
};
#define TELNET_CONNECTION_V2_INTERFACE "telnet_connection_v2"
import simics
class simics.telnet_connection_v2_interface_t(listening=None, connected=None,
disconnect=None)
The telnet_connection_v2 interface is used to control the text console telnet server.
The text console has a built-in telnet server.
The listening method indicates whether the server is listening for connections.
The connected method indicates whether there is a connected telnet client.
The disconnect method forcibly disconnects any connected client.
Global Context
vnc_server_v2 — interface used to control the vnc server
#include <simics/simulator-iface/consoles.h> // in C
import "simics/simulator-iface/consoles.dml"; // in DML
SIM_INTERFACE(vnc_server_v2) {
bool (*listening)(conf_object_t *NOTNULL obj);
int (*num_clients)(conf_object_t *NOTNULL obj);
void (*disconnect)(conf_object_t *NOTNULL obj);
};
#define VNC_SERVER_V2_INTERFACE "vnc_server_v2"
import simics
class simics.vnc_server_v2_interface_t(listening=None, num_clients=None,
disconnect=None)
The vnc_server_v2 interface is used to control the graphics console VNC server.
The graphics console has a built-in VNC server, supporting any number of connected clients.
The listening method indicates whether the server is listening for connections.
The num_clients method returns the number of connected clients.
The disconnect method forcibly disconnects any connected client.
Global Context