SIM_attribute_error, SIM_c_attribute_error — specify reason for attribute error
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_attribute_error(const char *NOTNULL msg);
void
SIM_c_attribute_error(const char *NOTNULL msg, ...);
import simics
simics.SIM_attribute_error(...)
When used inside an attribute set_attr/get_attr method, indicates why it failed to set or retrieve the attribute. This function only serves to give an informative message to the user. The object or attribute names need not be mentioned in the msg argument; Simics will supply this automatically. SIM_c_attribute_error is similar but the msg argument and those following it are used for string formatting in the same way as in the standard sprintf function. This function is not available from Python.
The error message supplied will be attached to any frontend exception generated by the attribute access.
Cell Context
SIM_register_attribute, SIM_get_attribute, SIM_set_attribute
SIM_class_port — check if class has specified port object
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
conf_class_t *
SIM_class_port(const conf_class_t *NOTNULL cls, const char *NOTNULL name);
import simics
simics.SIM_class_port(...)
Returns the class of objects on the port named name, or nullptr if no such port is registered.
SIM_register_port, SIM_register_simple_port
Cell Context
SIM_copy_class — create a copy of an existing class
#include <simics/device-api.h> // in C
// always available in DML
conf_class_t *
SIM_copy_class(const char *NOTNULL name, const conf_class_t *NOTNULL src_cls,
const char *desc);
import simics
simics.SIM_copy_class(...)
This function creates a copy of the class src_class named name.
Additional attributes and interfaces can be registered on the newly created class.
The new class is described by desc unless this parameter is nullptr which means that the original class description should be used.
The newly created class is returned.
SIM_extend_class, SIM_create_class
Global Context
SIM_create_class — create class
#include <simics/device-api.h> // in C
// always available in DML
conf_class_t *
SIM_create_class(const char *NOTNULL name,
const class_info_t *NOTNULL class_info);
import simics
simics.SIM_create_class(...)
This function creates a new class that can be instantiated by calling the SIM_create_object function. It is a replacement for SIM_register_class and should be used in all new code.
The name can contain upper and lower case ASCII letters, hyphens, underscores, and digits. It must not begin with a digit or a hyphen and must not end with a hyphen.
class_info may be freed when the function has returned.
Class structure, or NULL on error.
Global Context
SIM_ensure_partial_attr_order — ensure attribute order
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_ensure_partial_attr_order(conf_class_t *NOTNULL cls,
const char *NOTNULL before,
const char *NOTNULL after);
import simics
simics.SIM_ensure_partial_attr_order(...)
Attribute initialization order is guaranteed to be identical to the order in which the attributes were registered. In some cases a particular order is required in order for a model to work correctly.
This function checks the registration order of the attributes before and after in the class cls. If before is not registered before after, or if at least one of the two are not registered at all, an ASSERT is triggered.
Use this function to ensure that e.g. code refactoring does not break a required attribute order.
Cell Context
SIM_extend_class — extend class with contents from an extension class
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_extend_class(conf_class_t *NOTNULL cls, conf_class_t *NOTNULL ext);
import simics
simics.SIM_extend_class(...)
The function extends the class cls with attributes, interfaces, port objects and port interfaces defined by the extension class ext.
The extension class must be of the type Sim_Class_Kind_Extension and must not define any attributes or interfaces which have already been defined by the class being augmented.
Besides normal object initialization, the init_object method for the extension class, will be called when cls is instantiated. The pointer returned by init_object can be retrieved using SIM_extension_data. The init_object method may return nullptr if no private data pointer is needed; this does not signify an error condition for extension classes.
The finalize_instance method defined by the extension class will be called before the finalize_instance method is called for the class being extended.
The SIM_extend_class function is intended to be used to extend a class with generic functionality, common to multiple classes.
SIM_create_class, SIM_register_class, SIM_extension_data
Global Context
SIM_extension_data — get class extension data
#include <simics/device-api.h> // in C
// always available in DML
void *
SIM_extension_data(conf_object_t *obj, conf_class_t *ext_cls);
import simics
simics.SIM_extension_data(...)
Returns the private data pointer of an object associated with the extension class ext_cls. The returned pointer is the value returned by the init_object method called for the extension class ext_cls.
The object obj must be an instance of a class which has been extended with the extension class ext_cls using the SIM_extend_class function.
SIM_object_data, SIM_register_class, SIM_extend_class
Cell Context
SIM_get_class, conf_class_t — get class
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
conf_class_t *
SIM_get_class(const char *NOTNULL name);
#include <simics/device-api.h> // in C
// always available in DML
typedef struct conf_class conf_class_t;
import simics
simics.SIM_get_class(...)
class simics.conf_class_t
Returns the configuration class called name.
If it finds no class called name, SIM_get_class will load a module implementing that class, if any can be found, and return the newly created class.
Note that loading a module can not be done during the simulation execution: in that case, SIM_get_class will trigger an error instead. If you encounter this problem, a simple work-around is to make sure that all necessary modules are loaded before starting the execution.
Opaque pointer referencing the class, or nullptr if not found.
SimExc_General Thrown if the class has not been registered.
Cell Context, except when loading a module.
SIM_get_class_data — get class data
#include <simics/device-api.h> // in C
// always available in DML
lang_void *
SIM_get_class_data(conf_class_t *cls);
import simics
simics.SIM_get_class_data(...)
Obtain the class data that was set using SIM_set_class_data. This can be called at any time during the object initialisation process.
Cell Context
SIM_get_class_name — get class name
#include <simics/device-api.h> // in C
// always available in DML
const char *
SIM_get_class_name(const conf_class_t *NOTNULL class_data);
import simics
simics.SIM_get_class_name(...)
Returns the name of the class. Simics retains ownership of the returned string; it must not be modified or freed by the caller.
In Python, the name of an object’s class is available via the classname attribute:
obj.classname
Cell Context
SIM_get_interface — get interface
#include <simics/device-api.h> // in C
// always available in DML
const void *
SIM_get_interface(const conf_object_t *NOTNULL obj, const char *NOTNULL name);
const void *
SIM_c_get_interface(const conf_object_t *NOTNULL obj, const char *NOTNULL name);
const void *
SIM_get_class_interface(const conf_class_t *NOTNULL cls,
const char *NOTNULL name);
const void *
SIM_c_get_class_interface(const conf_class_t *NOTNULL cls,
const char *NOTNULL name);
const void *
SIM_get_port_interface(const conf_object_t *NOTNULL obj,
const char *NOTNULL name, const char *portname);
const void *
SIM_c_get_port_interface(const conf_object_t *NOTNULL obj,
const char *NOTNULL name,
const char *portname);
const void *
SIM_get_class_port_interface(const conf_class_t *NOTNULL cls,
const char *NOTNULL name,
const char *portname);
const void *
SIM_c_get_class_port_interface(const conf_class_t *NOTNULL cls,
const char *NOTNULL name,
const char *portname);
// not available in DML
SIM_C_GET_INTERFACE(obj, name);
SIM_C_GET_PORT_INTERFACE(obj, name, port);
SIM_C_GET_CLASS_INTERFACE(cls, name);
import simics
simics.SIM_get_interface(...)
simics.SIM_c_get_interface(...)
simics.SIM_get_class_interface(...)
simics.SIM_c_get_class_interface(...)
simics.SIM_get_port_interface(...)
simics.SIM_c_get_port_interface(...)
simics.SIM_get_class_port_interface(...)
simics.SIM_c_get_class_port_interface(...)
Get the interface with name name from object obj. Returns nullptr, and raises an exception if obj does not implement the interface.
SIM_get_port_interface returns a port interface instance as registered with SIM_register_port_interface. The portname selects a particular implementation of the interface by obj’s class. If no port name is supplied, the function behaves as SIM_get_interface.
SIM_get_class_interface and SIM_get_class_port_interface are similar but return the interface for a class instead of an object.
SIM_c_get_interface, SIM_c_get_port_interface, SIM_c_get_class_interface and SIM_c_get_class_port_interface are similar to their respective counterparts but never raise an exception, nor do they accept dashes inside name or portname instead of underscores.
The SIM_C_GET_INTERFACE macro is a useful type-safe replacement for SIM_c_get_interface. The macro takes an object and the name of the interface without quotes. Compare the three forms:
SIM_c_get_interface(obj, PCI_DEVICE_INTERFACE);
SIM_c_get_interface(obj, "pci_device");
SIM_C_GET_INTERFACE(obj, pci_device);
The data the result points to is owned by Simics. The caller must not deallocate or modify it.
In Python, there is usually no need to use these functions since Simics objects’ interfaces are available via the iface attribute. Here is sample Python code calling the signal_raise method of the object’s signal interface:
obj.iface.signal.signal_raise()
In a similar way one can call interfaces of an object’s port objects. Here is a respective example where an object obj with a port object obj.port.reset has a signal interface:
obj.port.reset.iface.signal.signal_raise()
Port interfaces - interfaces that are registered with SIM_register_port_interface and are considered legacy - are also directly accessible in Python. Here is sample code calling the signal_raise method of the signal interface from the object’s RESET port:
obj.ports.RESET.signal.signal_raise()
In order to check if a Simics object implements an interface the following Python code can be used:
if hasattr(obj.iface, "signal"): # check whether obj has signal interface
...
Pointer to interface, or nullptr if not found.
SimExc_Lookup Thrown if the interface is not implemented by obj’s class.
SimExc_General Thrown if the interface name is illegal.
All contexts (including Threaded Context)
SIM_is_restoring_state — check if state restoring phase
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_is_restoring_state(conf_object_t *obj);
import simics
simics.SIM_is_restoring_state(...)
Returns true if the configuration system is currently restoring the saved state for the object obj when reading a checkpoint, applying a persistent state or restoring a snapshot.
SIM_is_restoring_state is typically used to prevent side effects in attribute set methods that only should run when the attribute is set manually, for example when hot plugging.
| SIM_object_is_configured | SIM_is_restoring_state | |
|---|---|---|
| Creating object | false | false |
| Loading checkpoint | false | true |
| Loading persistent state | true | true |
| Loading snapshot | true | true |
| Manual attribute access (hot plug) | true | false |
LIMITATION: This function currently returns true for all objects in Simics while some state is being restored and not only for the affected objects.
Cell Context
SIM_marked_for_deletion — is object being deleted
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_marked_for_deletion(const conf_object_t *NOTNULL obj);
import simics
simics.SIM_marked_for_deletion(...)
Indicates if the given object is being deleted. This information can be useful by other objects that want to clean up their references.
true if the object is being deleted.
Global Context
SIM_object_clock — get object clock
#include <simics/device-api.h> // in C
// always available in DML
conf_object_t *
SIM_object_clock(const conf_object_t *NOTNULL obj);
import simics
simics.SIM_object_clock(...)
Retrieve the default clock used by an object. This is either set by the queue attribute, or inherited from the default clock of the object’s parent. The default clock is used as time reference for the object.
All contexts (including Threaded Context)
SIM_object_data — get object-specific data pointer
#include <simics/device-api.h> // in C
// always available in DML
lang_void *
SIM_object_data(conf_object_t *NOTNULL obj);
import simics
simics.SIM_object_data(...)
Returns the private data pointer of an object. This pointer is available to the class for storing instance-specific state.
It is initialised to the return value of the init (from class_info_t) method that is called during object creation. For classes created using the legacy SIM_register_class, the same functionality is provided by the `init_object method .
For classes implemented in Python, the data (which is then a Python value) can also be accessed as obj.object_data.
For classes written in C, the preferred way to store instance-specific state is by co-allocation with the object’s conf_object_t structure instead of using SIM_object_data. Such classes should define the alloc method in the class_info_t passed to SIM_create_class for allocating its instance data. For classes using the legacy SIM_register_class class registration function, they should define the alloc_object method in the class_data_t data structure.
SIM_create_class, SIM_register_class
All contexts (including Threaded Context)
SIM_object_id — get object identifier
#include <simics/device-api.h> // in C
// always available in DML
const char *
SIM_object_id(const conf_object_t *NOTNULL obj);
import simics
simics.SIM_object_id(...)
Returns the unique identifier for an object. The identifier is a string that is guaranteed to be unique and will never change, even if the object moves to another hierarchical location.
The return value is a static string that should not be modified or freed by the caller.
All contexts (including Threaded Context)
SIM_object_is_configured, SIM_set_object_configured — get/set configured status
#include <simics/device-api.h> // in C
// always available in DML
bool
SIM_object_is_configured(const conf_object_t *NOTNULL obj);
void
SIM_set_object_configured(conf_object_t *NOTNULL obj);
import simics
simics.SIM_object_is_configured(...)
simics.SIM_set_object_configured(...)
SIM_object_is_configured indicates whether obj is configured. SIM_set_object_configured sets the object as configured.
An object is configured once its finalize_instance method (post_init in DML) has completed, or SIM_set_object_configured has been called for it. Being configured indicates that the object is in a consistent state and is ready to be used by other objects.
SIM_set_object_configured is used to avoid circular dependencies between objects. It may only be called from the object’s own finalize_instance method, when the object is known to be in a consistent state.
SIM_object_is_configured: all contexts (including Threaded Context);SIM_set_object_configured: Global ContextSIM_require_object, SIM_register_class, SIM_is_restoring_state
SIM_object_name — get object name
#include <simics/device-api.h> // in C
// always available in DML
const char *
SIM_object_name(const conf_object_t *NOTNULL obj);
import simics
simics.SIM_object_name(...)
Returns the name of an object. This name identifies the object uniquely, but may change if the object is moved to another hierarchical location.
The return value is a string, owned by obj, that should not be modified or freed by the caller.
In Python, an object’s name is available via the name attribute:
obj.name
All contexts (including Threaded Context)
SIM_picosecond_clock — get object picosecond clock
#include <simics/device-api.h> // in C
// always available in DML
conf_object_t *
SIM_picosecond_clock(conf_object_t *NOTNULL obj);
import simics
simics.SIM_picosecond_clock(...)
Return the picosecond clock used by an object obj.
The returned clock uses a cycle period of exactly 1 ps. It has full picosecond resolution even if the processor (or clock) driving the simulation uses a lower resolution. An event posted at a particular picosecond triggers always at that precise time, without any rounding issues.
The returned object is the vtime.ps port object of the default clock for the object, and it implements the cycle_event interface.
The API functions SIM_event_post_cycle, SIM_event_post_time, SIM_event_find_next_cycle, SIM_event_cancel_time, and SIM_cycle_count can be used directly on the picosecond clock.
The function
SIM_timeis currently not supported for the picosecond clock; it will return same value as if the function is invoked on the default clock.
The picosecond clock will wrap around after roughly 200 days of virtual time (2^64 ps).
All contexts (including Threaded Context)
SIM_register_attribute, SIM_register_class_attribute, SIM_register_attribute_with_user_data, SIM_register_class_attribute_with_user_data — register attribute
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_register_attribute(
conf_class_t *NOTNULL cls, const char *NOTNULL name,
attr_value_t (*get_attr)(conf_object_t *),
set_error_t (*set_attr)(conf_object_t *, attr_value_t *),
attr_attr_t attr, const char *type, const char *desc);
void
SIM_register_class_attribute(
conf_class_t *NOTNULL cls, const char *NOTNULL name,
attr_value_t (*get_attr)(conf_class_t *),
set_error_t (*set_attr)(conf_class_t *, attr_value_t *),
attr_attr_t attr, const char *type, const char *desc);
void
SIM_register_attribute_with_user_data(
conf_class_t *NOTNULL cls, const char *NOTNULL name,
attr_value_t (*get_attr)(conf_object_t *, lang_void *),
lang_void *user_data_get,
set_error_t (*set_attr)(conf_object_t *, attr_value_t *, lang_void *),
lang_void *user_data_set,
attr_attr_t attr, const char *type, const char *desc);
void
SIM_register_class_attribute_with_user_data(
conf_class_t *NOTNULL cls, const char *NOTNULL name,
attr_value_t (*get_attr)(conf_class_t *, lang_void *),
lang_void *user_data_get,
set_error_t (*set_attr)(conf_class_t *, attr_value_t *, lang_void *),
lang_void *user_data_set,
attr_attr_t attr, const char *type, const char *desc);
import simics
simics.SIM_register_attribute(...)
simics.SIM_register_class_attribute(...)
simics.SIM_register_attribute_with_user_data(...)
simics.SIM_register_class_attribute_with_user_data(...)
Add the attribute name to the set of attributes of the class cls.
For SIM_register_attribute and SIM_register_class_attribute, the function get_attr is called with the object as argument, and returns the current value of the attribute. For SIM_register_attribute_with_user_data and SIM_register_class_attribute_with_user_data, the function get_attr takes an additional user data argument, which takes the value passed as user_data_get.
On error, get_attr should call SIM_attribute_error. The return value is then ignored; typically, SIM_make_attr_invalid is used to generate an explicitly invalid value.
If get_attr is a null pointer, the attribute will be write-only.
For SIM_register_attribute and SIM_register_class_attribute, the function set_attr is called with the object as argument. For SIM_register_attribute_with_user_data and SIM_register_class_attribute_with_user_data, the function set_attr takes an additional user data argument, which takes the value passed as user_data_set. The set_attr function is called when the attribute is initialised or changed. The argument value is owned by the caller, so any data from it must be copied.
The set_attr method should return Sim_Set_Ok if the new value could be set. On error, it should return an appropriate error code (usually Sim_Set_Illegal_Value), and optionally call SIM_attribute_error with an explanatory message.
If set_attr is a null pointer, the attribute will be read-only.
The attr parameter is one of Sim_Attr_Required, Sim_Attr_Optional or Sim_Attr_Pseudo.
Attributes marked Sim_Attr_Required or Sim_Attr_Optional are saved in checkpoints. Both set_attr and get_attr must be non-null for such attributes.
All attributes that are marked Sim_Attr_Required must be present in all configurations.
The set of permitted values is encoded in the string type.
The type strings are composed as follows:
Most types are represented by a single letter:
| Type | |
|---|---|
i | integer |
f | floating-point |
s | string |
b | boolean |
o | object |
d | data |
n | nil |
D | dictionary |
a | any type |
The | (vertical bar) operator specifies the union of two types; eg, s|o is the type of a string or an object.
Lists are defined inside square brackets: []. There are two kinds of list declarations:
A heterogeneous list of fixed length is defined by the types of its elements. For example, [ios] specifies a 3-element list consisting of an integer, an object and a string, in that order.
A homogeneous list of varying length is defined by a single type followed by a length modifier:
| Modifier | Description |
|---|---|
{N:M} | between N and M elements, inclusive |
{N} | exactly N elements |
* | zero or more elements |
+ | one or more elements |
For example, [i{3,5}] specifies a list of 3, 4 or 5 integers.
Inside heterogeneous lists, | (union) has higher precedence than juxtaposition; ie, [i|so|n] defines a list of two elements, the first being an integer or a string and the second an object or NIL.
SIM_register_class_attribute and SIM_register_class_attribute_with_user_data will register a class attribute. Class attributes are the same for all instances of the class.
Global Context
SIM_register_class — register class
#include <simics/device-api.h> // in C
// always available in DML
conf_class_t *
SIM_register_class(const char *NOTNULL name,
const class_data_t *NOTNULL class_data);
import simics
simics.SIM_register_class(...)
This function is considered legacy. New code should use the SIM_create_class function to create new classes in the Simics simulator.
The function registers a new class that can be instantiated by calling the SIM_create_object function.
The name can contain upper and lower case ASCII letters, hyphens, underscores, and digits. It must not begin with a digit or a hyphen and must not end with a hyphen.
class_data may be freed when the function has returned.
Class structure, or nullptr on error.
Global Context
SIM_register_class_alias — register class alias
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_register_class_alias(const char *NOTNULL alias, const char *NOTNULL name);
import simics
simics.SIM_register_class_alias(...)
Register an alias alias for the existing class class_name. Using aliases allows the read-configuration command to read configuration files that define objects of type alias, while the write-configuration command always uses class_name.
Aliases are used to support compatibility with old class names if a class is renamed. They can also be used to allow different modules, which define different specific implementations of the same generic base class, to read the same configuration files.
SIM_create_class, SIM_register_class
Global Context
SIM_register_clock — register mandatory interface and attributes for clock objects
#include <simics/device-api.h> // in C
// always available in DML
int
SIM_register_clock(conf_class_t *NOTNULL cls,
const cycle_interface_t *NOTNULL iface);
import simics
simics.SIM_register_clock(...)
Register the cls class as a class for schedulable clock objects. This includes registering the cycle interface (iface), in addition to which SIM_register_clock registers the cell attribute required for scheduling the clock and some other Simics specific attributes. Simics will be able to schedule objects instantiated from the class cls.
The return value is 0 if everything works, and non-zero if something fails. Depending on the stage that failed, SIM_register_clock() will return the error value provided by SIM_register_interface().
Returns non-zero on failure, 0 otherwise.
SimExc_General Thrown if the cycle interface has already been registered for this class.
Global Context
SIM_register_compatible_interfaces — register earlier versions of interface
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_register_compatible_interfaces(conf_class_t *NOTNULL cls,
const char *NOTNULL name);
import simics
simics.SIM_register_compatible_interfaces(...)
Register any earlier versions of the interface name for class cls. The interface name must already be registered for the class.
When supported, this function lets a module implement a single version of an interface while still exporting earlier versions.
The following interfaces are currently accepted by this function, with the additional interfaces that are exported given in parenthesis: BREAKPOINT_QUERY_V2 (no interfaces), PROCESSOR_INFO_V2 (PROCESSOR_INFO).
SimExc_General Thrown if no interface is registered with the given name, if compatible versions of the interface have already been registered, or if the interface does not have any earlier versions that this function knows about.
Global Context
SIM_register_interface — register interface
#include <simics/device-api.h> // in C
// always available in DML
int
SIM_register_interface(conf_class_t *NOTNULL cls, const char *NOTNULL name,
const void *NOTNULL iface);
int
SIM_register_port_interface(conf_class_t *NOTNULL cls,
const char *NOTNULL name,
const void *NOTNULL iface,
const char *NOTNULL portname,
const char *desc);
// not available in DML
SIM_REGISTER_INTERFACE(cls, name, iface);
SIM_REGISTER_PORT_INTERFACE(cls, name, iface, portname, desc);
import simics
simics.SIM_register_interface(...)
simics.SIM_register_port_interface(...)
Register that cls implements the name interface. The interface itself should be supplied in the iface argument.
SIM_register_port_interface registers a port instance of an interface that must be looked up using SIM_get_port_interface. The portname parameter is the name of the port. The port name may not be the same as any attribute name used by the class. A short description of the port is provided with the desc parameter and should be identical for all interfaces for a port. These two functions are considered legacy. New code should use SIM_register_port and SIM_register_interface instead.
The data iface points to must not be deallocated or overwritten by the caller. Simics will use that data to store the interface structure. It will never be freed or written to by Simics.
Returns non-zero on failure, 0 otherwise.
SimExc_General Thrown if the interface name is illegal, or if this interface has already been registered for this class.
Global Context
SIM_register_port — register port class
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_register_port(conf_class_t *NOTNULL cls, const char *NOTNULL name,
conf_class_t *NOTNULL port_cls, const char *desc);
import simics
simics.SIM_register_port(...)
Add a port named name of class port_cls to the set of ports defined by the class cls.
The result of this is that whenever an object of class cls is created, Simics will automatically create a port object of class port_cls. The name of the port object is created by appending . followed by the name string to the parent object’s name.
If the port name contains dots or brackets, then intermediate port objects are registered as well. For instance, the port name x.array[2] will implicitly register ports x of class namespace, and x.array of class index-map.
Each port name may be registered at most once in a class. One exception is namespace classes: If the port is registered once as class namespace and once as some other class, then the namespace registration is dropped. Also, if a port is registered twice as class index-map, or twice as class namespace, then the second registration is dropped.
Global Context
SIM_register_simple_port — register port
#include <simics/device-api.h> // in C
// always available in DML
conf_class_t *
SIM_register_simple_port(conf_class_t *NOTNULL cls, const char *NOTNULL name,
const char *desc);
import simics
simics.SIM_register_simple_port(...)
Add a port named name to the set of ports defined by the class cls. The port will be an instance of a class named "parent_class_name.portname" where portname is the specified name of the port with leading namespaces omitted and any array indices removed. The port class is created if it does not exist already.
The port class is returned.
Global Context
SIM_register_sub_object — register sub-object
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_register_sub_object(conf_class_t *NOTNULL parent,
const char *NOTNULL name,
conf_class_t *NOTNULL cls,
sub_object_flags_t flags,
const char * description);
import simics
simics.SIM_register_sub_object(...)
Add a sub-object named name of class cls to the set of ports defined by the class parent.
The result of this is that whenever an object of class parent is created, Simics will automatically create a sub-object of class cls. The name of the sub-object is created by appending . followed by the name string to the parent object’s name.
If the sub-object name contains dots or brackets, then intermediate namespace objects are registered as well. For instance, the sub-object name x.array[2] will implicitly register sub-object x of class namespace, and x.array of class index-map.
Each sub-object name may be registered at most once in a class. One exception is namespace classes: If the sub-object is registered once as class namespace and once as some other class, then the namespace registration is dropped. Also, if a port is registered twice as class index-map, or twice as class namespace, then the second registration is dropped.
The flags parameter controls the behaviour of the sub-object.
This API function supersedes the SIM_register_port function.
SIM_register_port, sub_object_flags_t
Global Context
SIM_register_typed_attribute, SIM_register_typed_class_attribute — register attribute
#include <simics/device-api.h> // in C
// always available in DML
int
SIM_register_typed_attribute(
conf_class_t *NOTNULL cls, const char *NOTNULL name,
attr_value_t (*get_attr)(lang_void *user_data,
conf_object_t *obj,
attr_value_t *idx),
lang_void *user_data_get,
set_error_t (*set_attr)(lang_void *user_data,
conf_object_t *obj,
attr_value_t *val, attr_value_t *idx),
lang_void *user_data_set,
attr_attr_t attr, const char *type, const char *idx_type,
const char *desc);
int
SIM_register_typed_class_attribute(
conf_class_t *NOTNULL cls, const char *NOTNULL name,
attr_value_t (*get_attr)(lang_void *ptr,
conf_class_t *c,
attr_value_t *idx),
lang_void *user_data_get,
set_error_t (*set_attr)(lang_void *ptr,
conf_class_t *c,
attr_value_t *val,
attr_value_t *idx),
lang_void *user_data_set,
attr_attr_t attr, const char *type, const char *idx_type,
const char *desc);
import simics
simics.SIM_register_typed_attribute(...)
simics.SIM_register_typed_class_attribute(...)
The functions
SIM_register_typed_attributeandSIM_register_typed_class_attributeare legacy. New code should useSIM_register_attributeorSIM_register_class_attribute.
Add the attribute name to the set of attributes of the class cls.
The function get_attr is called with the object and the value from user_data_get as arguments, and returns the current value of the attribute.
On error, get_attr should call SIM_attribute_error. The return value is then ignored; typically, SIM_make_attr_invalid is used to generate an explicitly invalid value.
If get_attr is a null pointer, the attribute will be write-only.
The function set_attr is called with the object and the value from user_data_set as arguments when the attribute is initialised or changed. The argument value is owned by the caller, so any data from it must be copied.
The set_attr method should return Sim_Set_Ok if the new value could be set. On error, it should return an appropriate error code (usually Sim_Set_Illegal_Value), and optionally call SIM_attribute_error with an explanatory message.
If set_attr is a null pointer, the attribute will be read-only.
The attr parameter is one of Sim_Attr_Required, Sim_Attr_Optional or Sim_Attr_Pseudo.
Attributes marked Sim_Attr_Required or Sim_Attr_Optional are saved in checkpoints. Both set_attr and get_attr must be non-null for such attributes.
All attributes that are marked Sim_Attr_Required must be present in all configurations.
The set of permitted values is encoded in the string type, and in idx_type for values during indexed access. A nullptr value for either type string means that values of any type are permitted.
The type strings are composed as follows:
Most types are represented by a single letter:
| Type | |
|---|---|
i | integer |
f | floating-point |
s | string |
b | boolean |
o | object |
d | data |
n | nil |
D | dictionary |
a | any type |
The | (vertical bar) operator specifies the union of two types; eg, s|o is the type of a string or an object.
Lists are defined inside square brackets: []. There are two kinds of list declarations:
A heterogeneous list of fixed length is defined by the types of its elements. For example, [ios] specifies a 3-element list consisting of an integer, an object and a string, in that order.
A homogeneous list of varying length is defined by a single type followed by a length modifier:
| Modifier | Description |
|---|---|
{N:M} | between N and M elements, inclusive |
{N} | exactly N elements |
* | zero or more elements |
+ | one or more elements |
For example, [i{3,5}] specifies a list of 3, 4 or 5 integers.
Inside heterogeneous lists, | (union) has higher precedence than juxtaposition; ie, [i|so|n] defines a list of two elements, the first being an integer or a string and the second an object or NIL.
SIM_register_typed_class_attribute will register a class attribute. Class attributes are the same for all instances of the class.
Returns zero if successful, and non-zero otherwise.
SimExc_General Thrown if the attribute name is invalid, and if the attribute is not a required, optional, session or pseudo attribute.
SimExc_AttrNotReadable Thrown if a checkpointed attribute is not readable.
SimExc_AttrNotWritable Thrown if a checkpointed attribute is not writable.
Global Context
SIM_require_object — make sure an object is fully configured
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_require_object(conf_object_t *NOTNULL obj);
import simics
simics.SIM_require_object(...)
If obj has not yet been set as configured, then that object’s finalize method (post_init in DML) is run; otherwise, nothing happens. After completion of that method, obj will be set as configured.
Each object will have its finalize method called automatically, usually in hierarchical order, during object creation. Since it is only permitted to call methods on objects that have been configured, SIM_require_object is a way to allow such calls during finalisation by ensuring that those objects are correctly set up. A better way to call methods on other objects during finalization is to defer such calls to the objects_finalized method.
SIM_require_object may only be called from the finalize method of another object.
Finalisation cycles can occur if two or more objects call SIM_require_object on each other. Such cycles are treated as errors. To avoid them, call SIM_set_object_configured as soon as the object has reached a consistent state.
Global Context
SIM_object_is_configured, SIM_create_class, SIM_is_restoring_state
SIM_set_attribute_default — set default value for an attribute in a child object
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
set_error_t
SIM_set_attribute_default(conf_object_t *NOTNULL obj, const char *NOTNULL name,
attr_value_t val);
import simics
simics.SIM_set_attribute_default(...)
SIM_set_attribute_default sets the default value for attribute name of object obj. The default value is used if no explicit value has been provided when the object is instantiated.
After the call val is still owned by the caller.
The function may only called while obj is being under construction and before its attributes have been set. More precisely, it is only legal to use this function from init_object callbacks or from an attribute setters belonging to a hierarchical ancestor of the object.
The main purpose of this function is setting suitable default attribute values for port objects.
Returns Sim_Set_Ok if successful.
Global Context
SIM_set_class_data — set class data
#include <simics/device-api.h> // in C
// always available in DML
void
SIM_set_class_data(conf_class_t *cls, lang_void *data);
import simics
simics.SIM_set_class_data(...)
Set extra data for the specified class. This is particularly useful if the same class methods are used for multiple distinct classes, for instance for generated classes.
The class data can be fetched at any time during the object initialisation, using SIM_get_class_data.
Global Context
SIM_set_thread_name, SIM_get_thread_name — set/get the name of a thread
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
void
SIM_set_thread_name(const char *name);
char *
SIM_get_thread_name(void);
import simics
simics.SIM_set_thread_name(...)
simics.SIM_get_thread_name(...)
The functions use platform-specific way to set/get the name of a thread. For example, on Linux the functions work similar to pthread_setname_np/pthread_getname_np. Assigning names to threads can be helpful when the debugging of multithreaded simulations is done. In C, the string returned by SIM_get_thread_name is owned by the caller and should be freed with a call to MM_FREE.
On success, SIM_get_thread_name returns a null-terminated string. On error, NULL is returned.
Any context