attr_value_t — attribute value
#include <simics/device-api.h> // in C
// always available in DML
typedef struct attr_value attr_value_t;
The attr_value_t is the type used for all values in the configuration system. It is a tagged union.
The following table shows the different types of values, the type of their payload in C, and the corresponding Python types:
| Kind | C payload | Python type |
|---|---|---|
| Invalid | - | raises exception |
| String | const char * | str |
| Integer | int64 or uint64 | int or long |
| Boolean | bool | bool |
| Floating | double | float |
| Object | conf_object_t * | simics.conf_object_t |
| List | array of attr_value_t | list |
| Dict | array of pairs of attr_value_t | dict |
| Data | array of bytes | tuple of small integers |
| Nil | - | None |
The members inside attr_value_t should not be accessed directly. Instead, use the corresponding functions for each type:
| API Functions | |
|---|---|
| Constructor | SIM_make_attr_TYPE |
| Destructor | SIM_attr_free |
| Type predicate | SIM_attr_is_TYPE |
| Access | SIM_attr_TYPE |
Values of type List and Dict can be modified using SIM_attr_list_set_item, SIM_attr_dict_set_item, SIM_attr_list_resize, and SIM_attr_dict_resize.
None of these functions are available or needed in Python. The attr_value_t values are translated to the ordinary Python values as shown in the table above.
Some values may have data in separate heap allocations. These are normally managed by the respective constructor and destructor methods, but careless copying of values may introduce aliasing errors. Use SIM_attr_copy to duplicate values. Again, this is of no concern in Python.
SIM_make_attr_int64, SIM_attr_is_integer, SIM_attr_integer, SIM_attr_free, SIM_attr_list_resize, SIM_attr_list_set_item, SIM_attr_dict_resize, SIM_attr_dict_set_item, SIM_attr_copy
break_net_cb_t — callback type used with network breakpoints
#include <simics/devs/ethernet.h> // in C
import "simics/devs/ethernet.dml"; // in DML
typedef int (*break_net_cb_t)(conf_object_t *obj, bytes_t data,
int len, int64 break_id);
Callback function used by network breakpoint system, called when associated criteria has matched. The obj parameter is the ethernet link id where the breakpoint matched, msg is the message that is given back to the manager, break_id is the associated breakpoint id, returned by the add method in the network_breakpoint interface. The return value is ignored.
buffer_t — a reference to a mutable buffer
#include <simics/device-api.h> // in C
// always available in DML
typedef struct {
uint8 *data;
size_t len;
} buffer_t;
import simics
class simics.buffer_t
A reference to a (mutable) buffer. When used as a function parameter, the callee is permitted to write up to len bytes into the buffer pointed to by data.
Returning values of this type from interface methods should be avoided. If this is the case the scope of the returned object should be documented.
The corresponding Python type is called buffer_t, and behaves like a fixed-size mutable byte vector. The constructor takes as argument either a string, providing the initial value, or an integer, specifying the buffer size.
bytes_t — an immutable sequence of bytes
#include <simics/device-api.h> // in C
// always available in DML
typedef struct {
const uint8 *data;
size_t len;
} bytes_t;
An immutable sequence of bytes. When used as a function parameter, the callee should treat the data as read-only.
When used as a return value, the data member must point to a heap-allocated memory block whose ownership is transferred to the caller. The caller is then responsible for freeing the block.
The corresponding Python type is Python’s built-in class ‘bytes’. Here are a few code examples that create ‘bytes’ objects in Python:
b'abcd'
b'\xf0\xf1\xf2\xf3'
bytes([0xf0, 0xf1, 0xf2, 0xf3])
0xf3f2f1f0.to_bytes(length=4, byteorder='little')
bytes.fromhex('f0f1f2f3')
cbdata_t, cbdata_register_t, cbdata_call_t, cbdata_type_t — callback data types
#include <simics/device-api.h> // in C
// always available in DML
typedef struct cbdata cbdata_t;
typedef cbdata_t cbdata_register_t;
typedef cbdata_t cbdata_call_t;
typedef struct {
const char *name;
void (*dealloc)(void *data);
} cbdata_type_t;
These data types are used by API functions and interface methods that provide callbacks with callback data. By using these data types instead of a simple void *, the callback data can be freed correctly when not needed anymore.
The types cbdata_register_t and cbdata_call_t are only aliases for cbdata_t, used to annotate whether the object is passed to a registration function or a callback function. This is used by the automatic Python wrapping to ensure that the callback data is freed correctly.
Objects of this type can be created by using either SIM_make_cbdata or SIM_make_simple_cbdata. The latter creates an untyped objects with no deallocation function, while the former takes a cbdata_type_t argument, specifying a type name and a deallocation function.
The following example shows how an API function could be defined using these data types:
void for_all_ids(void (*callback)(const char *id,
cbdata_call_t data),
cbdata_register_t data);
Note how the two flavors of cbdata_t are used. cbdata_register_t is used to pass some data to for_all_ids which passes the same data unmodified to callback. Here is an example of how this function could be called; from C:
static void callback(const char *id, cbdata_call_t data)
{
const char *prefix = SIM_cbdata_data(&data);
printf("%s %s\n", prefix, id);
}
:
for_all_ids(callback, SIM_make_simple_cbdata("Testing"));
and from Python:
def callback(id, prefix):
print("%s %s" % (prefix, id))
for_all_ids(callback, "Testing")
Note in particular that the Python code does not mention “cbdata” anywhere; it is all automatically handled by the Python wrapping code.
The C version of the previous example used SIM_make_simple_cbdata, as the constant string "Testing" does not need any deallocation function. For dynamically allocated data, you must use SIM_make_cbdata instead:
static const cbdata_type_t malloced_int_type = {
"integer", // name
free // dealloc
};
static void callback(const char *id, cbdata_call_t data)
{
int *count = SIM_cbdata_data(&data);
printf("%d %s\n", *count, id);
++*count;
}
:
int *counter = malloc(sizeof *counter);
*counter = 1;
for_all_ids(callback, SIM_make_cbdata(malloced_int_type, counter));
In this example, for_all_ids is responsible for calling the deallocation function for the callback data after it has completed all calls to callback. It does this by calling SIM_free_cbdata, which in turn will call malloced_int_type.dealloc; i.e., free.
The same example in Python; we still do not have to call any cbdata function manually, but we do have to pass the counter in a one-element list since integers are immutable in Python:
def callback(id, count):
print("%s %s" % (prefix, count[0]))
count[0] += 1
for_all_ids(callback, [1])
While the use of cbdata_t over a simple void * in these examples seems redundant, they are needed if for_all_ids does not call callback before returning, but asynchronously at some later point in time. The use of cbdata_t also ensures that the data is freed correctly even when any of the involved functions is implemented in Python. This case often arises in conjunction with Simics interfaces.
See the Callback Functions in Interfaces section in the Simics Model Builder User’s Guide for more information on how to use the cbdata_t types.
lang_void, SIM_make_cbdata, SIM_make_simple_cbdata, SIM_free_cbdata, SIM_cbdata_data, SIM_cbdata_type
class_data_t — type used when a new class is registered with SIM_register_class
#include <simics/device-api.h> // in C
// always available in DML
typedef struct class_data {
conf_object_t *(*alloc_object)(lang_void *data);
lang_void *(*init_object)(conf_object_t *obj, lang_void *data);
void (*finalize_instance)(conf_object_t *obj);
void (*pre_delete_instance)(conf_object_t *obj);
int (*delete_instance)(conf_object_t *obj);
const char *description;
const char *class_desc;
class_kind_t kind;
} class_data_t;
import simics
class simics.class_data_t(alloc_object=None, init_object=None,
finalize_instance=None, pre_delete_instance=None,
delete_instance=None, description=None, class_desc=None,
kind=Sim_Class_Kind_Vanilla)
The class_data_t type is used when a new class is registered. Uninitialized fields should be set to zero before the structure is passed to SIM_register_class.
When a new object is created, memory for the conf_object_t is allocated by Simics unless alloc_object has been provided by the class. Classes written in C may implement alloc_object to have a single allocation and must then place conf_object_t first in the object data structure. This has the advantage of allowing casts directly from a conf_object_t * to a pointer to the user structure instead of using SIM_object_data.
When the conf_object_t has been allocated, the init_object function is called. If the object instance needs additional storage, it may allocate its own memory and return a pointer to it from init_object. This pointer can later be obtained using SIM_object_data. The return value from init_object has to be non-null to signal a successful object initialization. If a null value is returned, no configuration object will be created and an error will be reported. For classes that implement their own alloc_object, there is no need to allocate additional storage in the init_object function and they can simply return the conf_object_t pointer from init_object.
alloc_object and init_object both receive a data parameter; they are currently not used, and should be ignored.
The optional finalize_instance function is called when all attributes have been initialized in the object, and in all other objects that are created at the same time.
The pre_delete_instance and delete_instance fields can be set to let the objects of this class support deletion:
pre_delete_instance will be called in the first phase of the object deletion, during which objects are expected to clean-up their external links to other objects (breakpoints, hap callbacks, file or network resources, …). They may also trigger the deletion of other objects. pre_delete_instance is only called for objects that have reached at least finalize_instance during initialization.delete_instance will be called in the second phase of the object deletion: objects are expected to deallocate the memory they use including the object data structure. They may not communicate with other objects as these may already have been destroyed. The return value from delete_instance is ignored for compatibility. delete_instance is always called unless alloc_object is not defined, or if it returned NULL.The delete functions may be called by Simics before an object is fully configured. That is, without any call to finalize_instance and possibly before all the attribute set methods have been called. This may happen when the object is part of a configuration that fails to load. The SIM_object_is_configured function can be used to determine if finalize_instance has run or not.
The description string is used to describe the class in several sentences. It is used in the help commands and reference manuals. The class_desc string is a short class description beginning with lower case, without any trailing dot, and at most 50 characters long. It is used in help commands and for example in the GUI.
The old class functions are legacy. New code should use
class_info_tandSIM_create_class.
class_kind_t, class_info_t — type used when a new class is registered with SIM_create_class
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Class_Kind_Vanilla = 0, /* object is saved at checkpoints */
Sim_Class_Kind_Session = 1, /* object is saved as part of a
* session only */
Sim_Class_Kind_Pseudo = 2, /* object is never saved */
Sim_Class_Kind_Extension = 3, /* extension class
(see SIM_extend_class) */
} class_kind_t;
typedef struct class_info {
conf_object_t *(*alloc)(conf_class_t *cls);
lang_void *(*init)(conf_object_t *obj);
void (*finalize)(conf_object_t *obj);
void (*objects_finalized)(conf_object_t *obj);
void (*deinit)(conf_object_t *obj);
void (*dealloc)(conf_object_t *obj);
const char *description;
const char *short_desc;
class_kind_t kind;
} class_info_t;
import simics
simics.Sim_Class_Kind_Vanilla
simics.Sim_Class_Kind_Extension
simics.Sim_Class_Kind_Session
simics.Sim_Class_Kind_Pseudo
class simics.class_info_t(alloc=None, init=None, finalize=None,
objects_finalized=None, deinit=None, dealloc=None, description=None,
short_desc=None, kind=Sim_Class_Kind_Vanilla)
The class_info_t type is used when a new class is registered. Uninitialized fields should be set to zero before the structure is passed to SIM_create_class.
The alloc method is responsible for allocating memory for the object itself, i.e. the conf_object_t structure. If no alloc method is provided, Simics will use a default one, which uses MM_MALLOC. Classes written in C may implement alloc to have a single allocation and must then place conf_object_t first in the object data structure. This has the advantage of allowing casts directly from a conf_object_t * to a pointer to the user structure instead of using SIM_object_data. The alloc method can fail, e.g. if memory allocation fails, and signals this by returning NULL.
After alloc has run on all objects being created, the init function is called, if defined. This method should do any class specific initialization, such as initializing internal data structures. The init method may also use SIM_get_object to obtain pointers to other objects, and it can use SIM_set_attribute_default on its descendants, but it may not call interfaces on other objects, or post events. If the object instance needs additional storage, it may allocate its own memory and return a pointer to it from init. This pointer can later be obtained using SIM_object_data. However, for classes that implement their own alloc, there is no need for that, since it can be done by co-allocating the conf_object_t struct in a larger data structure, and simply return the conf_object_t pointer from init. The init method is allowed to fail, and it signals this by returning NULL.
The finalize method, if defined, is called when all attributes have been initialized in the object. This method is supposed to do any object initialization that require attribute values. Communication with other objects, e.g. via interfaces, should be deferred until the objects_finalized method. For backwards compatibility, this is also allowed from finalize provided the calling object has invoked SIM_require_object on the target object.
The objects_finalized method, if defined, is called after finalize has been called on all objects, so in this method the configuration is ready, and communication with other objects is permitted without restrictions.
The deinit and dealloc methods are called during object destruction. The deinit method, if defined, is called first on all objects being deleted, and is supposed to do the inverse of the init method. The dealloc method is supposed to free the conf_object_t itself, i.e. it should be the inverse of alloc. It is not defined, a default dealloc method is used, which uses MM_FREE.
The delete functions may be called by Simics before an object is fully configured. That is, without any call to finalize and possibly before all the attribute set methods have been called. This may happen when the object is part of a configuration that fails to load. The SIM_object_is_configured function can be used to determine if finalize has run or not.
All functions are called in hierarchical order, starting from the root, so each object can assume that in each case, a function has already been called on all its ancestors. This can be used to e.g. set attribute default values on descendants in the init method.
If the initialization fails, i.e. if init fails, or if any attribute setter fails, then the configuration creation is rolled back. For those objects where init succeeded (or no init was defined), the deinit function will be called, and on all created objects (i.e. not ones where alloc failed) the dealloc method is called.
The description string is used to describe the class in several sentences. It is used in the help commands and reference manuals. The short_desc string is a short class description beginning with lower case, without any trailing dot, and at most 50 characters long. It is used in help commands and for example in the GUI.
concurrency_mode_t — available concurrency modes
#include <simics/model-iface/concurrency.h> // in C
import "simics/model-iface/concurrency.dml"; // in DML
typedef enum {
/* Model uses the Standard Device Model */
Sim_Concurrency_Mode_Serialized = 1,
/* Model uses the Threaded Device Model.
Direct memory pages are protected against concurrency. */
Sim_Concurrency_Mode_Serialized_Memory = 2,
/* Model uses the Threaded Device Model.
Concurrency can be observed on direct memory pages */
Sim_Concurrency_Mode_Full = 4,
} concurrency_mode_t;
import simics
simics.Sim_Concurrency_Mode_Serialized
simics.Sim_Concurrency_Mode_Full
simics.Sim_Concurrency_Mode_Serialized_Memory
conf_object_t — a configuration object
#include <simics/device-api.h> // in C
// always available in DML
typedef struct conf_object conf_object_t;
import simics
class simics.conf_object_t
All objects in the Simics simulator have an associated conf_object_t struct. Pointers to conf_object_t are used in the Simics simulator API to refer to a specific object in the current Simics session. conf_object_t is an opaque data structure whose members should only be accessed using the Simics API.
data_or_instr_t — type used to differentiate between data and instruction
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_DI_Instruction = 0,
Sim_DI_Data = 1
} data_or_instr_t;
import simics
simics.Sim_DI_Data
simics.Sim_DI_Instruction
This type is used to differentiate between data and instruction, usually in a TBL or memory transaction context.
dbuffer_t — type used to store blocks of binary data
#include <simics/device-api.h> // in C
// always available in DML
typedef struct dbuffer dbuffer_t;
This is a legacy data type. New code should use one of
frags_t,bytes_torbuffer_t.
This type is used to store blocks of binary data. It is optimized for fast adding and removing of data, and does fast copying between buffers using copy-on-write semantics.
The type is not inherently thread safe, so each instance must have a single thread as owner, and only the owner can read or write from the instance, however ownership can be transferred to another thread. To share the data with other threads, the instance must first be cloned using dbuffer_clone.
endianness_t — endianness to use for certain memory operations
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Endian_Target,
Sim_Endian_Host_From_BE,
Sim_Endian_Host_From_LE
} endianness_t;
import simics
simics.Sim_Endian_Host_From_LE
simics.Sim_Endian_Target
simics.Sim_Endian_Host_From_BE
Specifies the endianness to use for certain memory operations. When Sim_Endian_Target is used, the data from memory is copied without any endian conversion. Sim_Endian_Host_From_BE and Sim_Endian_Host_From_LE copies data between a big-endian, or little-endian, memory and a host buffer.
eth_frame_crc_status_t — values used to signal crc status on ethernet frames
#include <simics/devs/ethernet.h> // in C
import "simics/devs/ethernet.dml"; // in DML
typedef enum {
Eth_Frame_CRC_Match,
Eth_Frame_CRC_Mismatch,
Eth_Frame_CRC_Unknown
} eth_frame_crc_status_t;
import simics
simics.Eth_Frame_CRC_Match
simics.Eth_Frame_CRC_Unknown
simics.Eth_Frame_CRC_Mismatch
exception_type_t — exceptions for memory accesses
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
SIM_PSEUDO_EXC(SIM_PSEUDO_EXC_ENUM)
} exception_type_t;
import simics
simics.Sim_PE_Last
simics.Sim_PE_IO_Not_Taken
simics.Sim_PE_Inquiry_Unhandled
simics.Sim_PE_Execute_Outside_Memory
simics.Sim_PE_Instruction_Finished
simics.Sim_PE_Cancelled
simics.Sim_PE_Async_Required
simics.Sim_PE_IO_Error
simics.Sim_PE_Ignore_Semantics
simics.Sim_PE_Deferred
simics.Sim_PE_Default_Semantics
simics.Sim_PE_No_Exception
simics.Sim_PE_Silent_Break
simics.Sim_PE_Stop_Request
simics.Sim_PE_Stall_Cpu
simics.Sim_PE_Inquiry_Outside_Memory
Used to signal simulator exceptions for memory accesses. Errors usually correspond to hardware exceptions, but in some cases additional return values are needed, and then pseudo exceptions are used. The most common is Sim_PE_No_Exception, indicating that no error has occurred. Pseudo exceptions are used by devices, memory spaces, and Simics internally.
SIM_defer_transaction.SIM_defer_transaction but the transaction cannot be deferred.transaction_completion_t callbacks when asynchronous transactions are cancelled by Simics, for example, when simulation state is restored from a snapshot.gen_spr_access_type_t — list of access types
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
/* Access from a mfspr/mtspr instruction */
Sim_Gen_Spr_Instruction_Access,
/* Access through attribute */
Sim_Gen_Spr_Attribute_Access,
/* Access through int_register interface */
Sim_Gen_Spr_Int_Register_Access,
/* For compatibility with former PPC-only implementation */
Sim_PPC_Spr_Instruction_Access = Sim_Gen_Spr_Instruction_Access,
Sim_PPC_Spr_Attribute_Access = Sim_Gen_Spr_Attribute_Access,
Sim_PPC_Spr_Int_Register_Access = Sim_Gen_Spr_Int_Register_Access
} gen_spr_access_type_t;
import simics
simics.Sim_Gen_Spr_Attribute_Access
simics.Sim_Gen_Spr_Int_Register_Access
simics.Sim_Gen_Spr_Instruction_Access
gen_spr_ret_t — list of access status
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Gen_Spr_Ok, /* SPR access was OK */
Sim_Gen_Spr_Illegal, /* SPR access should trigger illegal insn exc */
Sim_Gen_Spr_Privilege, /* SPR access should trigger privilege exc */
Sim_Gen_Spr_Processor_Sleeps, /* SPR access suspends the processor */
/* For compatibility with former PPC-only implementation */
Sim_PPC_Spr_Ok = Sim_Gen_Spr_Ok,
Sim_PPC_Spr_Illegal = Sim_Gen_Spr_Illegal,
Sim_PPC_Spr_Privilege = Sim_Gen_Spr_Privilege
} gen_spr_ret_t;
import simics
simics.Sim_Gen_Spr_Processor_Sleeps
simics.Sim_Gen_Spr_Illegal
simics.Sim_Gen_Spr_Privilege
simics.Sim_Gen_Spr_Ok
gen_spr_user_getter_func_t — function type used with spr interfaces
#include <simics/device-api.h> // in C
// always available in DML
typedef gen_spr_ret_t (*gen_spr_user_getter_func_t)(
conf_object_t *cpu,
int64 spr_number,
gen_spr_access_type_t type,
lang_void *user_data);
gen_spr_user_setter_func_t — function type used with spr interfaces
#include <simics/device-api.h> // in C
// always available in DML
typedef gen_spr_ret_t (*gen_spr_user_setter_func_t)(
conf_object_t *cpu,
int64 spr_number,
uint64 value,
gen_spr_access_type_t type,
lang_void *user_data);
generic_transaction_t — represents a memory transaction
#include <simics/device-api.h> // in C
// always available in DML
typedef struct generic_transaction {
logical_address_t logical_address;
physical_address_t physical_address;
unsigned int size; /* size in bytes */
mem_op_type_t type; /* opaque */
unsigned int atomic:1; /* trans is part of an atomic
sequence of mem ops */
unsigned int inquiry:1; /* set to 1 to indicate inquiry
access */
unsigned int non_coherent:1; /* set to 1 to use
direct_memory_update_interface_t.
update_caching else
update_permission */
unsigned int _deprecated_ignore:1;
unsigned int may_stall:1; /* when set to 0, any stall time
returned is ignored */
unsigned int reissue:1; /* If this is 1, the transaction
will be reissued if a stall
greater than 0 is returned */
unsigned int block_STC:1; /* blocks stc (compat. only) */
unsigned int use_page_cache:1; /* internal - do not change */
unsigned int inverse_endian:1; /* data transfer is
byte-reversed */
unsigned int page_cross:2; /* page crossing
0 - no crossing
1 - first access
2 - second access */
unsigned int mem_hier_on_fetch:1; /* set to have fetches sent
through mem hier */
unsigned int block_flags; /* what we wish to block
from caching */
ini_type_t ini_type; /* cpu, device, or other */
conf_object_t *ini_ptr;
exception_type_t exception; /* set if memhier throws
exception, otherwise
Sim_PE_No_Exception */
#if !defined(PYWRAP)
void *user_ptr; /* user pointer that Simics never
touches */
uint8 *real_address; /* data pointer for the
initiator */
int space_count; /* internal, # of memory space
transitions */
#endif
#if !defined(PYWRAP)
struct transaction *transaction;
#else
transaction_t *transaction; /* associated transaction_t */
#endif
#if !defined(PYWRAP)
page_t *reserved; /* no longer used */
unsigned int reserved2; /* no longer used */
#endif
} generic_transaction_t;
import simics
class simics.generic_transaction_t(logical_address = 0, physical_address = 0,
size = 0, type = Sim_Trans_Load, atomic = 0, inquiry = 0,
non_coherent = 0, may_stall = 0, reissue = 0,
block_STC = 0, use_page_cache = 0, inverse_endian = 0,
page_cross = 0, mem_hier_on_fetch = 0, block_flags = 0,
ini_type = Sim_Initiator_Illegal, ini_ptr = None, exception = 0,
transaction = None)
A generic_transaction_t represents a memory transaction. It should only be accessed via the accessor functions documented in Device API Functions: Memory Transactions
global_notifier_type_t — enum with predefined global notifiers
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Global_Notify_Object_Delete = 100,
Sim_Global_Notify_Objects_Finalized,
Sim_Global_Notify_Message,
Sim_Global_Notify_Before_Snapshot_Restore = 150,
Sim_Global_Notify_After_Snapshot_Restore,
Sim_Global_Notify_Snapshot_Created,
Sim_Global_Notify_Snapshot_Deleted,
} global_notifier_type_t;
import simics
simics.Sim_Global_Notify_Snapshot_Created
simics.Sim_Global_Notify_Message
simics.Sim_Global_Notify_Snapshot_Deleted
simics.Sim_Global_Notify_Objects_Finalized
simics.Sim_Global_Notify_After_Snapshot_Restore
simics.Sim_Global_Notify_Before_Snapshot_Restore
simics.Sim_Global_Notify_Object_Delete
This enum is used to identify pre-defined global notifier. The Sim_Global_Notify_Object_Delete notifier is triggered by Simics when objects are being deleted. In the callback, objects are still fully available, but SIM_marked_for_deletion can be used to determine if an object is being deleted.
The Sim_Global_Notify_Objects_Finalized notifier is triggered by Simics when new objects have been finalized, after their objects_finalized methods have been called.
The Sim_Global_Notify_Message notifier is used by SIM_trigger_global_message.
The corresponding names used in e.g. list-notifiers are as follows:
Sim_Global_Notify_Object_DeleteSim_Global_Notify_Objects_FinalizedSim_Global_Notify_MessageSIM_add_global_notifier, SIM_add_global_notifier_once, SIM_delete_global_notifier,
hap_type_t — data type of hap types
#include <simics/device-api.h> // in C
// always available in DML
typedef int hap_type_t;
This data type is used to represent hap (occurrence) types. This is a runtime number that may change between different Simics invocations. Haps are normally identified by strings, but by calling SIM_hap_get_number, a lookup from such a name to a hap_type_t can be made.
init_arg_t — parameter type used to initialize an embedded Simulator
#include <simics/simulator-api.h> // in C
import "simics/simulator-api.dml"; // in DML
typedef struct {
const char *name;
bool boolean;
union {
const char *string;
bool enabled;
} u;
} init_arg_t;
Data structure used to pass an initialization argument to the SIM_init_simulator2 function. The name field is mandatory and the associated data is either a boolean or a string (char *). A list of init_arg_t is passed to SIM_init_simulator2 where the last entry has the name field set to NULL.
int16, int32, int64, uint8, uint16, uint32, uint64, intptr_t, uintptr_t, int8 — basic integer types
These are basic integer data types defined by the Simics headers (unless defined by system header files).
The intn types are defined to be signed integers of exactly n bits. The uintn types are their unsigned counterparts.
intptr_t and uintptr_t are signed and unsigned integer types of a size that lets any pointer to void be cast to it and then cast back to a pointer to void, and the result will compare equal to the original pointer. This typically means that the two types are 64 bits wide.
interrupt_source_t — list of interrupt sources
#include <simics/devs/interrupt-subscriber.h> // in C
import "simics/devs/interrupt-subscriber.dml"; // in DML
typedef enum {
Interrupt_Source_Icr_Ipr,
Interrupt_Source_Msi,
Interrupt_Source_Virtual_Wire,
Interrupt_Source_Nmi_Pin,
Interrupt_Source_Lvt,
Interrupt_Source_Iommu,
Interrupt_Source_Int2,
Interrupt_Source_Vmcs_Injection,
Interrupt_Source_Legacy_Apic_Vector,
Interrupt_Source_Self_Ipi,
Interrupt_Source_Unknown,
} interrupt_source_t;
import simics
simics.Interrupt_Source_Self_Ipi
simics.Interrupt_Source_Virtual_Wire
simics.Interrupt_Source_Lvt
simics.Interrupt_Source_Msi
simics.Interrupt_Source_Legacy_Apic_Vector
simics.Interrupt_Source_Vmcs_Injection
simics.Interrupt_Source_Iommu
simics.Interrupt_Source_Int2
simics.Interrupt_Source_Icr_Ipr
simics.Interrupt_Source_Nmi_Pin
simics.Interrupt_Source_Unknown
Sources of interrupts
Interrupt_Source_Icr_Ipr means that the source is the Interrupt Control Register - Inter Processor Interrupt.Interrupt_Source_Msi means that the source is an MSI.Interrupt_Source_Virtual_Wire means that the source is the Virtual Wire.Interrupt_Source_Nmi_Pin means that the source is the external NMI pin.Interrupt_Source_Lvt means that the source is the local vector table (LVT).Interrupt_Source_Iommu means that the source is the IOMMU.Interrupt_Source_Int2 means that the source is the INT2 instruction.Interrupt_Source_Vmcs_Injection means that the source is an interrupt injected through the VMCS.Interrupt_Source_Legacy_Apic_Vector means that the source is the legacy APIC interrupt vector.Interrupt_Source_Self_Ipi means that the source is the SELF IPI Register.Interrupt_Source_Unknown means that the source is unknown.lang_void — any data type in the current programming language
#include <simics/device-api.h> // in C
// always available in DML
typedef void lang_void;
In some places in the Simics API, arguments of type lang_void * are used. This data type is used to allow transparent passing of any data type in the current programming language as argument. In C, this works exactly like a <nobr>void *</nobr> and in Python, it is any Python object.
Typically, this is used by iterator functions in the API which take callback functions as arguments. The callback function is later called with the lang_void data and the object being iterated over.
logical_address_t, physical_address_t, generic_address_t, linear_address_t — target address types
#include <simics/device-api.h> // in C
// always available in DML
typedef uint64 logical_address_t;
typedef uint64 physical_address_t;
typedef uint64 generic_address_t;
typedef uint64 linear_address_t;
These are integer data types defined to reflect the nature of the simulated architecture.
logical_address_t is an unsigned integer sufficiently large to contain logical (virtual) addresses on the target machine.
physical_address_t is an unsigned integer sufficiently large to contain physical addresses on the target machine.
generic_address_t is defined to be the largest of the logical_address_t and physical_address_t types.
linear_address_t is used for linear addresses used on x86 machines after segmentation but before paging.
Note that these data types are all defined to be 64-bit unsigned integers, and they can be printed by printf using the ll (ell-ell) size modifier.
swap_mode_t, map_info_t — describes a device mapping in a memory space
#include <simics/device-api.h> // in C
// always available in DML
typedef enum swap_mode {
Sim_Swap_None = 0,
Sim_Swap_Bus = 1,
Sim_Swap_Bus_Trans = 2,
Sim_Swap_Trans = 3
} swap_mode_t;
typedef struct map_info {
physical_address_t base;
physical_address_t start;
physical_address_t length;
int function;
int16 priority;
int align_size;
swap_mode_t reverse_endian;
} map_info_t;
import simics
simics.Sim_Swap_Trans
simics.Sim_Swap_None
simics.Sim_Swap_Bus
simics.Sim_Swap_Bus_Trans
class simics.map_info_t(base=0, start=0, length=0, function=0, priority=0,
align_size=0, reverse_endian=Sim_Swap_None)
The map_info_t structure members have the following meaning:
base: The base address of the device mapping in the memory space.start: The address inside the device memory space where the mapping starts.length: The length of the mapped memory, in bytes.function: Used to map the same object several times with different functionality. Corresponds to the function argument used when mapping devices into a memory space.align_size can be set to the maximum allowed size. Accesses spanning align boundaries will be split into several smaller transactions. The align size must be a power of two, or zero (which means “use the default value”: 8 for devices and 8192 for memory).reverse_endian field to a non zero value. This can be used to model bridges that perform byte swapping on a specific bus width.If both base and length are 0 the map will become a default_target.
map_type_t, map_list_t — information about the set of mappings at an address
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Map_Ram,
Sim_Map_Rom,
Sim_Map_IO,
Sim_Map_Port,
Sim_Map_Translate = 0x100, /* pseudo - do not use */
Sim_Map_Translate_To_Space,
Sim_Map_Translate_To_Ram,
Sim_Map_Translate_To_Rom
} map_type_t;
typedef struct map_list {
map_type_t map_type;
conf_object_t *object;
const char *port;
#if !defined(PYWRAP)
const void *interface_ptr;
const void *target_interface;
const void *breakpoint_interface;
#if defined(SIMICS_6_API)
const void *breakpoint_query_interface;
#else
const void *breakpoint_query_v2_interface;
#endif
const void *bridge_interface;
#endif
conf_object_t *target_object;
const char *target_port;
conf_object_t *bridge;
map_info_t map_info;
physical_address_t map_size; /* not constant, use with caution */
int deleted; /* internal flag - should always be 0 ! */
} map_list_t;
// with SIMICS_API = 6
typedef struct map_list {
map_type_t map_type;
conf_object_t *object;
const char *port;
const void *interface_ptr;
const void *target_interface;
const void *breakpoint_interface;
const void *breakpoint_query_interface;
const void *bridge_interface;
conf_object_t *target_object;
const char *target_port;
conf_object_t *bridge;
map_info_t map_info;
physical_address_t map_size;
int deleted;
} map_list_t;
import simics
simics.Sim_Map_IO
simics.Sim_Map_Translate
simics.Sim_Map_Translate_To_Space
simics.Sim_Map_Port
simics.Sim_Map_Translate_To_Ram
simics.Sim_Map_Ram
simics.Sim_Map_Rom
simics.Sim_Map_Translate_To_Rom
class simics.map_list_t
This data structure is used to pass information about the set of mappings a particular address in an address space contains.
map_target_t — opaque type of map-targets
#include <simics/device-api.h> // in C
// always available in DML
typedef struct map_target map_target_t;
import simics
class simics.map_target_t()
A map target can be viewed as an opaque representation of an object/interface pair which can function either as an endpoint for a memory transaction or as an address space where a memory transaction can be performed. To create a map_target_t object one should use the SIM_new_map_target function.
The SIM_free_map_target function frees a map_target_t object. In order to get better performance, it is better to allocate a map target once and reuse it rather than to allocate and free it every time.
Examples of map targets include IO banks, RAM, ROM, memory spaces, port spaces, translators and bridges.
For certain targets, e.g. bridges or translators, the map target also holds information about a chained, or default, target.
In Python, it is allowed to use arguments of the conf_object_t type with Simics API functions that have parameters of the map_target_t type. The arguments of the conf_object_t type will be converted to map_target_t values automatically, via the call to the SIM_new_map_target function. Here is an example where memory_space is a Simics object, i.e. has the conf_object_t type:
t = transaction_t(...)
SIM_issue_transaction(memory_space, t, addr)
In Python, the objects of the map_target_t type have read-only obj, port, and target attributes. These attributes correspond to the arguments given to SIM_new_map_target that created a map_target_t object.
SIM_new_map_target, SIM_free_map_target, SIM_map_target_object, SIM_map_target_port, SIM_map_target_target, translator
mem_op_type_t — enum that identifies the type of a memory operation
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Trans_Load = 0,
Sim_Trans_Store = Sim_Trn_Write,
Sim_Trans_Instr_Fetch = Sim_Trn_Instr,
Sim_Trans_Prefetch = Sim_Trn_Prefetch | Sim_Trn_Control,
Sim_Trans_Cache = Sim_Trn_Control
} mem_op_type_t;
import simics
simics.Sim_Trans_Instr_Fetch
simics.Sim_Trans_Prefetch
simics.Sim_Trans_Cache
simics.Sim_Trans_Load
simics.Sim_Trans_Store
This enum is used to identify the type of a memory operation. The function SIM_get_mem_op_type() returns the type of a generic_transaction_t, and SIM_set_mem_op_type() is used to set it.
SIM_get_mem_op_type, SIM_set_mem_op_type, SIM_get_mem_op_type_name generic_transaction_t,
notifier_type_t — predefined notifiers
#include <simics/device-api.h> // in C
// always available in DML
/* Note that notifier types can be added either by modifying this enum or
by using SIM_notifier_type. The latter is typically preferred since it does
not change the Simics API. */
typedef enum {
Sim_Notify_Queue_Change,
Sim_Notify_Cell_Change,
Sim_Notify_Frequency_Change,
Sim_Notify_Concurrency_Change,
Sim_Notify_Object_Delete,
Sim_Notify_Map_Change,
Sim_Notify_State_Change,
Sim_Notify_Freerunning_Mode_Change,
Sim_Notify_Bank_Register_Value_Change,
} notifier_type_t;
import simics
simics.Sim_Notify_Map_Change
simics.Sim_Notify_Freerunning_Mode_Change
simics.Sim_Notify_State_Change
simics.Sim_Notify_Object_Delete
simics.Sim_Notify_Cell_Change
simics.Sim_Notify_Bank_Register_Value_Change
simics.Sim_Notify_Queue_Change
simics.Sim_Notify_Concurrency_Change
simics.Sim_Notify_Frequency_Change
Values of the notifier_type_t type identify notification events. A notifier_type_t value should be obtained from the SIM_notifier_type function and can then be used in other functions such as SIM_register_notifier, SIM_add_notifier, SIM_notify.
A few notification events have predefined (constant) values. They are listed below where a notifier type in the form of a string (as accepted by SIM_notifier_type) is followed by the constant of the notifier_type_t type corresponding to the notification event (as returned by SIM_notifier_type):
Sim_Notify_Queue_Change)Sim_Notify_Cell_Change)Sim_Notify_Frequency_Change)Sim_Notify_Concurrency_Change)Sim_Notify_Object_Delete)Sim_Notify_Map_Change)Sim_Notify_State_Change)Sim_Notify_Freerunning_Mode_Change)Sim_Notify_Bank_Register_Value_Change)SIM_notify, SIM_add_notifier, SIM_register_notifier, SIM_notifier_type, SIM_describe_notifier, SIM_notifier_description
processor_mode_t — type for generic CPU-modes
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_CPU_Mode_User = 0,
Sim_CPU_Mode_Supervisor = 1,
Sim_CPU_Mode_Hypervisor
} processor_mode_t;
import simics
simics.Sim_CPU_Mode_Hypervisor
simics.Sim_CPU_Mode_Supervisor
simics.Sim_CPU_Mode_User
The processor_mode_t data type is used to specify if a CPU is running in user mode or in a privileged mode (often called supervisor mode). For processor architectures with several privilege levels, the non-user levels are all identified as Sim_CPU_Mode_Supervisor.
read_or_write_t — read or write memory access kind enumeration
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_RW_Read = 0,
Sim_RW_Write = 1
} read_or_write_t;
import simics
simics.Sim_RW_Read
simics.Sim_RW_Write
Whether a memory access is a read (from memory) or a write (to memory).
set_error_t — type for errors that an attribute setter can return
#include <simics/device-api.h> // in C
// always available in DML
typedef enum {
Sim_Set_Ok,
Sim_Set_Object_Not_Found,
Sim_Set_Interface_Not_Found,
Sim_Set_Illegal_Value,
Sim_Set_Illegal_Type,
Sim_Set_Illegal_Index,
Sim_Set_Attribute_Not_Found,
Sim_Set_Not_Writable,
Sim_Set_Error_Types /* number of error types */
} set_error_t;
import simics
simics.Sim_Set_Ok
simics.Sim_Set_Interface_Not_Found
simics.Sim_Set_Illegal_Type
simics.Sim_Set_Illegal_Index
simics.Sim_Set_Error_Types
simics.Sim_Set_Illegal_Value
simics.Sim_Set_Attribute_Not_Found
simics.Sim_Set_Not_Writable
simics.Sim_Set_Object_Not_Found
The SIM_set_attribute() family of functions and the set functions registered with the SIM_register_attribute() family of functions return a set_error_t value to report success or failure.
The attribute was successfully set.
The string value does not match any object name. Deprecated, use attributes of object type instead of string attributes referring to object names.
The object value does not implement an interface required by the attribute.
The value is of a legal type for the attribute, but outside the legal range.
Sim_Set_Illegal_Type The value is of an illegal type for the attribute.
The object has no attribute with the specified name. Should only be returned by SIM_set_attribute() family of functions, not by attribute set functions.
The attribute is read-only.
This is the number of valid error values and should not be used as an error code.
pc_step_t, simtime_t, cycles_t, nano_secs_t — types used for time keeping
#include <simics/device-api.h> // in C
// always available in DML
typedef simtime_t pc_step_t;
// always available in DML
typedef int64 simtime_t;
typedef simtime_t cycles_t;
typedef int64 nano_secs_t;
These are the types used for keeping track of time in Simics.
cycles_t is used when the time is specified in cycles.
pc_step_t is used when the time is specified in steps.
simtime_t is used in places where it is unknown whether the time is in steps or cycles.
See the Understanding Simics Timing application note for a discussion about the difference between steps and cycles.
nano_secs_t is used to express a number of nanoseconds (10^-9 seconds).
sub_object_flags_t — bitmask used to configure how sub-objects are registered
#include <simics/device-api.h> // in C
// always available in DML
typedef uint64 sub_object_flags_t;
The type sub_object_flags_t is a bitmask used to configure how sub-objects registered through SIM_register_sub_object() behave, such as their visibility or how tight the connection is between the sub-object and its parent.
Sim_Sub_Obj_DefaultSim_Reduced_VisibilitySim_Dependent