Name

sim_exception_t — frontend exceptions

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef enum sim_exception {
        SimExc_No_Exception,
        SimExc_General,
        SimExc_Lookup,
        SimExc_Attribute,
        SimExc_IOError,
        SimExc_Index,
        SimExc_Memory,
        SimExc_InquiryOutsideMemory,
        SimExc_InquiryUnhandled,
        SimExc_Type,
        SimExc_Break,
        SimExc_PythonTranslation,
        SimExc_License,
        SimExc_IllegalValue,
        SimExc_InterfaceNotFound,
        SimExc_AttrNotFound,
        SimExc_AttrNotReadable,
        SimExc_AttrNotWritable
} sim_exception_t;

Python

import simics

simics.SimExc_Break
simics.SimExc_Index
simics.SimExc_InquiryUnhandled
simics.SimExc_AttrNotFound
simics.SimExc_InquiryOutsideMemory
simics.SimExc_Lookup
simics.SimExc_General
simics.SimExc_IllegalValue
simics.SimExc_Type
simics.SimExc_PythonTranslation
simics.SimExc_Attribute
simics.SimExc_Memory
simics.Sim_Exceptions
simics.SimExc_License
simics.SimExc_No_Exception
simics.SimExc_Stop
simics.SimExc_AttrNotReadable
simics.SimExc_IOError
simics.SimExc_AttrNotWritable
simics.SimExc_InterfaceNotFound

Description

Whenever an error occurs in a Simics API function, that function will raise an exception. An exception consists of an exception type and an error message.

Note that API users writing in C must use SIM_clear_exception() and SIM_last_error() since C does not support exceptions. In Python, the Simics API exceptions will trigger actual Python exceptions, which you can capture using try ... except.

Name

attr_value_t — attribute value

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct attr_value attr_value_t;

Description

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:

The members inside attr_value_t should not be accessed directly. Instead, use the corresponding functions for each 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.

See Also

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

Name

break_net_cb_t — callback type used with network breakpoints

Synopsis

C and DML

#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);

Description

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.

Name

buffer_t — a reference to a mutable buffer

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct {
        uint8 *data;
        size_t len;
} buffer_t;

Python

import simics

class simics.buffer_t

Description

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.

Name

bytes_t — an immutable sequence of bytes

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct {
        const uint8 *data;
        size_t len;
} bytes_t;

Description

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')

Name

cbdata_t, cbdata_register_t, cbdata_call_t, cbdata_type_t — callback data types

Synopsis

C and DML

#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;

Description

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.

See Also

lang_void, SIM_make_cbdata, SIM_make_simple_cbdata, SIM_free_cbdata, SIM_cbdata_data, SIM_cbdata_type

Name

class_data_t — type used when a new class is registered with SIM_register_class

Synopsis

C and DML

#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;

Python

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)

Description

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_t and SIM_create_class.

Name

class_kind_t, class_info_t — type used when a new class is registered with SIM_create_class

Synopsis

C and DML

#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;

Python

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)

Description

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.

Name

concurrency_mode_t — available concurrency modes

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_Concurrency_Mode_Serialized
simics.Sim_Concurrency_Mode_Full
simics.Sim_Concurrency_Mode_Serialized_Memory

Name

conf_object_t — a configuration object

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct conf_object conf_object_t;

Python

import simics

class simics.conf_object_t

Description

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.

Name

data_or_instr_t — type used to differentiate between data and instruction

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_DI_Data
simics.Sim_DI_Instruction

Description

This type is used to differentiate between data and instruction, usually in a TBL or memory transaction context.

Name

dbuffer_t — type used to store blocks of binary data

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct dbuffer dbuffer_t;

Description

This is a legacy data type. New code should use one of frags_t, bytes_t or buffer_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.

Name

endianness_t — endianness to use for certain memory operations

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_Endian_Host_From_LE
simics.Sim_Endian_Target
simics.Sim_Endian_Host_From_BE

Description

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.

Name

eth_frame_crc_status_t — values used to signal crc status on ethernet frames

Synopsis

C and DML

#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;

Python

import simics

simics.Eth_Frame_CRC_Match
simics.Eth_Frame_CRC_Unknown
simics.Eth_Frame_CRC_Mismatch

Description

Eth_Frame_CRC_Match

the frame contents are correct. The CRC field in the frame should not be relied upon as its computation may have been skipped for optimization, and it may contain any value, including zero, a random value or a correctly computed CRC.

Eth_Frame_CRC_Mismatch

the frame contents are incorrect. The CRC field in the frame must contain a CRC that does not match the frame contents, i.e., to send an incorrect frame on the link, you must make sure that the CRC field will not match when computed.

Eth_Frame_CRC_Unknown

the relation between the frame contents and the CRC field is unknown. The relation can be established by computing the frame’s CRC and comparing it to the frame’s CRC field.

Name

exception_type_t — exceptions for memory accesses

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef enum {
        SIM_PSEUDO_EXC(SIM_PSEUDO_EXC_ENUM)
} exception_type_t;

Python

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

Description

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_PE_No_Exception

No error.

Sim_PE_Deferred

Transaction completion is deferred via the call to SIM_defer_transaction.

Sim_PE_Async_Required

The endpoint tried to defer the transaction with SIM_defer_transaction but the transaction cannot be deferred.

Sim_PE_Cancelled

Special completion status passed to transaction_completion_t callbacks when asynchronous transactions are cancelled by Simics, for example, when simulation state is restored from a snapshot.

Sim_PE_IO_Not_Taken

Access to unmapped memory. In the PCI memory spaces interpreted as master abort.

Sim_PE_IO_Error

Accessed device returned error. In the PCI memory spaces interpreted as target abort.

Sim_PE_Inquiry_Outside_Memory

Same as Sim_PE_IO_Not_Taken, but for inquiry accesses.

Sim_PE_Execute_Outside_Memory

A processor tried to fetch instruction where no memory is defined.

Sim_PE_Inquiry_Unhandled

The accessed device does not support inquiry operations.

Sim_PE_Stall_Cpu

Timing model requested stall.

Sim_PE_Default_Semantics

Used by user decoders and user ASI handlers on SPARC to signal that the default semantics should be run.

Sim_PE_Ignore_Semantics

Used by user ASI handlers on SPARC to signal no update of destination registers.

Sim_PE_Silent_Break, Sim_PE_Instruction_Finished, Sim_PE_Last

Simics internal.

Name

gen_spr_access_type_t — list of access types

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_Gen_Spr_Attribute_Access
simics.Sim_Gen_Spr_Int_Register_Access
simics.Sim_Gen_Spr_Instruction_Access

Name

gen_spr_ret_t — list of access status

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_Gen_Spr_Processor_Sleeps
simics.Sim_Gen_Spr_Illegal
simics.Sim_Gen_Spr_Privilege
simics.Sim_Gen_Spr_Ok

Name

gen_spr_user_getter_func_t — function type used with spr interfaces

Synopsis

C and DML

#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);

Name

gen_spr_user_setter_func_t — function type used with spr interfaces

Synopsis

C and DML

#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);

Name

generic_transaction_t — represents a memory transaction

Synopsis

C and DML

#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;

Python

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)

Description

A generic_transaction_t represents a memory transaction. It should only be accessed via the accessor functions documented in Device API Functions: Memory Transactions

Name

global_notifier_type_t — enum with predefined global notifiers

Synopsis

C and DML

#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;

Python

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

Description

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:

• “global-object-delete”, Sim_Global_Notify_Object_Delete
• “global-objects-finalized”, Sim_Global_Notify_Objects_Finalized
• “global-message”, Sim_Global_Notify_Message

See Also

SIM_add_global_notifier, SIM_add_global_notifier_once, SIM_delete_global_notifier,

Name

hap_type_t — data type of hap types

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef int hap_type_t;

Description

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.

See Also

SIM_get_all_hap_types, SIM_hap_get_number, SIM_hap_add_type

Name

init_arg_t — parameter type used to initialize an embedded Simulator

Synopsis

C and DML

#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;

Description

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.

Name

int16, int32, int64, uint8, uint16, uint32, uint64, intptr_t, uintptr_t, int8 — basic integer types

Description

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.

Name

interrupt_source_t — list of interrupt sources

Synopsis

C and DML

#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;

Python

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

Description

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.

See Also

interrupt_subscriber interface

Name

lang_void — any data type in the current programming language

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef void lang_void;

Description

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.

See Also

SIM_hap_add_callback, SIM_register_typed_attribute

Name

logical_address_t, physical_address_t, generic_address_t, linear_address_t — target address types

Synopsis

C and DML

#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;

Description

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.

Name

swap_mode_t, map_info_t — describes a device mapping in a memory space

Synopsis

C and DML

#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;

Python

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)

Description

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.
• If the map target does not support large accesses, then 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).
• Mappings with an align size of 2, 4, or 8 may set the 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.

Name

map_type_t, map_list_t — information about the set of mappings at an address

Synopsis

C and DML

#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;

Python

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

Description

This data structure is used to pass information about the set of mappings a particular address in an address space contains.

Name

map_target_t — opaque type of map-targets

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct map_target map_target_t;

Python

import simics

class simics.map_target_t()

Description

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.

Python Specific

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.

See Also

SIM_new_map_target, SIM_free_map_target, SIM_map_target_object, SIM_map_target_port, SIM_map_target_target, translator

Name

mem_op_type_t — enum that identifies the type of a memory operation

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_Trans_Instr_Fetch
simics.Sim_Trans_Prefetch
simics.Sim_Trans_Cache
simics.Sim_Trans_Load
simics.Sim_Trans_Store

Description

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.

See Also

SIM_get_mem_op_type, SIM_set_mem_op_type, SIM_get_mem_op_type_name generic_transaction_t,

Name

notifier_type_t — predefined notifiers

Synopsis

C and DML

#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;

Python

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

Description

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):

• “queue-change” (Sim_Notify_Queue_Change)
• “cell-change” (Sim_Notify_Cell_Change)
• “frequency-change” (Sim_Notify_Frequency_Change)
• “concurrency-change” (Sim_Notify_Concurrency_Change)
• “object-delete” (Sim_Notify_Object_Delete)
• “map-change” (Sim_Notify_Map_Change)
• “state-change” (Sim_Notify_State_Change)
• “freerunning-mode-change” (Sim_Notify_Freerunning_Mode_Change)
• “bank-register-value-change” (Sim_Notify_Bank_Register_Value_Change)

See Also

SIM_notify, SIM_add_notifier, SIM_register_notifier, SIM_notifier_type, SIM_describe_notifier, SIM_notifier_description

Name

processor_mode_t — type for generic CPU-modes

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_CPU_Mode_Hypervisor
simics.Sim_CPU_Mode_Supervisor
simics.Sim_CPU_Mode_User

Description

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.

Name

read_or_write_t — read or write memory access kind enumeration

Synopsis

C and DML

#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;

Python

import simics

simics.Sim_RW_Read
simics.Sim_RW_Write

Description

Whether a memory access is a read (from memory) or a write (to memory).

Name

set_error_t — type for errors that an attribute setter can return

Synopsis

C and DML

#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;

Python

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

Description

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.

Sim_Set_Ok

The attribute was successfully set.

Sim_Set_Object_Not_Found

The string value does not match any object name. Deprecated, use attributes of object type instead of string attributes referring to object names.

Sim_Set_Interface_Not_Found

The object value does not implement an interface required by the attribute.

Sim_Set_Illegal_Value

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.

Sim_Set_Attribute_Not_Found

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.

Sim_Set_Not_Writable

The attribute is read-only.

Sim_Set_Error_Types

This is the number of valid error values and should not be used as an error code.

Name

pc_step_t, simtime_t, cycles_t, nano_secs_t — types used for time keeping

Synopsis

C and DML

#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;

Description

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).

Name

sub_object_flags_t — bitmask used to configure how sub-objects are registered

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef uint64 sub_object_flags_t;

Description

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_Default

The sub-object will be listed as a normal full object and is an independent object that can be scheduled separately to its parent. The sub-object is only allowed to access its parent through interfaces and attributes.

Sim_Reduced_Visibility

The sub-object will only be listed when port-objects are asked for.

Sim_Dependent

The sub-object can be seen as a port of its parent and is free to access data there directly. Dependent sub-objects are always scheduled together with its parent.

Name

atom_id_t — predefined atom ids

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef enum {
        Sim_Atom_Id_illegal = 0,
        Sim_Atom_Id_list_end,
        Sim_Atom_Id_flags,
        Sim_Atom_Id_data,
        Sim_Atom_Id_size,
        Sim_Atom_Id_fill_value,
        Sim_Atom_Id_initiator,
        Sim_Atom_Id_user_data,
        Sim_Atom_Id_completion,
        Sim_Atom_Id_owner,
        Sim_Atom_Id_memop,
        Sim_Atom_Id_bytemap,
        Sim_Atom_Id_trace_atom_access,
        Sim_Atom_Id_target_type,
        Sim_Atom_Id_pcie_type = 0x100,
        Sim_Atom_Id_pcie_requester_id,
        Sim_Atom_Id_pcie_msg_type,
        Sim_Atom_Id_pcie_ecs,
        Sim_Atom_Id_pcie_msg_route,
        Sim_Atom_Id_pcie_pasid,
        Sim_Atom_Id_pcie_at,
        Sim_Atom_Id_pcie_error_ret,
        Sim_Atom_Id_pcie_byte_count_ret,
        Sim_Atom_Id_pcie_device_id,
        Sim_Atom_Id_pcie_destination_segment,
        Sim_Atom_Id_pcie_link_negotiation,
        Sim_Atom_Id_pcie_link_flit_mode,
        Sim_Atom_Id_pcie_ats_translation_request_cxl_src,
        Sim_Atom_Id_pcie_ats_translation_request_no_write,
        Sim_Atom_Id_pcie_ats_invalidate_request_itag,
        Sim_Atom_Id_pcie_ats_invalidate_completion_itag_vector,
        Sim_Atom_Id_pcie_ats_invalidate_completion_count,
        Sim_Atom_Id_pcie_prs_page_request,
        Sim_Atom_Id_pcie_prs_page_group_response,
        Sim_Atom_Id_pcie_prs_stop_marker,
        Sim_Atom_Id_pcie_requester_segment,
        Sim_Atom_Id_pcie_ide_secured,
        Sim_Atom_Id_pcie_msg_vdm_subtype,
        Sim_Atom_Id_pcie_msg_vdm_vendor_id,
        Sim_Atom_Id_pcie_link_l0p_support,
        Sim_Atom_Id_pcie_msg_vdm_frs_reason,
        Sim_Atom_Id_arm_privileged = 0x200,
        Sim_Atom_Id_arm_nonsecure,
        Sim_Atom_Id_arm_memory_attributes,
        Sim_Atom_Id_arm_smmu_attributes,
        Sim_Atom_Id_arm_nsaid,
        Sim_Atom_Id_arm_device_id,
        Sim_Atom_Id_arm_smmu_qtw_access_type,
        Sim_Atom_Id_arm_axi_id,
        Sim_Atom_Id_riscv_wg_wid = 0x300,
        Sim_Atom_Id_riscv_device_id,
        Sim_Atom_Id_riscv_process_id,
        Sim_Atom_Id_riscv_io_error_ret,
        Sim_Atom_Id_cxl_type = 0x400,
} atom_id_t;

Python

import simics

simics.Sim_Atom_Id_pcie_prs_stop_marker
simics.Sim_Atom_Id_pcie_msg_vdm_vendor_id
simics.Sim_Atom_Id_trace_atom_access
simics.Sim_Atom_Id_initiator
simics.Sim_Atom_Id_riscv_process_id
simics.Sim_Atom_Id_data
simics.Sim_Atom_Id_arm_device_id
simics.Sim_Atom_Id_owner
simics.Sim_Atom_Id_pcie_device_id
simics.Sim_Atom_Id_user_data
simics.Sim_Atom_Id_pcie_link_negotiation
simics.Sim_Atom_Id_pcie_ecs
simics.Sim_Atom_Id_pcie_ats_translation_request_cxl_src
simics.Sim_Atom_Id_pcie_prs_page_group_response
simics.Sim_Atom_Id_pcie_link_flit_mode
simics.Sim_Atom_Id_fill_value
simics.Sim_Atom_Id_arm_memory_attributes
simics.Sim_Atom_Id_pcie_requester_segment
simics.Sim_Atom_Id_riscv_io_error_ret
simics.Sim_Atom_Id_pcie_pasid
simics.Sim_Atom_Id_pcie_ats_translation_request_no_write
simics.Sim_Atom_Id_arm_smmu_attributes
simics.Sim_Atom_Id_riscv_wg_wid
simics.Sim_Atom_Id_size
simics.Sim_Atom_Id_pcie_msg_vdm_subtype
simics.Sim_Atom_Id_bytemap
simics.Sim_Atom_Id_riscv_device_id
simics.Sim_Atom_Id_memop
simics.Sim_Atom_Id_pcie_requester_id
simics.Sim_Atom_Id_illegal
simics.Sim_Atom_Id_pcie_byte_count_ret
simics.Sim_Atom_Id_pcie_ide_secured
simics.Sim_Atom_Id_completion
simics.Sim_Atom_Id_list_end
simics.Sim_Atom_Id_cxl_type
simics.Sim_Atom_Id_pcie_ats_invalidate_completion_count
simics.Sim_Atom_Id_pcie_msg_vdm_frs_reason
simics.Sim_Atom_Id_pcie_prs_page_request
simics.Sim_Atom_Id_flags
simics.Sim_Atom_Id_pcie_link_l0p_support
simics.Sim_Atom_Id_pcie_type
simics.Sim_Atom_Id_arm_nonsecure
simics.Sim_Atom_Id_pcie_ats_invalidate_completion_itag_vector
simics.Sim_Atom_Id_arm_axi_id
simics.Sim_Atom_Id_pcie_msg_route
simics.Sim_Atom_Id_target_type
simics.Sim_Atom_Id_arm_nsaid
simics.Sim_Atom_Id_pcie_msg_type
simics.Sim_Atom_Id_pcie_error_ret
simics.Sim_Atom_Id_pcie_destination_segment
simics.Sim_Atom_Id_arm_smmu_qtw_access_type
simics.Sim_Atom_Id_pcie_ats_invalidate_request_itag
simics.Sim_Atom_Id_pcie_at
simics.Sim_Atom_Id_arm_privileged

Description

Each atom type is associated with a unique id, the atom_id_t. Most atoms types are pre-defined by Simics Core and have static ids, but there are also dynamically assigned ids which are used for custom atom types.

Atom ids are internal to Simics Core and should never be used explicitly by a Simics models. Instead, there are API functions like e.g. ATOM_size or ATOM_initiator which should be used instead.

Name

atom_t — basic type used inside transactions

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct {
        atom_id_t id;
#ifndef PYWRAP
        void *ptr;
#endif
} atom_t;

Python

import simics

class simics.atom_t

Description

The atom_t type is a container type for tagged data associated with a transaction. The kind of data stored in the atom is determined by the id field, and a pointer to the data or the data itself is stored in the ptr field.

Atoms should always be initialized using provided constructor functions like ATOM_flags or ATOM_size. Usage of the constructors ensures that the data payload is of the correct type and that the id is set to the correct value.

Atom lists must be terminated with the special ATOM_LIST_END marker.

Name

transaction_completion_t — callback type for transaction completion

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef exception_type_t (*transaction_completion_t)(conf_object_t *obj,
                                                     transaction_t *t,
                                                     exception_type_t ex);

Description

Callback invoked when an asynchronous transaction is completed. The callback is stored in a completion atom belonging to the transaction t. Similarly, obj is an object stored in either an owner atom or an initiator atom. The former takes precedence if both are present.

Completion callbacks are only invoked for transactions monitored with either SIM_monitor_transaction or SIM_monitor_chained_transaction, or for transactions deferred with SIM_defer_owned_transaction.

The completion status for the operation is given in the ex argument, and is usually equal to Sim_PE_No_Exception.

The return value of the callback is the completion status for the transaction t. This status is used to complete the parent transaction if the transaction is being monitored with SIM_monitor_chained_transaction. The return value is also returned by SIM_monitor_transaction or SIM_monitor_chained_transaction when a transaction is completed synchronously.

If the callback returns Sim_PE_Deferred, then the transaction t is left uncompleted. It must then be completed later on by an explicit call to SIM_complete_transaction.

Name

transaction_flags_t — flags used with transaction_t

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef enum {
        Sim_Transaction_Fetch         = 1 << 0,
        Sim_Transaction_Write         = 1 << 1,
        Sim_Transaction_Control       = 1 << 2,

        Sim_Transaction_Inquiry       = 1 << 8,
        Sim_Transaction_Incoherent    = 1 << 9,
        Sim_Transaction_Atomic        = 1 << 10,
} transaction_flags_t;

Python

import simics

simics.Sim_Transaction_Write
simics.Sim_Transaction_Fetch
simics.Sim_Transaction_Incoherent
simics.Sim_Transaction_Control
simics.Sim_Transaction_Atomic
simics.Sim_Transaction_Inquiry

Description

The transaction_flags_t type is bitmask used to specify the transaction type. It is a combination of the following bits:

Sim_Transaction_Fetch indicates that the transaction is an instruction fetch.

Sim_Transaction_Write is set if the transaction is a write.

Sim_Transaction_Control is set if the transaction does not actually transfer any data. One example of such transactions is cache control operations.

The Sim_Transaction_Inquiry bit signifies that side effects normally triggered by the transaction should be suppressed. Examples of side effects include triggering breakpoints and clearing “read-to-clear” device registers.

When neither Sim_Transaction_Fetch nor Sim_Transaction_Write is set the transaction is a read transaction.

Name

transaction_t — type of transactions

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef struct transaction {
#ifndef PYWRAP
        atom_t *atoms;
#endif
        struct transaction *prev;
#ifndef PYWRAP
        struct transaction_cache *_cache;
        uint64 _status;
#endif
} transaction_t;

Python

import simics

class simics.transaction_t(read = True, write = False, fetch = False, inquiry = False
                  prev = None, <atoms...>)

Description

A transaction_t represents a memory transaction. The properties of the transaction is stored in the form of an atom list, where each atom describes a particular aspect of the transaction, like the size of the transaction.

The field atoms points to the atoms list, which must be terminated with the constant ATOM_LIST_END.

The prev field points to an optional parent transaction. If a particular atom is not found in the atoms list, then the parent’s list of atoms is consulted instead. The prev pointer is also used when a chained transaction is monitored with SIM_monitor_chained_transaction.

Besides the fields above, the transaction contains some internal fields that should be initialized to 0. The internal fields should not be referenced explicitly since they are likely to change in future Simics releases.

For details, please refer to Transactions chapter in the Model Builder’s User Guide.

Name

translation_flags_t, translation_t — structure used with translator_interface_t

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef enum {
        Sim_Translation_Dynamic = 1,
        Sim_Translation_Ambiguous = 2
} translation_flags_t;

typedef struct translation {
        const map_target_t *target;  /* target of translation */

        physical_address_t base;     /* base address of translated range */
        physical_address_t start;    /* start address in mapped object */
        physical_address_t size;     /* size of translated range */

        translation_flags_t flags;
} translation_t;

Python

import simics

simics.Sim_Translation_Ambiguous
simics.Sim_Translation_Dynamic
class simics.translation_t(target=None, base=0, start=0, size=0, flags=0)

Description

The translation_t type is used for the implementation of the translator and transaction_translator interfaces. It describes the range for which the translation is valid, its target as well as translation properties.

The range for which the translation is valid is specified by the fields base and size. As a special case, if size and base are both 0, then the translation is valid for the entire address space. To allow optimizations (e.g., caching of translations) translators should return as wide ranges as possible.

The target field specifies the object and interface port which is mapped into the address range in the form of a map target. Map targets can be created using the function SIM_new_map_target.

Please note that the ownership over the returned map target is not transferred to the interface caller. This means that to avoid memory leaks the reference to the map target must be kept by the implementing object, and SIM_free_map_target function should be later used to deallocate the map target. Possible map targets include IO banks, RAM, ROM, memory spaces, port spaces, bridges, and translators. The base address in the source address space is mapped to the target address returned in the start field.

A null value returned in the target field signifies that the translation cannot be done. This can happen if there is nothing mapped in the range defined by base and size (transactions directed to this region will be terminated with the pseudo exception Sim_PE_IO_Not_Taken) or if a translation valid for all requested accesses cannot be performed. In the latter case, the requestor is expected to repeat the interface call with just a single bit set in the access mask, e.g. Sim_Access_Read.

If the returned translation is not static but instead depends on e.g. a device register, then the translator can set the flags field to Sim_Translation_Dynamic. This flag indicates that the translation must not be cached. If this flag is not used, then it is the responsibility of the translator to call either SIM_map_target_flush (preferably) or SIM_translation_changed function when a previously performed translation is no longer valid.

The Sim_Translation_Ambiguous flag should not generally be used by models. It is used by Simics objects of the memory-space class to indicate an error in the memory mapping when several destinations are specified for the address.

See Also

SIM_map_target_flush,SIM_translation_changed

Name

arm_cpu_state_t — structure that can hold the state of an ARM processor

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef struct arm_cpu_state {
        bool fmo_set; /* scr_el3.irq */
        bool imo_set;
        bool irq_set; /* scr_el3.irq */
        bool fiq_set; /* scr_el3.fiq */
        bool ns;
        int el;
        uint32 mpidr;
} arm_cpu_state_t;

Python

import simics

class simics.arm_cpu_state_t(fmo_set=False, imo_set=False, irq_set=False,
        fiq_set=False, ns=False, el=0, mpidr=0)

Name

arm_device_type_t — ARM device memory types

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_DeviceType_nGnRnE = 0x0,
        Arm_DeviceType_nGnRE  = 0x1,
        Arm_DeviceType_nGRE   = 0x2,
        Arm_DeviceType_GRE    = 0x3,
        Arm_DeviceType_Unknown
} arm_device_type_t;

Python

import simics

simics.Arm_DeviceType_Unknown
simics.Arm_DeviceType_nGnRnE
simics.Arm_DeviceType_nGRE
simics.Arm_DeviceType_GRE
simics.Arm_DeviceType_nGnRE

Description

Arm device memory types. Corresponds to the DeviceType pseudo code enumeration in the Armv8 A-profile Architecture Reference Manual.

Name

arm_mem_attr_t — ARM memory cacheability

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_MemAttr_NC = 0x0, // Non-cacheable
        Arm_MemAttr_WT = 0x2, // Write-through
        Arm_MemAttr_WB = 0x3, // Write-back
        Arm_MemAttr_Unknown
} arm_mem_attr_t;

Python

import simics

simics.Arm_MemAttr_NC
simics.Arm_MemAttr_WT
simics.Arm_MemAttr_WB
simics.Arm_MemAttr_Unknown

Description

Memory cacheability. Corresponds to the MemAttr pseudo code constants in the Armv8 A-profile Architecture Reference Manual.

Name

arm_mem_hint_t — ARM cache allocation hint

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_MemHint_No  = 0x0, // No Read-Allocate, No Write-Allocate
        Arm_MemHint_WA  = 0x1, // No Read-Allocate, Write-Allocate
        Arm_MemHint_RA  = 0x2, // Read-Allocate, No Write-Allocate
        Arm_MemHint_RWA = 0x3, // Read-Allocate, Write-Allocate
        Arm_MemHint_Unknown
} arm_mem_hint_t;

Python

import simics

simics.Arm_MemHint_Unknown
simics.Arm_MemHint_RWA
simics.Arm_MemHint_No
simics.Arm_MemHint_RA
simics.Arm_MemHint_WA

Description

Cache allocation hint. Corresponds to the MemHint pseudo code constants in the Armv8 A-profile Architecture Reference Manual.

Name

arm_mem_instr_origin_t — list of special memory operations that can be sent by a ARM processor

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        /* Normal load or store instructions */
        Instr_Normal_Arm = 0,

        /* Unprivileged memory access instructions. */
        Instr_Unprivileged_Load,
        Instr_Unprivileged_Store,

        /* Other loads/stores or cache affecting instructions */
        Instr_ldrex,
        Instr_strex,
        Instr_ldxp,
        Instr_stxp,

        /* Address translation instruction */
        Instr_At,

        /* Atomic read-modify-write instructions */
        Instr_Atomic,

        /* Cache maintenance instructions */
        Instr_Cache_Maintenance,

        /* Instruction with non-faulting memory access */
        Instr_Non_Faulting,

        /* Number of different of enum values, not a value in itself. */
        Instr_Count
} arm_mem_instr_origin_t;

Python

import simics

simics.Instr_ldrex
simics.Instr_ldxp
simics.Instr_stxp
simics.Instr_strex
simics.Instr_Normal_Arm
simics.Instr_Count
simics.Instr_Atomic
simics.Instr_Unprivileged_Load
simics.Instr_Cache_Maintenance
simics.Instr_At
simics.Instr_Unprivileged_Store
simics.Instr_Non_Faulting

Name

arm_mem_transient_t — ARM transcience hint

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_Transient_True,
        Arm_Transient_False,
        Arm_Transient_Unknown
} arm_mem_transient_t;

Python

import simics

simics.Arm_Transient_Unknown
simics.Arm_Transient_True
simics.Arm_Transient_False

Description

Transcience hint. Corresponds to the boolean used for transience by the pseudo code in the Armv8 A-profile Architecture Reference Manual.

Name

arm_mem_type_t — ARM memory types

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_MemType_Normal,
        Arm_MemType_Device
} arm_mem_type_t;

Python

import simics

simics.Arm_MemType_Device
simics.Arm_MemType_Normal

Description

Arm memory types. Corresponds to the MemType pseudo code enumeration in the Armv8 A-profile Architecture Reference

Name

arm_memory_attributes_encoding_t — ARM memory attributes encoding

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef union {
        struct {
                uint64 memory_type:2;            // arm_mem_type_t
                uint64 device_type:3;            // arm_device_type_t
                uint64 inner_cacheability:3;     // arm_mem_attr_t
                uint64 inner_allocation_hint:3;  // arm_mem_hint_t
                uint64 inner_transcience_hint:2; // arm_mem_transient_t
                uint64 outer_cacheability:3;     // arm_mem_attr_t
                uint64 outer_allocation_hint:3;  // arm_mem_hint_t
                uint64 outer_transcience_hint:2; // arm_mem_transient_t
                uint64 shareable:1;              // bool
                uint64 outer_shareable:1;        // bool
        } u;
        uint64 u64;
} arm_memory_attributes_encoding_t;

Description

This type should be used to encode or decode the uint64 value contained in an arm_memory_attributes atom. The comment beside each field is the type that should be used to interpret the field value.

Name

arm_memory_transaction_t — memory transaction specific to the Arm architecture

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef struct arm_memory_transaction {
        generic_transaction_t s;

        processor_mode_t mode;
        int rotate;
        arm_mem_instr_origin_t instr_origin;
} arm_memory_transaction_t;

Python

import simics

class simics.arm_memory_transaction_t(s = generic_transaction_t(),
        mode = Sim_CPU_Mode_User, instr_origin = Normal_Load_Store,
        rotate = 0)

Description

This is the ARM specific memory transaction data structure. The generic data is stored in the s field.

The mode field specifies the processor mode the MMU should assume when processing the transaction. This is the same as the current mode of the processor except for unprivileged load and store instructions when it is always Sim_CPU_Mode_User.

The rotate field is non-zero if this transaction is from one of the AArch32 instructions for which an unaligned address is interpreted as an aligned load with the value rotated so that the addressed byte becomes the least significant byte if neither SCTLR.U nor SCTLR.A is set.

The instr_origin field specifies the type of instruction that initiated this memory transaction.

Name

arm_smmu_attributes_t — ARM smmu attributes

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef union {
        struct {
                uint64 sid:32;    // IMPLEMENTATION DEFINED size, between 0 and 32 bits
                uint64 ssid:20;   // IMPLEMENTATION DEFINED size, between 0 and 20 bits
                uint64 secsid:1;  // bool
                uint64 ssidv:1;   // bool
                uint64 atst:1;    // bool
        } u;
       uint64 u64;
} arm_smmu_attributes_t;

Description

This type should be used to encode or decode the uint64 value contained in an arm_smmu_attributes atom. The comment beside each field is the type that should be used to interpret the field value.

Name

arm_smmu_qtw_access_type_t — Classification of the SMMU QTW/DVM access

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_SMMU_QTW_STE_Fetch,
        Arm_SMMU_QTW_CD_Fetch,
        Arm_SMMU_QTW_Page_Table_Walk,
        Arm_SMMU_QTW_Cmd_Queue_Walk,
        Arm_SMMU_QTW_DVM,
        Arm_SMMU_QTW_Event_Queue_Write,
        Arm_SMMU_QTW_PRI_Queue_Write,
        Arm_SMMU_QTW_MSI_Write,
        Arm_SMMU_QTW_HTTU_Write,
} arm_smmu_qtw_access_type_t;

Python

import simics

simics.Arm_SMMU_QTW_HTTU_Write
simics.Arm_SMMU_QTW_CD_Fetch
simics.Arm_SMMU_QTW_STE_Fetch
simics.Arm_SMMU_QTW_PRI_Queue_Write
simics.Arm_SMMU_QTW_Page_Table_Walk
simics.Arm_SMMU_QTW_Event_Queue_Write
simics.Arm_SMMU_QTW_DVM
simics.Arm_SMMU_QTW_MSI_Write
simics.Arm_SMMU_QTW_Cmd_Queue_Walk

Description

Classifies the SMMU QTW/DVM access that produced a transaction. Provides finer granularity than the hardware arid_qtw/awid_qtw signals define.

Name

arm_translation_regime_t — ARM MMU translation regime

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

typedef enum {
        Arm_TR_EL3,  /* EL3         */
        Arm_TR_EL2,  /* EL2   PL2   */
        Arm_TR_EL20, /* EL2&0       */
        Arm_TR_EL10, /* EL1&0 PL1&0 */
} arm_translation_regime_t;

Python

import simics

simics.Arm_TR_EL2
simics.Arm_TR_EL3
simics.Arm_TR_EL10
simics.Arm_TR_EL20

Description

Arm MMU translation regimes. Named after the AArch64 translation regimes, but also used for the AArch32 ones.

Name

decoder_t — type used with user decoder

Synopsis

C and DML

#include <simics/model-iface/decoder.h> // in C
import "simics/model-iface/decoder.dml"; // in DML

typedef struct {
        void *user_data;
        int (*NOTNULL decode)(uint8 *code,
                              int valid_bytes,
                              conf_object_t *cpu,
                              instruction_info_t *ii,
                              void *user_data);
        tuple_int_string_t (*NOTNULL disassemble)(uint8 *code,
                                                  int valid_bytes,
                                                  conf_object_t *cpu,
                                                  void *user_data);
        int (*NOTNULL flush)(instruction_info_t *ii,
                             void *user_data);
} decoder_t;

Description

The decode function is called to decode an instruction pointed to by code. The first byte corresponds to the lowest address of the instruction in the simulated memory. valid_bytes tells how many bytes can be read. The CPU is given in the cpu parameter. When the decoder has successfully decoded an instruction, it should set the ii_ServiceRoutine, the ii_Arg, and the ii_Type members of the instruction_info_t structure, and returns the number of bytes used in the decoding. If it does not apply to the given instruction, it should return zero. If the decoder needs more data than valid_bytes it should return a negative number corresponding to the total number of bytes it will need to continue the decoding. The underlying architecture limits the number of bytes that can be requested, e.g. no more than 4 bytes can be requested on most RISC architectures. Simics will call the decoder again when more bytes are available. This process is repeated until the decoder accepts or rejects the instruction. A decoder should never request more data than it needs. For example, if an instructions can be rejected by looking at the first byte, the decoder should never ask for more bytes.

The disassemble function is called to disassemble an instruction. It uses the same code, valid_bytes, and cpu parameters as the decode function. If the disassembly is valid, then the string part of the returned tuple_int_string_t struct should be a MALLOCed string with the disassembly and the integer part should be its length in bytes. The caller is responsible for freeing the disassembly string. The string member should be NULL and the integer part should be zero if the disassembly is not valid. If the disassemble function needs more data than valid_bytes it should return a negative number in the integer part in the same way as the decode function, and set the string part to NULL.

The flush function is called to free any memory allocated when decoding an instruction and any user data associated with the instruction. It should return zero if it does not recognize the instruction, and non-zero if it has accepted it. Usually, the way to recognize if a decoded instruction is the right one to flush is to compare ii->ii_ServiceRoutine with the function that was set in the decode function. Note that the cpu parameter is the processor that caused the flush. It is more or less an arbitrary processor and should be ignored.

In addition to the function pointers, the decoder_t structure contains a user_data pointer that is passed to all the functions. This can be used for passing any data to the decoder functions.

See Also

service_routine_t,instruction_info_t, decoder interface.

Name

instruction_info_t — type used with user decoder

Synopsis

C and DML

#include <simics/model-iface/decoder.h> // in C
import "simics/model-iface/decoder.dml"; // in DML

typedef struct instruction_info {
        service_routine_t  ii_ServiceRoutine;
        uint64             ii_Arg;
        unsigned int       ii_Type;
        lang_void         *ii_UserData;
        logical_address_t  ii_LogicalAddress;
        physical_address_t ii_PhysicalAddress;
} instruction_info_t;

Description

ii_ServiceRoutine is a pointer to a function that will be called by Simics every time the instruction is executed. It has the type service_routine_t.

Note that in a shared memory multiprocessor, the CPU used in decoding may differ from the CPU that executes the instruction, since the decoded instructions may be cached.

ii_Arg is the argument arg that will be passed on to the service routine function. Op code bit-fields for the instruction such as register numbers or intermediate values can be stored here. The ii_UserData field can also be used to pass information to the service routine if more data is needed.

ii_Type is either UD_IT_SEQUENTIAL or UD_IT_CONTROL_FLOW. A sequential type means that the instruction does not perform any branches and the update of the program counter(s) is handled by Simics. In a control flow instruction on the other hand it is up to the user to set the program counter(s).

ii_LogicalAddress and ii_PhysicalAddress holds the logical and physical addresses of the instruction to be decoded.

See also

service_routine_t,decoder_t, decoder interface.

Name

interrupt_ack_fn_t — function type used with acked interrupts.

Synopsis

C and DML

#include <simics/devs/interrupt-ack.h> // in C
import "simics/devs/interrupt-ack.dml"; // in DML

typedef int (*interrupt_ack_fn_t)(conf_object_t *NOTNULL);

Description

The interrupt_ack_fn_t function is called by an interrupt target to ack an interrupt. Returns the interrupt vector.

Name

mips_memory_transaction_t — memory transaction type used with MIPS cores

Synopsis

C and DML

#include <simics/arch/mips.h> // in C
import "simics/arch/mips.dml"; // in DML

typedef struct mips_memory_transaction {

        /* generic transaction */
        generic_transaction_t s;

        /* Cache coherency, values as the C field in EntryLo0 and EntryLo1. */
        unsigned int cache_coherency:3;
} mips_memory_transaction_t;

Python

import simics

class simics.mips_memory_transaction_t(s = generic_transaction_t(),
        cache_coherency = 0)

Description

This is the MIPS specific memory transaction data structure. The generic data is stored in the s field.

The cache_coherency field specifies the cache coherency attribute of the memory transaction, as defined by the C field of the EntryLo0 and EntryLo1 coprocessor 0 registers.

Name

nios_memory_transaction_t — memory transaction specific to the Nios architecture

Synopsis

C and DML

#include <simics/arch/nios.h> // in C
import "simics/arch/nios.dml"; // in DML

typedef struct nios_memory_transaction {
        /* generic transaction */
        generic_transaction_t s;
} nios_memory_transaction_t;

Description

The s field contains generic information about memory operations (see generic_transaction_t).

Name

pci_memory_transaction_t — generic transaction initiated by PCI devices

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef struct pci_memory_transaction {
        generic_transaction_t INTERNAL_FIELD(s);
        uint32 INTERNAL_FIELD(original_size);

        int INTERNAL_FIELD(bus_address);

        int INTERNAL_FIELD(bus_number);
        int INTERNAL_FIELD(device_number);
        int INTERNAL_FIELD(function_number);

        uint32 INTERNAL_FIELD(tlp_prefix);
} pci_memory_transaction_t;

Python

import simics

class simics.pci_memory_transaction_t(_internal_s = generic_transaction_t(),
        _internal_original_size = 0, _internal_bus_address = 0,
        _internal_bus_number = 0, _internal_device_number = 0,
        _internal_function_number = 0, _internal_tlp_prefix = 0)

Description

The pci_memory_transaction_t is used for memory accesses initiated by PCI devices.

All struct fields are internal and should never be used directly.

A generic_transaction_t can be converted to a pci_memory_transaction_t via the SIM_pci_mem_trans_from_generic function. Never explicitly cast one struct to the other, always use the Simics API functions.

See Also

SIM_pci_mem_trans_from_generic, generic_transaction_t

Name

pcie_ide_secured_t — PCIe IDE Secured TLP

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef struct {
    bool t;  // Trusted Execution
    bool k;  // Key set
    bool m;  // MAC included
    bool p;  // PCRC included
    uint8 sub_stream;
    uint8 stream_id;
    uint8 pr_sent_counter;
} pcie_ide_secured_t;

Python

import simics

class simics.pcie_ide_secured_t(t=False, k=False, m=False, p=False, sub_stream=0,
        stream_id=0, pr_sent_counter=0)

Description

This type is used contain PCIe IDE Secured TLP.

Name

pcie_link_flit_mode_t — PCIe link Flit Mode

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef struct {
        bool enable_flit_mode;
} pcie_link_flit_mode_t;

Python

import simics

class simics.pcie_link_flit_mode_t(enable_flit_mode=False)

Description

This type is used to indicate to a peer that it wants to use Flit Mode if the peer supports it. The peer sets the enable_flit_mode field to true in the struct to agree that Flit mode should be used.

Name

pcie_link_l0p_support_t — PCIe link L0p support

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef struct {
        bool enable_l0p_support;
} pcie_link_l0p_support_t;

Python

import simics

class simics.pcie_link_l0p_support_t(enable_l0p_support=False)

Description

This type is used to indicate to a peer that it supports the L0p link state. The peer sets the enable_l0p_support field to true in the struct to agree that the L0p link state should be used.

Name

pcie_link_negotiation_t — PCIe link negotiation attributes

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef struct {
        pcie_link_speed_t maximum_link_speed;
        pcie_link_width_t maximum_link_width;
        pcie_link_speed_t negotiated_link_speed;
        pcie_link_width_t negotiated_link_width;
} pcie_link_negotiation_t;

Python

import simics

class simics.pcie_link_negotiation_t(maximum_link_speed=PCIE_Link_Speed_Undefined,
        maximum_link_width=PCIE_Link_Width_Undefined,
        negotiated_link_speed=PCIE_Link_Speed_Undefined,
        negotiated_link_width=PCIE_Link_Width_Undefined)

Description

This type is used to send desired (maximum) link attributes to a peer who then sets the negotiated link speed and width based on the supported values of both peers.

Name

pcie_link_speed_t — PCIe link speeds

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef enum {
        PCIE_Link_Speed_Undefined = 0,
        PCIE_Link_Speed_2_5       = 1,
        PCIE_Link_Speed_5         = 2,
        PCIE_Link_Speed_8         = 4,
        PCIE_Link_Speed_16        = 8,
        PCIE_Link_Speed_32        = 16,
        PCIE_Link_Speed_64        = 32,
        PCIE_Link_Speed_128       = 64,
} pcie_link_speed_t;

Python

import simics

simics.PCIE_Link_Speed_8
simics.PCIE_Link_Speed_2_5
simics.PCIE_Link_Speed_64
simics.PCIE_Link_Speed_16
simics.PCIE_Link_Speed_Undefined
simics.PCIE_Link_Speed_128
simics.PCIE_Link_Speed_5
simics.PCIE_Link_Speed_32

Description

This type is used to indicate PCIe link speeds.

Name

pcie_link_width_t — PCIe link widths

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef enum {
        PCIE_Link_Width_Undefined  = 0,
        PCIE_Link_Width_x1         = 1,
        PCIE_Link_Width_x2         = 2,
        PCIE_Link_Width_x4         = 4,
        PCIE_Link_Width_x8         = 8,
        PCIE_Link_Width_x16        = 16,
} pcie_link_width_t;

Python

import simics

simics.PCIE_Link_Width_x4
simics.PCIE_Link_Width_x1
simics.PCIE_Link_Width_x8
simics.PCIE_Link_Width_x2
simics.PCIE_Link_Width_Undefined
simics.PCIE_Link_Width_x16

Description

This type is used to indicate PCIe link widths.

Name

pcie_msg_vdm_frs_reason_t — Reasons field for FRS

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef enum {
        /* DRS Message Received: The Downstream Port indicated by the Message
           Requester ID received a DRS Message and has the DRS Signaling Control
           field in the Link Control Register set to DRS to FRS Signaling
           Enabled. */
        PCIE_MSG_VDM_FRS_DRS_Message_Received = 0x01,

        /* D3Hot to D0 Transition Completed: A D3Hot to D0 transition has
           completed, and the Function indicated by the Message Requester ID is
           now Configuration-Ready and has returned to the D0uninitialized or
           D0active state depending on the setting of the No_Soft_Reset bit. */
        PCIE_MSG_VDM_FRS_D3Hot_to_D0_Completed = 0x02,

        /* FLR Completed: An FLR has completed, and the Function indicated by
           the Message Requester ID is now Configuration-Ready. */
        PCIE_MSG_VDM_FRS_FLR_Completed = 0x03,

        /* VF Enabled: The Message Requester ID indicates a Physical Function
           (PF) - All Virtual Functions (VFs) associated with that PF are now
           Configuration-Ready. */
        PCIE_MSG_VDM_FRS_VF_Enabled = 0x08,

        /* VF Disabled: The Message Requester ID indicates a PF - All VFs
           associated with that PF have been disabled and the SR-IOV data
           structures in that PF may now be accessed. */
        PCIE_MSG_VDM_FRS_VF_Disabled = 0x09,
} pcie_msg_vdm_frs_reason_t;

Python

import simics

simics.PCIE_MSG_VDM_FRS_VF_Enabled
simics.PCIE_MSG_VDM_FRS_FLR_Completed
simics.PCIE_MSG_VDM_FRS_VF_Disabled
simics.PCIE_MSG_VDM_FRS_DRS_Message_Received
simics.PCIE_MSG_VDM_FRS_D3Hot_to_D0_Completed

Description

Reason field encoded in a Function Readiness Status (FRS) message. Indicates why the Function Readiness Status message was sent.

Name

pcie_msg_vdm_subtype_t — PCIe message VDM subtype

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef enum {
        PCIE_VDM_Hierarchy_Id = 0x01,
        PCIE_VDM_Device_Readiness_Status = 0x08,
        PCIE_VDM_Function_Readiness_Status = 0x09,
} pcie_msg_vdm_subtype_t;

Python

import simics

simics.PCIE_VDM_Function_Readiness_Status
simics.PCIE_VDM_Hierarchy_Id
simics.PCIE_VDM_Device_Readiness_Status

Description

This atom can be included in Vendor-Defined Type 1 Messages (transactions that have the pcie_type atom set to PCIE_Type_Msg, pcie_message_type atom set to PCIE_Vendor_Defined_Type_1 and pcie_msg_vdm_vendor_id atom set to 0x0001) to indicate the subtype of th PCI-SIG VDM 1 message.

Name

pcie_msg_vdm_vendor_id_t — PCIE VDM message vendor id

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef uint16 pcie_msg_vdm_vendor_id_t;

Description

This atom can be included in Vendor-Defined Type 1 Messages (transactions that have the pcie_type atom set to PCIE_Type_Msg and pcie_message_type atom set to PCIE_Vendor_Defined_Type_0 or PCIE_Vendor_Defined_Type_1) to indicate the vendor id of the VDM message.

Name

pcie_pasid_info_t — PCIe PASID information

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef union {
    struct {
        uint32 pasid:20;    // PASID
        uint32 exe:1;       // Execute Requested
        uint32 priv:1;      // Privileged Mode Requested
    } field;
    uint32 u32;
} pcie_pasid_info_t;

Description

This type contain the PASID Information in the pcie_pasid transaction atom.

Name

pcie_prs_page_group_response_t — PCIe PRS page response data

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef union {
        struct {
                uint16 prgi:9;  // Page request group
                uint16 rsvd:3;
                uint16 response_code:4;  // Response code
        } field;
        uint16 u16;
} pcie_prs_page_group_response_t;

Description

This type is used contain PCIe PRS page response data.

Name

pcie_prs_page_request_t — PCIe PRS page request data

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef union {
        struct {
                uint64 r:1;     // Read access
                uint64 w:1;     // Write access
                uint64 l:1;     // Last
                uint64 prgi:9;  // Page request group
                uint64 page_addr: 52;
        } field;
        uint64 u64;
} pcie_prs_page_request_t;

Description

This type is used contain PCIe PRS page request data.

Name

pcie_prs_response_code_t — PCIe PRS Response Message Code

Synopsis

C and DML

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

typedef enum {
        PCIE_PRS_Response_Success = 0,
        PCIE_PRS_Response_Invalid_Request = 1,
        PCIE_PRS_Response_Failure = 15,
} pcie_prs_response_code_t;

Python

import simics

simics.PCIE_PRS_Response_Failure
simics.PCIE_PRS_Response_Invalid_Request
simics.PCIE_PRS_Response_Success

Description

This type is used to indicate PCIe PRS Response Message Code.

Name

ppc_mem_instr_origin_t — PPC special memory operations

Synopsis

C and DML

#include <simics/arch/ppc.h> // in C
import "simics/arch/ppc.dml"; // in DML

typedef enum {
        /* Normal load or store instructions */
        Normal_Load_Store = 0,

        /* No data touched by the load/store will be placed in cache */
	    Caching_Inhibited,

        Instr_Multiple,         /* load/store multiple */
        Instr_String,           /* load/store string */

        Instr_Altivec_Element,  /* Altivec load/store element */

        /* Data cache manipulations */
        Instr_dcbt,             /* data cache block touch */
        Instr_dcbst,            /* data cache block store */
        Instr_dcbtst,           /* data cache block touch for store */
        Instr_dcbi,             /* data cache block invalidate */
        Instr_dcbf,             /* data cache block flush */
        Instr_dcbfl,            /* data cache block flush local */
        Instr_dcba,             /* data cache block allocate */
        Instr_dcbz,             /* data cache block to zero */

        /* Instruction cache manipulations */
        Instr_icbi,             /* instruction cache block invalidate */

        /* Data stream (Altivec) manipulations */
        Instr_dst,              /* data stream touch */
        Instr_dstt,             /* data stream touch transient */
        Instr_dstst,            /* data stream touch for store */
        Instr_dststt,           /* data stream touch for store transient */

        /* e500 cache lock apu instructions */
        Instr_dcblc_l1,         /* data cache block lock clear (L1) */
        Instr_dcblc_l2,         /* data cache block lock clear (L2) */
        Instr_dcbtls_l1,        /* data cache block touch and lock set (L1)*/
        Instr_dcbtls_l2,        /* data cache block touch and lock set (L1)*/
        Instr_dcbtstls_l1,      /* data cache block touch for store and lock
                                   set (L1)*/
        Instr_dcbtstls_l2,      /* data cache block touch for store and lock
                                   set (L1)*/
        Instr_icblc_l1,         /* instruction cache block clear (L1) */
        Instr_icblc_l2,         /* instruction cache block clear (L2) */
        Instr_icbtls_l1,        /* instruction cache block touch and lock
                                   set (L1) */
        Instr_icbtls_l2,        /* instruction cache block touch and lock
                                   set (L1) */

        /* Other loads/stores or cache affecting instructions */
        Instr_lwarx,
        Instr_stwcx,
        Instr_ldarx,
        Instr_stdcx,
        Instr_lq,
        Instr_stq,

        /* Other cache affecting instructions */
        Instr_sync,
        Instr_eieio,
        Instr_ecowx,
        Instr_eciwx,
        Instr_tlbie,
        Instr_tlbsync,
        Instr_isync,

        Instr_lfdp,             /* Load Floating point Double Pair */
        Instr_stfdp,            /* Store Floating point Double Pair */

        Instr_spe,

        Instr_dcbal,            /* Obsolete - use Instr_dcba. */

        /* e500 cache lock apu instructions, platform cache versions */
        Instr_dcblc_pc,         /* data cache block lock clear */
        Instr_dcbtls_pc,        /* data cache block touch and lock set*/
        Instr_dcbtstls_pc,      /* data cache block touch for store and lock
                                   set */
        Instr_icblc_pc,         /* instruction cache block clear */
        Instr_icbtls_pc,        /* instruction cache block touch and lock
                                   set */
        Instr_Fpu               /* Load/store from FPU unit */
} ppc_mem_instr_origin_t;

Python

import simics

simics.Instr_icblc_l1
simics.Instr_stwcx
simics.Instr_Altivec_Element
simics.Instr_dcbi
simics.Instr_Fpu
simics.Instr_ecowx
simics.Normal_Load_Store
simics.Instr_icbtls_l1
simics.Instr_icbtls_l2
simics.Instr_dcbtls_l2
simics.Instr_lfdp
simics.Instr_sync
simics.Instr_stfdp
simics.Instr_String
simics.Instr_lq
simics.Instr_dcbfl
simics.Instr_dcblc_pc
simics.Instr_Multiple
simics.Instr_dcbz
simics.Instr_dstst
simics.Instr_tlbsync
simics.Instr_icbtls_pc
simics.Instr_dcbal
simics.Instr_eieio
simics.Instr_dststt
simics.Instr_isync
simics.Instr_stq
simics.Instr_dst
simics.Instr_dcba
simics.Instr_ldarx
simics.Instr_tlbie
simics.Instr_dcbtls_l1
simics.Instr_dcbtls_pc
simics.Instr_dcbtstls_pc
simics.Instr_icblc_pc
simics.Instr_dcblc_l2
simics.Instr_icbi
simics.Caching_Inhibited
simics.Instr_dcbtstls_l1
simics.Instr_eciwx
simics.Instr_dcblc_l1
simics.Instr_stdcx
simics.Instr_spe
simics.Instr_dcbf
simics.Instr_dcbst
simics.Instr_dcbtst
simics.Instr_icblc_l2
simics.Instr_lwarx
simics.Instr_dcbt
simics.Instr_dcbtstls_l2
simics.Instr_dstt

Description

List of special memory operations that can be send by a PPC processor.

Name

ppc_decoration_type_t, ppc_decoration_t, ppc_memory_transaction_t — memory transaction used with ppc

Synopsis

C and DML

#include <simics/arch/ppc.h> // in C
import "simics/arch/ppc.dml"; // in DML

typedef enum {
        Decoration_None,
        Decoration_Notify,
        Decoration_Load,
        Decoration_Store
} ppc_decoration_type_t;

typedef struct {
        ppc_decoration_type_t type;
        uint64 data;
} ppc_decoration_t;

typedef struct ppc_memory_transaction {

        /* generic transaction */
        generic_transaction_t s;

        processor_mode_t mode;
        ppc_mem_instr_origin_t instr_origin;
        logical_address_t ea_origin;
        uint8 wimg;
        uint8 alignment;

        /* cache operations may flag this to cause prefetches to be no-ops */
        uint8 inhibit_exception;

        /* External PID */
        uint8 external_pid;

        /* Decorated storage */
        ppc_decoration_t decoration;
} ppc_memory_transaction_t;

Python

import simics

simics.Decoration_Load
simics.Decoration_Notify
simics.Decoration_Store
simics.Decoration_None
class simics.ppc_decoration_t
class simics.ppc_memory_transaction_t(s = generic_transaction_t(),
        mode = Sim_CPU_Mode_User, instr_origin = Normal_Load_Store,
        ea_origin = 0, wimg = 0, alignment = 0, inhibit_exception = 0,
        external_pid = 0, decoration = ppc_decoration_t())

Description

This is the PPC specific memory transaction data structure. The generic data is stored in the s field.

The current processor mode when generating this transaction is stored in the mode field.

The type of instruction generating the memory transactions is provided by the instr_origin field. Note that it is mainly provided for special memory accesses like cache block operations..

The wimg field is filled in by the MMU with the corresponding WIMG bits during the translation.

The alignment field contains the size on which the transaction is required to be aligned.

The inhibit_exception field is set for operations that should be ignored if triggering an exception.

The external_pid field is only used internally for some Book-E cores. It is undefined for cores which do not have this feature.

decoration contains decoration data.

The type field specifies whether the transaction is decorated or not, and if it is, the decoration type.

The data field holds the decoration data supplied by the instruction. It is only valid if type is not Decoration_None.

Note

Not all processors implement decorated storage.

Name

riscv_cpu_mode_t — list of privilege levels of the RISC-V core

Synopsis

C and DML

#include <simics/arch/risc-v.h> // in C
import "simics/arch/risc-v.dml"; // in DML

typedef enum {
        Riscv_Mode_User            = 0x0,
        Riscv_Mode_Supervisor      = 0x1,
        Riscv_Mode_Reserved        = 0x2,
        Riscv_Mode_Machine         = 0x3,

        Riscv_Mode_Guest_User       = 0x10,
        Riscv_Mode_Guest_Supervisor = 0x11
} riscv_cpu_mode_t;

Python

import simics

simics.Riscv_Mode_Supervisor
simics.Riscv_Mode_Reserved
simics.Riscv_Mode_Machine
simics.Riscv_Mode_Guest_Supervisor
simics.Riscv_Mode_User
simics.Riscv_Mode_Guest_User

Name

riscv_io_error_t, riscv_io_error_ret_t — values and structures used to signal back transaction errors to RISC-V cores

Synopsis

C and DML

#include <simics/arch/risc-v.h> // in C
import "simics/arch/risc-v.dml"; // in DML

typedef enum {
        Riscv_No_IO_Error               = 0x00,
        Riscv_Throw_Access_Fault        = 0x01,
        Riscv_Clint_Wrong_Sized_Access  = 0x10,
        Riscv_WG_Access_WID_Not_Allowed = 0x20,
} riscv_io_error_t;

typedef struct
{
        uint64 val;
} riscv_io_error_ret_t;

Python

import simics

simics.Riscv_Clint_Wrong_Sized_Access
simics.Riscv_Throw_Access_Fault
simics.Riscv_No_IO_Error
simics.Riscv_WG_Access_WID_Not_Allowed
class simics.riscv_io_error_ret_t

Description

The ATOM riscv_io_error_ret is added to all transactions originating from RISC-V cores. The values defined by riscv_io_error_t can be used to signal various access errors back to the the core.

To report, write an error value to the address pointed to by the ATOM riscv_io_error_ret.

Name

service_routine_t — type used with user decoder

Synopsis

C and DML

#include <simics/model-iface/decoder.h> // in C
import "simics/model-iface/decoder.dml"; // in DML

typedef exception_type_t (*service_routine_t)(conf_object_t *cpu,
                                              uint64 arg,
                                              lang_void *user_data);

Description

The service routine function should return an exception when it is finished to signal its status. If no exception occurs Sim_PE_No_Exception should be returned.

See exception_type_t in for the different exceptions available.

A special return value, Sim_PE_Default_Semantics, can be returned; this signals Simics to run the default semantics for the instruction. This is useful if the semantics of an instruction should be changed but the user routine does not want to handle it all the time.

See also

instruction_info_t, decoder_t, decoder interface.

Name

usb_transfer_t — type used for data transfer over USB

Synopsis

C and DML

#include <simics/devs/usb.h> // in C
import "simics/devs/usb.dml"; // in DML

typedef struct {
        /* Endpoint/function specific information */
        uint8                 function_address;
        uint8                 endpoint_number;
        /* Type specific information */
        usb_type_t            type;
#ifndef PYWRAP
        union {
                usb_device_request_t   control_request;
                nano_secs_t            periodic_time;
        } u;
#endif /* PYWRAP */
        /* Data specific */
        usb_direction_t       direction;
        int                   size;
        dbuffer_t             *buf;
        /* Status */
        usb_status_t          status;
} usb_transfer_t;

Python

import simics

class simics.usb_transfer_t

Description

All USB related data types are Simics internal, and should not be used by user-defined classes. The data types may change in future versions of Simics.

The usb_transfer_t type is independent of USB host and USB device implementations and is used for sending data over USB.

There are two fields to identify the pipe: function_address is the function/device address for the target USB device; endpoint_number specifies the endpoint number.

The type of transfer is defined using the type field. The type is either control, bulk, interrupt, or isochronous. The u.control_request field is only valid for control transfers. It contains the information that would be in the setup packet of a control transfer. The u.periodic_time field is only valid for periodic transfers, i.e., interrupt and isochronous transfers. It specifies the minimum response time for a transfer expected by the USB host. A USB device do not need to fulfill the expectation. It is merely a way to tell the USB device how to keep the timing specified in the periodic list scheduling.

The usb_direction field specifies the direction of the data in the USB transfer. Only the actual data packet is used to specify the direction, even if a real transfer consists of a mix of SETUP/OUT/IN/STATUS packets. USB_Direction_None means that the transfer does not contain any data, for example, in Set_Address control transfers. size is the number of bytes the USB host can receive for IN transfers and the number of bytes sent for OUT transfers. buf contains the IN or OUT data. Note that buf can contain data for several data packets concatenated together. The endpoint descriptors in USB host and USB device define the maximum packet size for the pipe, but there is no limitation in Simics.

The status field contains the status for the transfer. The status is typically only set by the USB device. The USB host does not set the status field when it has completed an IN transfer.

Name

x86_access_type_t — type used with x86 accesses

Synopsis

C and DML

#include <simics/arch/x86-memop.h> // in C
import "simics/arch/x86-memop.dml"; // in DML

typedef enum x86_access_type {
        FOR_X86_ACCESS_TYPES(X86_ACCESS_TYPE_ENUM)
} x86_access_type_t;

Python

import simics

simics.X86_Pml4
simics.X86_Fpu_Env
simics.X86_Smm_State
simics.X86_Instruction
simics.X86_Prefetch_T2
simics.X86_Pde
simics.X86_Non_Temporal
simics.X86_Access_Simple
simics.X86_Pml5e
simics.X86_Vmx_Vapic
simics.X86_Pml_Log
simics.X86_Stack
simics.X86_Vmx_IO_Bitmap
simics.X86_Fpu
simics.X86_Task_Segment
simics.X86_Pd
simics.X86_Microcode_Update
simics.X86_Fpu_State
simics.X86_Other
simics.X86_Prefetchw_3DNow
simics.X86_Pt
simics.X86_Prefetch_T0
simics.X86_Invvpid_Descriptor
simics.X86_Pdp_Pae
simics.X86_Invept_Descriptor
simics.X86_Atomic_Info
simics.X86_Pml4e
simics.X86_Vanilla
simics.X86_Pdp
simics.X86_Cmpxchg16b
simics.X86_Far_Call_Parameter
simics.X86_Vmx_Msr
simics.X86_Ldt
simics.X86_Prefetch_NTA
simics.X86_Sppt
simics.X86_Sse
simics.X86_Processor_Trace
simics.X86_Loadall
simics.X86_Shadow_Stack
simics.X86_Task_Switch
simics.X86_Vmx_Msr_Bitmaps
simics.X86_Prefetch_T1
simics.X86_Vmx_Pasid_Translation
simics.X86_Stack_Explicit
simics.X86_Vmcs
simics.X86_Prefetch_3DNow
simics.X86_Clflush
simics.X86_Gdt
simics.X86_Access_Type_Last
simics.X86_Pdpte
simics.X86_Vmx_EPTP_List
simics.X86_Pebs
simics.X86_Vmx_VE_Info
simics.X86_Pml5
simics.X86_Pte
simics.X86_Prefetch_Other
simics.X86_Idt
simics.X86_Mtt_Metadata

Description

See online help for expanded output of this type: api-help x86_access_type_t

Name

x86_exception_source_t — x86 exception sources

Synopsis

C and DML

#include <simics/arch/x86.h> // in C
import "simics/arch/x86.dml"; // in DML

typedef enum {
        X86_Exc_Hardware,
        X86_Exc_Software,
        X86_Exc_External,
        X86_Exc_Software_Debug,
        X86_Exc_Software_Priv,
        X86_Exc_Triple_Fault,
        X86_Exc_NMI,
        X86_Exc_Other_Event
} x86_exception_source_t;

Python

import simics

simics.X86_Exc_Triple_Fault
simics.X86_Exc_Software
simics.X86_Exc_Hardware
simics.X86_Exc_Software_Debug
simics.X86_Exc_NMI
simics.X86_Exc_External
simics.X86_Exc_Other_Event
simics.X86_Exc_Software_Priv

Description

Defines different exception sources for a given exception/interrupt.

Name

x86_memory_transaction_t — generic_transaction used with x86 accesses

Synopsis

C and DML

#include <simics/arch/x86-memop.h> // in C
import "simics/arch/x86-memop.dml"; // in DML

typedef struct x86_memory_transaction {
        generic_transaction_t s;                /* Superclass */
        linear_address_t      linear_address;
        physical_address_t    guest_physical_address;
        uint16                segnum;           /* segment number */
        uint16                access_linear:1;  /* Linear access */
        uint16                io:1;             /* I/O (port) access */
        uint16                fault_as_if_write:1;
        uint16                guest_phys_valid:1;
        processor_mode_t      mode;
        x86_access_type_t     access_type;
        x86_memory_type_t     pat_type;
        x86_memory_type_t     mtrr_type;
        x86_memory_type_t     effective_type;
        int                   sequence_number; /* used for -stall */
        linear_address_t      original_linear_address;
} x86_memory_transaction_t;

Python

import simics

class simics.x86_memory_transaction_t(s = generic_transaction_t(),
        linear_address = 0, guest_physical_address = 0, segnum = 0,
        access_linear = 0, io = 0, fault_as_if_write = 0,
        guest_phys_valid = 0, mode = Sim_CPU_Mode_User,
        access_type = X86_Other, pat_type = X86_None, mtrr_type = X86_None,
        effective_type = X86_None, sequence_number = 0)

Description

The s field contains generic information about memory operations (see generic_transaction_t).

The mode is the current mode (user or supervisor) of the cpu.

The linear_address contains the address for transactions with linear addresses.

The access_linear flag is set for all transactions with linear addresses.

The io flag is set on port accesses (from IN and OUT instructions). It is cleared for regular memory accesses, and also for memory mapped I/O.

The fault_as_if_write flag indicates that an access should set the page fault access bits as a write even if the access is a read.

The access_type field in the type x86_access_type_t contains the kind of the transaction.

The effective memory type for the access is contained in effective_type. The MMU calculates the effective memory type and uses the pat_type and mtrr_type members as temporary storage and input to that calculation. The pat_type and mtrr_type members should not be used by code outside of the MMU. All these fields use the type x86_memory_type_t.

The original_linear_address holds the linear address before a linear-address masking is applied.

Name

x86_memory_type_t — type used with x86 accesses

Synopsis

C and DML

#include <simics/arch/x86-memop.h> // in C
import "simics/arch/x86-memop.dml"; // in DML

typedef enum {
        X86_None,
        X86_Strong_Uncacheable,    /* UC */
        X86_Uncacheable,           /* UC- */
        X86_Write_Combining,       /* WC */
        X86_Write_Through,         /* WT */
        X86_Write_Back,            /* WB */
        X86_Write_Protected        /* WP */
} x86_memory_type_t;

Python

import simics

simics.X86_Write_Combining
simics.X86_Strong_Uncacheable
simics.X86_None
simics.X86_Uncacheable
simics.X86_Write_Protected
simics.X86_Write_Back
simics.X86_Write_Through

Name

x86_processor_mode_t — x86 processor mode

Synopsis

C and DML

#include <simics/arch/x86.h> // in C
import "simics/arch/x86.dml"; // in DML

typedef enum {
        X86_Processor_Mode_Privileged,
        X86_Processor_Mode_User,
        X86_Processor_Mode_Current
} x86_processor_mode_t;

Python

import simics

simics.X86_Processor_Mode_Privileged
simics.X86_Processor_Mode_User
simics.X86_Processor_Mode_Current

Name

x86_register_id_t — used to refer to the different registers on x86

Synopsis

C and DML

#include <simics/arch/x86.h> // in C
import "simics/arch/x86.dml"; // in DML

typedef enum {
        X86_Reg_Id_Rax = 0,
        X86_Reg_Id_Rcx = 1,
        X86_Reg_Id_Rdx = 2,
        X86_Reg_Id_Rbx = 3,
        X86_Reg_Id_Rsp = 4,
        X86_Reg_Id_Rbp = 5,
        X86_Reg_Id_Rsi = 6,
        X86_Reg_Id_Rdi = 7,

        X86_Reg_Id_R8  = 8,
        X86_Reg_Id_R9  = 9,
        X86_Reg_Id_R10 = 10,
        X86_Reg_Id_R11 = 11,
        X86_Reg_Id_R12 = 12,
        X86_Reg_Id_R13 = 13,
        X86_Reg_Id_R14 = 14,
        X86_Reg_Id_R15 = 15,

        X86_Reg_Id_Xmm0  = 16,
        X86_Reg_Id_Xmm1  = 17,
        X86_Reg_Id_Xmm2  = 18,
        X86_Reg_Id_Xmm3  = 19,
        X86_Reg_Id_Xmm4  = 20,
        X86_Reg_Id_Xmm5  = 21,
        X86_Reg_Id_Xmm6  = 22,
        X86_Reg_Id_Xmm7  = 23,

        X86_Reg_Id_Xmm8  = 24,
        X86_Reg_Id_Xmm9  = 25,
        X86_Reg_Id_Xmm10 = 26,
        X86_Reg_Id_Xmm11 = 27,
        X86_Reg_Id_Xmm12 = 28,
        X86_Reg_Id_Xmm13 = 29,
        X86_Reg_Id_Xmm14 = 30,
        X86_Reg_Id_Xmm15 = 31,

        X86_Reg_Id_Mm0 = 32,
        X86_Reg_Id_Mm1 = 33,
        X86_Reg_Id_Mm2 = 34,
        X86_Reg_Id_Mm3 = 35,
        X86_Reg_Id_Mm4 = 36,
        X86_Reg_Id_Mm5 = 37,
        X86_Reg_Id_Mm6 = 38,
        X86_Reg_Id_Mm7 = 39,

        X86_Reg_Id_PC  = 40,    /* this is RIP */

        X86_Reg_Id_CF  = 41,    /* integer condition code flags */
        X86_Reg_Id_DST = 42,    /* DST field used to cache PF flag */
        X86_Reg_Id_AF  = 43,
        X86_Reg_Id_ZF  = 44,
        X86_Reg_Id_SF  = 45,
        X86_Reg_Id_OF  = 46,
        X86_Reg_Id_DF  = 47,

        X86_Reg_Id_EFLAGS = 48, /* the whole 32 bits eflags */

        X86_Reg_Id_C0 = 49,     /* floating point cc flags */
        X86_Reg_Id_C1 = 50,
        X86_Reg_Id_C2 = 51,
        X86_Reg_Id_C3 = 52,
        X86_Reg_Id_Top = 53,    /* floating point stack top */
        X86_Reg_Id_Not_Used,    /* dummy number that can be used */

        X86_Reg_Id_Local_Max    /* keep this one last */
} x86_register_id_t;

Python

import simics

simics.X86_Reg_Id_Rsi
simics.X86_Reg_Id_DF
simics.X86_Reg_Id_Rsp
simics.X86_Reg_Id_Xmm12
simics.X86_Reg_Id_OF
simics.X86_Reg_Id_Mm0
simics.X86_Reg_Id_C3
simics.X86_Reg_Id_Xmm14
simics.X86_Reg_Id_R14
simics.X86_Reg_Id_Rdx
simics.X86_Reg_Id_Mm2
simics.X86_Reg_Id_EFLAGS
simics.X86_Reg_Id_Xmm7
simics.X86_Reg_Id_R13
simics.X86_Reg_Id_R9
simics.X86_Reg_Id_Local_Max
simics.X86_Reg_Id_Xmm8
simics.X86_Reg_Id_C2
simics.X86_Reg_Id_C1
simics.X86_Reg_Id_R10
simics.X86_Reg_Id_Xmm10
simics.X86_Reg_Id_Rax
simics.X86_Reg_Id_Mm3
simics.X86_Reg_Id_Xmm3
simics.X86_Reg_Id_Xmm13
simics.X86_Reg_Id_Mm6
simics.X86_Reg_Id_Mm5
simics.X86_Reg_Id_Rbp
simics.X86_Reg_Id_C0
simics.X86_Reg_Id_Xmm15
simics.X86_Reg_Id_ZF
simics.X86_Reg_Id_Xmm6
simics.X86_Reg_Id_Mm7
simics.X86_Reg_Id_DST
simics.X86_Reg_Id_Top
simics.X86_Reg_Id_Xmm5
simics.X86_Reg_Id_Mm1
simics.X86_Reg_Id_Xmm9
simics.X86_Reg_Id_Xmm4
simics.X86_Reg_Id_Rbx
simics.X86_Reg_Id_R15
simics.X86_Reg_Id_AF
simics.X86_Reg_Id_Xmm2
simics.X86_Reg_Id_CF
simics.X86_Reg_Id_Not_Used
simics.X86_Reg_Id_Mm4
simics.X86_Reg_Id_Xmm11
simics.X86_Reg_Id_Rcx
simics.X86_Reg_Id_R11
simics.X86_Reg_Id_R8
simics.X86_Reg_Id_Xmm0
simics.X86_Reg_Id_SF
simics.X86_Reg_Id_PC
simics.X86_Reg_Id_R12
simics.X86_Reg_Id_Xmm1
simics.X86_Reg_Id_Rdi

Description

For x86 the x86_register_id_t can be used to refer to the different registers.

Name

x86_sync_instruction_type_t — type of synchronisation instruction for x86

Synopsis

C and DML

#include <simics/arch/x86.h> // in C
import "simics/arch/x86.dml"; // in DML

typedef enum {
        X86_SFence = 1,
        X86_LFence = 2,
        X86_MFence = 3
} x86_sync_instruction_type_t;

Python

import simics

simics.X86_SFence
simics.X86_LFence
simics.X86_MFence

Description

Type of synchronisation instruction for x86. Used in the Core_Sync_Instruction hap.

Name

xtensa_memory_transaction_t — old memory operation type used with xtensa cores

Synopsis

C and DML

#include <simics/arch/xtensa.h> // in C
import "simics/arch/xtensa.dml"; // in DML

typedef struct xtensa_memory_transaction {
        /* generic transaction */
        generic_transaction_t s;
} xtensa_memory_transaction_t;

Description

The s field contains generic information about memory operations (see generic_transaction_t).

Name

access_filter_cb_t — instrumentation callback type for access filter

Synopsis

C and DML

#include <simics/model-iface/ram-instrumentation.h> // in C
import "simics/model-iface/ram-instrumentation.dml"; // in DML

typedef access_t (*access_filter_cb_t)(conf_object_t *obj,
                                      conf_object_t *ram,
                                      conf_object_t *initiator,
                                      uint64 offset,
                                      unsigned size,
                                      access_t access,
                                      lang_void *user_data);

Description

Instrumentation callback function registered through the register_access_filter_cb method of the ram_access_subscribe interface to get a callback when a direct page is requested which is typically done by CPU models. The obj is the object that registered the callback, and the initiator is the object which tries to get the direct page. The target object of the direct page lookup is passed in the ram argument. Typically, it is an object of the ram class. The offset, size and access are the ram offset, the size of the cached page, and the access type, respectively. The user_data is the user data for the callback. To allow caching of a page, the corresponding bits in an access_t should be returned. If 0 is returned the page will not be cached.

Name

after_read_callback_t — Callback type used with bank_instrumentation_subscribe interface

Synopsis

C and DML

#include <simics/model-iface/bank-instrumentation.h> // in C
import "simics/model-iface/bank-instrumentation.dml"; // in DML

typedef void (*after_read_callback_t)(conf_object_t *connection,
                                      bank_after_read_interface_t *access,
                                      bank_access_t *handle,
                                      lang_void *user_data);

Description

An implementation of this callback type can be registered with the register_after_read method in the bank_instrumentation_subscribe interface.

The connection is the object used to group the callback with any other callbacks, which may be NULL. The access object provides a number of methods via the bank_after_read interface which may be used along with the handle to perform a certain set of actions at the particular point of the access. The user_data is the custom data which was associated with the callback at registration.

Name

after_write_callback_t — Callback type used with bank_instrumentation_subscribe interface

Synopsis

C and DML

#include <simics/model-iface/bank-instrumentation.h> // in C
import "simics/model-iface/bank-instrumentation.dml"; // in DML

typedef void (*after_write_callback_t)(conf_object_t *connection,
                                       bank_after_write_interface_t *access,
                                       bank_access_t *handle,
                                       lang_void *user_data);

Description

An implementation of this callback type can be registered with the register_after_write method in the bank_instrumentation_subscribe interface.

The connection is the object used to group the callback with any other callbacks, which may be NULL. The access object provides a number of methods via the bank_after_write interface which may be used along with the handle to perform a certain set of actions at the particular point of the access. The user_data is the custom data which was associated with the callback at registration.

Name

bank_access_t — callback handle retrieved from the bank_instrumentation_subscribe interface

Synopsis

C and DML

#include <simics/model-iface/bank-instrumentation.h> // in C
import "simics/model-iface/bank-instrumentation.dml"; // in DML

typedef struct bank_access bank_access_t;

Python

import simics

class simics.bank_access_t

Description

Handle used to monitor and modify the state of register accesses using the bank_before_read, bank_after_read, bank_before_write, and bank_after_write interfaces.

Name

bank_callback_handle_t — bank callback handle

Synopsis

C and DML

#include <simics/model-iface/bank-instrumentation.h> // in C
import "simics/model-iface/bank-instrumentation.dml"; // in DML

typedef uintptr_t bank_callback_handle_t;

Description

Unique handle associated with a callback registered through the bank_instrumentation_subscribe interface.

Name

before_read_callback_t — Callback type used with bank_instrumentation_subscribe interface

Synopsis

C and DML

#include <simics/model-iface/bank-instrumentation.h> // in C
import "simics/model-iface/bank-instrumentation.dml"; // in DML

typedef void (*before_read_callback_t)(conf_object_t *connection,
                                       bank_before_read_interface_t *access,
                                       bank_access_t *handle,
                                       lang_void *user_data);

Description

An implementation of this callback type can be registered with the register_before_read method in the bank_instrumentation_subscribe interface.

The connection is the object used to group the callback with any other callbacks, which may be NULL. The access object provides a number of methods via the bank_before_read interface which may be used along with the handle to perform a certain set of actions at the particular point of the access. The user_data is the custom data which was associated with the callback at registration.

Name

before_write_callback_t — Callback type used with bank_instrumentation_subscribe interface

Synopsis

C and DML

#include <simics/model-iface/bank-instrumentation.h> // in C
import "simics/model-iface/bank-instrumentation.dml"; // in DML

typedef void (*before_write_callback_t)(conf_object_t *connection,
                                        bank_before_write_interface_t *access,
                                        bank_access_t *handle,
                                        lang_void *user_data);

Description

An implementation of this callback type can be registered with the register_before_write method in the bank_instrumentation_subscribe interface.

The connection is the object used to group the callback with any other callbacks, which may be NULL. The access object provides a number of methods via the bank_before_write interface which may be used along with the handle to perform a certain set of actions at the particular point of the access. The user_data is the custom data which was associated with the callback at registration.

Name

cpu_access_scope_t — type to describe scope of memory access for instrumentation

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef enum {
        CPU_Access_Scope_Explicit,
        CPU_Access_Scope_Implicit
} cpu_access_scope_t;

Python

import simics

simics.CPU_Access_Scope_Implicit
simics.CPU_Access_Scope_Explicit

Description

Used to select the access scope for instrumentation of memory accesses. CPU_Access_Scope_Explicit selects explicit accesses used by an instruction such as loading or storing a value. CPU_Access_Scope_Implicit selects implicit accesses such as table walks and exceptions handling. See the cpu_instrumentation_subscribe for more information.

Name

cpu_address_cb_t — type of callback function to handle addresses

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef logical_address_t (*cpu_address_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        logical_address_t address,
        address_handle_t *handle,
        lang_void *user_data);

Description

Instrumentation callback function registered through the cpu_instrumentation_subscribe interface’s register_address_before member function.

The callback will be called prior to a processor memory access, allowing the callback to change the logical address for an access.

The argument obj is the object installing the callback and the cpu is the processor generating the logical address. If the access crosses a page boundary the access will be split into two calls. The part argument tells if the address belongs to the first or the second part. The cpu_address_part_t type has two values: CPU_Address_Part_First and CPU_Address_Part_Second. The handle can be used to extract more information about he address by using a architecture specific interface. See the x86_address_query for example.

Name

cpu_bytes_t — type used for bytes in cpu accesses

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef struct cpu_bytes {
        size_t size;
#ifndef PYWRAP
        const uint8 *data;
#endif
} cpu_bytes_t;

Description

An immutable sequence of bytes. The ownership is not transferred to the callee/caller when called or returned. The corresponding Python type is a string of bytes. May only be used in a defined scope which should be documented in each use case.

The member data contains the data pointer, and the member size contains tha size of the data. It is illegal to access beyond the limit.

Name

cpu_cached_instruction_cb_t — type of cached instruction callback function

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_cached_instruction_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        cached_instruction_handle_t *ci_handle,
        instruction_handle_t *iq_handle,
        lang_void *user_data);

Description

Instrumentation callback function registered through the cpu_instrumentation_subscribe interface’s register_cached_instruction_cb member function.

This callback will be called when an instruction is about to be cached in the processor model (this is not the same as being in the processor’s real hardware instruction cache).

cpu is the processor which executed an instruction.

ci_handle is an opaque handle associated with the instruction being executed, it is used with the cpu_cached_instruction interface to install instruction specific callbacks.

iq_handle together with the cpu_instruction_query interface let a user examine instruction properties.

user_data is the user data for the callback.

Name

cpu_callback_free_user_data_cb_t — callback type used for freeing user data

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_callback_free_user_data_cb_t)(
        conf_object_t *obj, conf_object_t *cpu, lang_void *user_data);

Description

Callback function registered through the cpu_cached_instruction interface to free instruction specific user data when the instruction is not being cached anymore. The user_data is the pointer to the callback data. obj is the connection object and cpu is the processor that the callback was registered for.

Name

cpu_control_register_read_cb_t — type of callback function for control register read

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_control_register_read_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        int register_number,
        lang_void *user_data);

Description

The obj is the object registering the callback and cpu is the processor that reads the control register register_number. The user_data is the user data for the callback.

Name

cpu_control_register_scope_t — type used to describe control register scope

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef enum {
        CPU_Control_Register_All = -1
        /* Any other value corresponds to the register number as
           defined in the int_register interface for the processor */
} cpu_control_register_scope_t;

Python

import simics

simics.CPU_Control_Register_All

Name

cpu_control_register_write_cb_t — type of callback function for control register write

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_control_register_write_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        int register_number,
        uint64 value,
        lang_void *user_data);

Description

The obj is the object registering the callback and cpu is the processor that writes to the control register register_number. The value is the value that will be written. The user_data is the user data for the callback.

Name

cpu_emulation_cb_t — type of instruction decode callback function

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef cpu_emulation_t (*cpu_emulation_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        lang_void *user_data);

Description

Instrumentation callback function registered through the cpu_instruction_decoder interface.

This callback will be called when an user added instruction is about to be executed in the processor. The cpu is the processor which executes an instruction. The instruction_user_data is the user-data associated with the instruction. The return type cpu_emulation_t is used to tell Simics how the next instruction should be fetched. For more information, see the cpu_instruction_decoder interface.

Name

cpu_emulation_t — type of instruction decode callback function

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef enum {
        CPU_Emulation_Fall_Through,
        CPU_Emulation_Control_Flow,
        CPU_Emulation_Default_Semantics,
        CPU_Emulation_Stall,
} cpu_emulation_t;

Python

import simics

simics.CPU_Emulation_Fall_Through
simics.CPU_Emulation_Default_Semantics
simics.CPU_Emulation_Control_Flow
simics.CPU_Emulation_Stall

Name

cpu_exception_cb_t — type of callback function for exception

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_exception_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        exception_handle_t *exception_handle,
        lang_void *user_data);

Description

The obj is the object registering the callback and cpu is the processor that takes the exception or receives the interrupt. The handle is used to get more architectural information about the exception, for example, see the x86_exception_query for details. The user_data is the callback user data.

No architectural state has been changed in this callback to reflect the exception or interrupt, e.g., the program counter will still be at the faulting instruction. Since an exception can occur while handling an exception it is not always the case that this callback corresponds to the final taken exception. Recursive exception will result in another call to this callback.

Name

cpu_exception_return_cb_t — type of callback function for exception return

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_exception_return_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        exception_return_handle_t *exception_handle,
        lang_void *user_data);

Description

The obj is the object registering the callback and cpu is the processor that takes the exception or receives an interrupt. The handle is used to get more architectural information about the exception. Currently there is no interface available for this.

Name

cpu_exception_scope_t — type used to describe exception scope

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef enum {
        CPU_Exception_All = -1
        /* Any other value corresponds to the exception number as
           defined in the exception interface for the processor */
} cpu_exception_scope_t;

Python

import simics

simics.CPU_Exception_All

Name

cpu_instruction_cb_t — callback type used for instruction execution

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_instruction_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        instruction_handle_t *handle,
        lang_void *user_data);

Description

Instrumentation callback function registered through the cpu_instrumentation_subscribe or the cpu_cached_instruction interfaces to get a callback before or after an instruction has been executed.

obj is the connection or the user object that registered the callback (or NULL if there is no object).

cpu is the processor which executed the instruction.

handle is an opaque handle associated with the instruction being executed. It can be used together with the cpu_instruction_query interface to get more information about the instruction.

user_data is the user data for the callback.

Name

cpu_instruction_decoder_cb_t — type of instruction decode callback function

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef int (*cpu_instruction_decoder_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        decoder_handle_t *decoder_handle,
        instruction_handle_t *iq_handle,
        lang_void *user_data);

Description

Instrumentation callback function registered through the cpu_instrumentation_subscribe interface’s register_instruction_decoder_cb member function.

This callback will be called when an instruction is about to be cached in the processor model (this is not the same as being in the processor’s real hardware instruction cache). The cpu is the processor which executed an instruction. The decoder_handle is an opaque handle associated with the instruction being executed and used in the cpu_instruction_decoder interface. The iq_handle is used with the cpu_instruction_query interface to get more information on the instruction. The user_data is the user data associated with the callback.

If the instruction is accepted by the callback a positive integer number should be returned corresponding to the length of the instruction. In this case the register_emulation_cb method of the cpu_instruction_decoder interface should be called to set the actual (user) function that Simics will call each time the instruction is executed.

If the decoder requires more bytes (i.e., because the new instruction is longer), a negative integer value should be returned by the cb function, indicating the number of bytes needed. For example, if the available bytes are 3 but the decoder need at least 4 bytes, -4 should be returned. The callback will then be called again with more available bytes (this can be repeated if the new instruction requires even more bytes at this point). Note that requesting more data than actual needed can cause spurious page faults if the data crosses a page boundary.

If the cb callback should ignore the instruction the number 0 should be returned. This means that any other registered decoder will have a chance to decode the instruction. If no decoder accepts it, Simics’ default implementation will be used.

Name

cpu_instruction_disassemble_cb_t — type of disassemble callback function

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef tuple_int_string_t (*cpu_instruction_disassemble_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        generic_address_t addr,
        cpu_bytes_t bytes);

Description

Instrumentation callback function registered through the cpu_instrumentation_subscribe interface’s register_instruction_decoder_cb member function.

The callback will be called when a replaced instruction is being disassembled.

obj is the object registering the callback and cpu is the processor disassembling the instruction. addr is the address of the instruction in a generic form. This means that it is typically a physical address or a logical address depending on the context of the disassembling. The address can be used for offset calculations, i.e., displaying an absolute address instead of a relative one, for example in a branch instruction. The bytes argument should be used to read instruction bytes.

The return value is of type tuple_int_string_t and should be filled with the instruction length and an allocated (e.g., malloc) string representing the disassembly of the instruction. The ownership of the string is transferred to the calling environment which will free it when it is no longer needed.

If too few bytes are passed for the instruction to be disassembled a negative value should be returned for the length indicating the needed bytes. The disass_cb is then called again with more bytes. If the instruction is rejected a length of 0 should be returned and the string should be set to NULL.

Name

cpu_memory_cb_t — callback type used for memory access

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_memory_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        memory_handle_t *handle,
        lang_void *user_data);

Description

Instrumentation callback function registered through the cpu_instrumentation_subscribe or the cpu_cached_instruction interfaces to get a callback before or after an memory access is executed.

obj is the object that registered the callback

cpu is the processor doing the access.

handle is an opaque handle associated with the instruction being executed. It can be used with the cpu_memory_query interface to get more information about the access.

user_data is the userdata for the callback.

Name

cpu_mode_change_cb_t — type of callback function for mode change

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef void (*cpu_mode_change_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        processor_mode_t old_mode, processor_mode_t new_mode,
        lang_void *user_data);

Description

The obj is the object registering the callback and cpu is the processor that changes mode. The old_mode is the mode before the change and new_mode is the mode after the change.

Name

do_map_target_cb_t — callback type for map target instrumentation

Synopsis

C and DML

#include <simics/model-iface/transaction-instrumentation.h> // in C
import "simics/model-iface/transaction-instrumentation.dml"; // in DML

typedef next_map_t (*do_map_target_cb_t)(const map_target_t *mt,
                                         transaction_t *org_t,
                                         uint64 addr, map_info_t *map,
                                         lang_void *handle);

Name

next_map_t — type used for chaining map_target_t’s

Synopsis

C and DML

#include <simics/model-iface/transaction-instrumentation.h> // in C
import "simics/model-iface/transaction-instrumentation.dml"; // in DML

typedef struct {
        const map_target_t *mt;
#ifndef PYWRAP
        exception_type_t ex;
#else
        unsigned ex;
#endif
        uint64 addr;
} next_map_t;

Python

import simics

class simics.next_map_t(mt=None, ex=0, addr=0)

Description

This type is used to hold information about the next map target in a translation chain. It is exposed in the do_map_target_cb_t function callback used in the transaction_issue_cb_t callback in the transaction_subscribe interface. See transaction_issue_cb_t for more information.

Name

pre_decoder_cb_t — callback function type used with pre_decoder interface

Synopsis

C and DML

#include <simics/model-iface/cpu-instrumentation.h> // in C
import "simics/model-iface/cpu-instrumentation.dml"; // in DML

typedef bool (*pre_decoder_cb_t)(
        conf_object_t *obj,
        conf_object_t *cpu,
        generic_address_t instruction_start_address,
        physical_address_t position_physical_address,
        uint8 *opcode_bytes,
        unsigned valid_bytes,
        unsigned instruction_position,
        lang_void *user_data);

Description

This callback is used by the pre_decoder interface to observe and modify the instruction byte stream.

The obj is the connection object which owns the callback, or NULL, if no connection is used. cpu is the cpu which decodes the instructions. instruction_start_address is the address of the first byte in the instruction that is being decoded. For x86 this is the linerar address. opcode_bytes is a pointer to the first opcode byte in the instruction. The valid_bytes tells how many bytes that can read from the first byte.

If the decoded instruction crosses a page boundary this callback is invoked twice, first with the bytes on the first page and then with additional bytes located on the next page. The instruction_position tells where in the instruction opcode the next bytes are added from the second page, and hence will be greater 0 if this occurs.

The position_physical_address reflects the physical address of the instruction_position.

The function should return true if the memory was modified, otherwise false.

Name

ram_access_cb_t — instrumentation callback type for ram access

Synopsis

C and DML

#include <simics/model-iface/ram-instrumentation.h> // in C
import "simics/model-iface/ram-instrumentation.dml"; // in DML

typedef void (*ram_access_cb_t)(conf_object_t *obj,
                                conf_object_t *ram,
                                uint64 ram_offset,
                                transaction_t *t,
                                lang_void *user_data);

Description

Instrumentation callback function registered through the register_access_before_cb or register_access_after_cb methods in the ram_access_subscribe interface to get a callback when a ram/rom object is accessed. obj is the object that registered the callback, and the ram is the ram/rom object that is accessed. The ram_offset is the offset in the ram/rom object where the transaction hits. The t argument is a pointer to the transaction_t that is performed. See the access primitives of the transaction_t type to see how to examine and modify the transaction. Depending on if the register function is of before or after type, the transaction will be, or already has been completed, at the time of this callback. This places restrictions on what can be done with the transaction.

Name

smm_switch_cb_t — callback type for smm switch

Synopsis

C and DML

#include <simics/arch/x86-instrumentation.h> // in C
import "simics/arch/x86-instrumentation.dml"; // in DML

typedef void (*smm_switch_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        lang_void *user_data);

Description

This callback type is used by the smm_instrumentation_subscribe to implement instrumentation.

The obj argument is the user object that registered the callback, or NULL if no such object exists.

The cpu argument is the processor that enters/leaves System Management Mode.

The user_data argument is the callback user data, passed to the register methods.

Name

transaction_issue_cb_t — callback type for transaction instrumentation

Synopsis

C and DML

#include <simics/model-iface/transaction-instrumentation.h> // in C
import "simics/model-iface/transaction-instrumentation.dml"; // in DML

typedef next_map_t (*transaction_issue_cb_t)(conf_object_t *obj,
                                             const map_target_t *mt,
                                             const char *map_target_type,
                                             map_info_t *map,
                                             transaction_t *t,
                                             uint64 offset,
                                             do_map_target_cb_t do_mt,
                                             lang_void *handle,
                                             lang_void *user_data);

Description

Note: This callback is internal and may change without notice.

Instrumentation callback function registered through the register_issue_cb method in the transaction_subscribe interface. In this callback a user can snoop and/or replace a transaction passing through a map target object.

Argument obj is the object that registered the callback. The mt argument is the map target used to map the transaction, and the map_target_type is a string describing the map target. The map parameter is map information for the map target. addr is the address in the mapped object where the transaction hits. You can retrieve the object by calling SIM_map_target_object on the map_target. The t argument is a pointer to the transaction that is issued. See the access primitives of the transaction_t type to see how to examine and modify the transaction. The do_mt is the function to call that actually do the map target access, and it is the callback’s responsibility to call it. This allows the map target, the map, the address, and the transaction to be modified by then callback. Se the documentation of the do_map_target_cb_t for a description of how to call it.

The callback should return a next_map_t value that is the return value of the do_mt callback. This describes the next map target to be considered, if the map target translates to a new map target. In this case, the next target is stored in the mt field. If no new map target is used, the field will be NULL. The type also contains an ex field set to something else than Sim_PE_No_Exception, if an exception occurred. It also has a addr field which describes the new address for the next map target.

If the do_mt function is not called, this effectively cancels the transaction. The value map_next_t to return should then fill in the mt field with a NULL pointer.

Name

vmx_mode_switch_cb_t — callback type for vmx mode switch

Synopsis

C and DML

#include <simics/arch/x86-instrumentation.h> // in C
import "simics/arch/x86-instrumentation.dml"; // in DML

typedef void (*vmx_mode_switch_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        vmx_mode_t mode,
        physical_address_t vmcs_address,
        lang_void *user_data);

Description

This callback type is used by the vmx_instrumentation_subscribe interface to implements VMX mode switch instrumentation.

The obj argument is the user object that registered the callback, or NULL if no such object exists.

The cpu argument is the processor that switches VMX mode.

The mode that will be left or entered is passed in the mode argument in the callback.

Name

vmx_mode_t — enum for vmx modes

Synopsis

C and DML

#include <simics/arch/x86-instrumentation.h> // in C
import "simics/arch/x86-instrumentation.dml"; // in DML

typedef enum {
        Vmx_Off = 0,
        Vmx_Root = 1,
        Vmx_Non_Root = 2
} vmx_mode_t;

Python

import simics

simics.Vmx_Root
simics.Vmx_Off
simics.Vmx_Non_Root

Description

This enum is used to distinguish VMX modes. It is used by the vmx_mode_switch_cb_t.

Name

x86_mode_switch_cb_t — x86 specific callback type for mode switch instrumentation

Synopsis

C and DML

#include <simics/arch/x86-instrumentation.h> // in C
import "simics/arch/x86-instrumentation.dml"; // in DML

typedef void (*x86_mode_switch_cb_t)(
        conf_object_t *obj, conf_object_t *cpu,
        x86_detailed_exec_mode_t mode,
        lang_void *user_data);

Description

The obj is the connection object that registered the callback. new_mode argument contains the new mode. The possible modes available are captured in the x86_detailed_exec_mode_t type.

The user_data is the user data associated with the callback.

Name

byte_string_t, struct ether_addr, event_queue_type_t, icode_mode_t, image_spage_t, intervals_func_t, interval_set_t, interval_set_iter_t, os_time_t, struct os_tm, page_info_t, prof_data_t, prof_data_address_t, prof_data_counter_t, prof_data_iter_t, rand_state_t, range_node_t, sim_ic_type_t, simics_internal_counters_t, socket_t, state_save_kind_t, strbuf_t, struct simcontext, vtmem_inform_opcode_t, addr_type_t — internal data types

Description

These data types are exported for Simics internal use.

Name

block_flag_t — flags for blocking various internal caches

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

typedef enum {
        Sim_Block_Memhier = 1,               /* want memhier or timing model
                                                to see future accesses */
        Sim_Block_MMU = 2,                   /* want future MMU visibility */
        Sim_Block_MMU_IOSTC = 4,             /* want future MMU visibility
                                                for accesses that skip the
                                                IOSTC lookup */
        Sim_Block_Breakpoint = 8,            /* need breakpoint check */
        Sim_Block_Notmem = 16,               /* is not memory */
        Sim_Block_Endian = 32,               /* memory is byteswapped */
        Sim_Block_DSTC_Disabled = 64         /* DSTC is disabled for this
                                                access */
} block_flag_t;

Python

import simics

simics.Sim_Block_MMU_IOSTC
simics.Sim_Block_DSTC_Disabled
simics.Sim_Block_Breakpoint
simics.Sim_Block_Endian
simics.Sim_Block_Notmem
simics.Sim_Block_MMU
simics.Sim_Block_Memhier

Description

This enum are flags for blocking various internal caches (internal).

Name

SIM_alloc_attr_dict — create empty attribute dictionary

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

attr_value_t
SIM_alloc_attr_dict(unsigned length);

Description

Returns an attr_value_t of type dict with size len. The dictionary elements are initialized to invalid values.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_attr_dict_set_item, SIM_alloc_attr_list

Name

SIM_alloc_attr_list — create uninitialized attribute list

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

attr_value_t
SIM_alloc_attr_list(unsigned length);

Description

Returns an attr_value_t of type list with size length. The list elements are initialized to invalid values.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_make_attr_list, SIM_attr_list_set_item

Name

SIM_attr_copy — copy attribute value

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

attr_value_t
SIM_attr_copy(attr_value_t val);

Description

Return a deep copy of val. The caller obtains ownership of the copy and needs to free it after use; the argument is not modified.

This function is not available from Python.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_attr_free

Name

SIM_attr_dict_resize — resize dict attribute value

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_attr_dict_resize(attr_value_t *NOTNULL attr, unsigned newsize);

Description

Resize attr, which must be of dict type, to newsize elements. New elements are marked invalid. Dropped elements are freed.

Execution Context

Cell Context

Name

SIM_attr_dict_set_item — set dict attribute element

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_attr_dict_set_item(attr_value_t *NOTNULL attr, unsigned index,
                       attr_value_t key, attr_value_t value);

Description

Set the element numbered index of the dict attr to key and value. The previous key and value at that position are freed. The ownership for key and value is transferred from the caller to attr. The key must be of integer, string or object type.

Execution Context

Cell Context

Name

SIM_attr_free, SIM_free_attribute — free attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_attr_free(attr_value_t *NOTNULL value);

void
SIM_free_attribute(attr_value_t value);

Description

Free the memory allocation used by the value pointed to by value. For values of list or dict type, this recursively frees all contents; for string or data values, the allocation containing the payload is freed. It is an error to use the value or any sub-part of it after it has been freed.

SIM_attr_free is the preferred call because it changes the type of the argument variable to Invalid, preventing accidental use after freeing. SIM_free_attribute only differs in how the argument is passed, but cannot change the argument variable as it is passed by value.

These functions are not available in Python; memory allocation is managed automatically there.

Execution Context

All contexts (including Threaded Context)

Name

SIM_attr_integer, SIM_attr_boolean, SIM_attr_string, SIM_attr_string_detach, SIM_attr_floating, SIM_attr_object, SIM_attr_object_or_nil, SIM_attr_data_size, SIM_attr_data, SIM_attr_list_size, SIM_attr_list_item, SIM_attr_list, SIM_attr_dict_size, SIM_attr_dict_key, SIM_attr_dict_value — extract values stored in attr_value_t values

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE int64
SIM_attr_integer(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_boolean(attr_value_t attr);

FORCE_INLINE const char *
SIM_attr_string(attr_value_t attr);

FORCE_INLINE char *
SIM_attr_string_detach(attr_value_t *attr);

FORCE_INLINE double
SIM_attr_floating(attr_value_t attr);

FORCE_INLINE conf_object_t *
SIM_attr_object(attr_value_t attr);

FORCE_INLINE conf_object_t *
SIM_attr_object_or_nil(attr_value_t attr);

FORCE_INLINE unsigned
SIM_attr_data_size(attr_value_t attr);

FORCE_INLINE const uint8 *
SIM_attr_data(attr_value_t attr);

FORCE_INLINE unsigned
SIM_attr_list_size(attr_value_t attr);

FORCE_INLINE attr_value_t
SIM_attr_list_item(attr_value_t attr, unsigned index);

FORCE_INLINE attr_value_t *
SIM_attr_list(attr_value_t attr);

FORCE_INLINE unsigned
SIM_attr_dict_size(attr_value_t attr);

FORCE_INLINE attr_value_t
SIM_attr_dict_key(attr_value_t attr, unsigned index);

FORCE_INLINE attr_value_t
SIM_attr_dict_value(attr_value_t attr, unsigned index);

Description

Extract a value encapsulated in attr. It is an error to call an accessor function with an attr of the wrong type.

SIM_attr_integer returns the integer attribute value modulo-reduced to the interval [-2**63,2**(63-1)]. (Converting the return value to uint64 gives the integer attribute value modulo-reduced to [0,2**(64-1)].)

SIM_attr_string, SIM_attr_data and SIM_attr_list return values owned by attr. Ownership is not transferred to the caller.

SIM_attr_string_detach returns the string in attr and changes the value pointed to by attr into a nil attribute. Ownership of the string is transferred to the caller.

SIM_attr_object_or_nil accepts an attr parameter of either object or nil type. In case of a nil attribute, the function returns NULL.

SIM_attr_list_size and SIM_attr_dict_size return the number of items in the list and key-value pairs in the dict respectively. SIM_attr_data_size returns the number of bytes in the data value.

SIM_attr_list_item returns the item at index. The index must be less than the number of items in the list. The item returned is still owned by attr. Ownership is not transferred to the caller.

SIM_attr_list returns a pointer directly into the internal array of the attribute value; it is mainly present as an optimisation. Use SIM_attr_list_item and SIM_attr_list_set_item for type-safety instead.

SIM_attr_dict_key and SIM_attr_dict_value return the key and value at index. The index must be less than the number of items in the dict. The value returned is still owned by attr. Ownership is not transferred to the caller.

Execution Context

All contexts (including Threaded Context)

Name

SIM_attr_is_nil, SIM_attr_is_int64, SIM_attr_is_uint64, SIM_attr_is_integer, SIM_attr_is_boolean, SIM_attr_is_string, SIM_attr_is_floating, SIM_attr_is_object, SIM_attr_is_invalid, SIM_attr_is_data, SIM_attr_is_list, SIM_attr_is_dict — attr_value_t type predicates

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_attr_is_nil(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_int64(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_uint64(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_integer(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_boolean(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_string(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_floating(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_object(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_invalid(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_data(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_list(attr_value_t attr);

FORCE_INLINE bool
SIM_attr_is_dict(attr_value_t attr);

Description

Indicates whether the value stored in attr is of the specified type. SIM_attr_is_int64 and SIM_attr_is_uint64 additionally test whether the integer value would fit in the given C type.

Execution Context

Cell Context

Name

SIM_attr_list_resize — resize list attribute value

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_attr_list_resize(attr_value_t *NOTNULL attr, unsigned newsize);

Description

Resize attr, which must be of list type, to newsize elements. New elements are set to invalid value. Dropped elements are freed.

Execution Context

Cell Context

Name

SIM_attr_list_set_item — set list attribute element

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_attr_list_set_item(attr_value_t *NOTNULL attr, unsigned index,
                       attr_value_t elem);

Description

Set the element numbered index of the list attr to elem. The previous value at that position is freed. The ownership for elem is transferred from the caller to attr.

Execution Context

Cell Context

Name

SIM_attr_scanf, SIM_ascanf — parse list attribute values

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_attr_scanf(attr_value_t *NOTNULL list, const char *NOTNULL fmt, ...);

bool
SIM_ascanf(attr_value_t *NOTNULL list,
           const char *NOTNULL fmt, ...) __attribute__((alias("SIM_attr_scanf")));

Description

Reads and converts entries in list according to the format string fmt. Returns true if all elements were successfully converted, false otherwise.

The characters in the format string mean:

The fmt string may also include a period (.) at the end, taken to mean that more elements may follow. If the period is not present, the length of the list must equal the number of specified elements.

Converted values of type attr_value_t * and const char * are still owned by list.

SIM_ascanf is an alias of SIM_attr_scanf and will be deprecated.

Execution Context

All contexts (including Threaded Context)

Name

SIM_make_attr_boolean — make boolean attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE attr_value_t
SIM_make_attr_boolean(bool b);

Description

Returns an attr_value_t of boolean type.

Execution Context

Cell Context

Name

SIM_make_attr_data, SIM_make_attr_data_adopt — create raw data attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

attr_value_t
SIM_make_attr_data(size_t size, const void *data);

FORCE_INLINE attr_value_t
SIM_make_attr_data_adopt(size_t size, void *data);

Description

Returns an attr_value_t of type data using size and data for the binary data. The maximum size of the binary data is 2**32-1 bytes, i.e. size should fit into a 32-bit unsigned integer.

SIM_make_attr_data will make a copy of the argument data.

SIM_make_attr_data_adopt is mainly provided for compatibility; it will assume ownership of the argument data, which must have been allocated using one of the MM_MALLOC functions.

Execution Context

All contexts (including Threaded Context)

Name

SIM_make_attr_floating — make floating point attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE attr_value_t
SIM_make_attr_floating(double d);

Description

Returns an attr_value_t of floating type with value d.

Execution Context

Cell Context

Name

SIM_make_attr_uint64, SIM_make_attr_int64 — make integer attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE attr_value_t
SIM_make_attr_uint64(uint64 i);

FORCE_INLINE attr_value_t
SIM_make_attr_int64(int64 i);

Description

Returns an attr_value_t of integer type with value i.

Execution Context

Cell Context

Name

SIM_make_attr_invalid — make invalid attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE attr_value_t
SIM_make_attr_invalid(void);

Description

Returns an attr_value_t of invalid type.

Execution Context

Cell Context

Name

SIM_make_attr_list, SIM_make_attr_list_vararg — make list attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

attr_value_t
SIM_make_attr_list(unsigned length, ...);

// not available in DML

attr_value_t
SIM_make_attr_list_vararg(unsigned length, va_list va);

Description

Returns an attr_value_t of type list with size length. The list is filled with data from the arguments following, which should be of type attr_value_t.

This function must be called with exactly length+1 arguments. The attribute parameters should all be valid attributes; e.g., attributes of invalid type are not allowed. The length argument must be a constant expression.

The newly created list assumes ownership of the passed parameters, which therefore should not be freed.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_alloc_attr_list

Name

SIM_make_attr_nil — make nil attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE attr_value_t
SIM_make_attr_nil(void);

Description

Returns an attr_value_t of type nil.

Execution Context

Cell Context

Name

SIM_make_attr_object — make object attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE attr_value_t
SIM_make_attr_object(conf_object_t *obj);

Description

Returns an attr_value_t of object type with value obj. Returns a nil value if obj is NULL.

Execution Context

Cell Context

Name

SIM_make_attr_string, SIM_make_attr_string_adopt — make string attribute

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

attr_value_t
SIM_make_attr_string(const char *str);

FORCE_INLINE attr_value_t
SIM_make_attr_string_adopt(char *str);

Description

Returns an attr_value_t of type string with value str. Returns Nil if str is NULL.

SIM_make_attr_string will make a copy of the argument string.

SIM_make_attr_string_adopt is mainly provided for compatibility; it will assume ownership of the argument string, which must have been allocated using one the MM_MALLOC functions.

Execution Context

All contexts (including Threaded Context)

Name

SIM_attribute_error, SIM_c_attribute_error — specify reason for attribute error

Synopsis

C and DML

#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, ...);

Python

import simics

simics.SIM_attribute_error(...)

Description

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.

Execution Context

Cell Context

See Also

SIM_register_attribute, SIM_get_attribute, SIM_set_attribute

Name

SIM_class_port — check if class has specified port object

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_class_port(...)

Description

Returns the class of objects on the port named name, or nullptr if no such port is registered.

See Also

SIM_register_port, SIM_register_simple_port

Execution Context

Cell Context

Name

SIM_copy_class — create a copy of an existing class

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_copy_class(...)

Description

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.

Return Value

The newly created class is returned.

See Also

SIM_extend_class, SIM_create_class

Execution Context

Global Context

Name

SIM_create_class — create class

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_create_class(...)

Description

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.

Return Value

Class structure, or NULL on error.

Execution Context

Global Context

See Also

SIM_register_class_alias, class_info_t

Name

SIM_ensure_partial_attr_order — ensure attribute order

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_ensure_partial_attr_order(...)

Description

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.

Execution Context

Cell Context

See Also

SIM_register_attribute

Name

SIM_extend_class — extend class with contents from an extension class

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_extend_class(...)

Description

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.

See Also

SIM_create_class, SIM_register_class, SIM_extension_data

Execution Context

Global Context

Name

SIM_extension_data — get class extension data

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void *
SIM_extension_data(conf_object_t *obj, conf_class_t *ext_cls);

Python

import simics

simics.SIM_extension_data(...)

Description

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.

See Also

SIM_object_data, SIM_register_class, SIM_extend_class

Execution Context

Cell Context

Name

SIM_get_class, conf_class_t — get class

Synopsis

C and DML

#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;

Python

import simics

simics.SIM_get_class(...)
class simics.conf_class_t

Description

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.

Return Value

Opaque pointer referencing the class, or nullptr if not found.

Exceptions

SimExc_General Thrown if the class has not been registered.

Execution Context

Cell Context, except when loading a module.

See Also

SIM_get_class_name

Name

SIM_get_class_data — get class data

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

lang_void *
SIM_get_class_data(conf_class_t *cls);

Python

import simics

simics.SIM_get_class_data(...)

Description

Obtain the class data that was set using SIM_set_class_data. This can be called at any time during the object initialisation process.

See Also

SIM_set_class_data

Execution Context

Cell Context

Name

SIM_get_class_name — get class name

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_get_class_name(const conf_class_t *NOTNULL class_data);

Python

import simics

simics.SIM_get_class_name(...)

Description

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

Execution Context

Cell Context

See Also

SIM_get_class

Name

SIM_get_interface — get interface

Synopsis

C and DML

#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);

Python

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(...)

Description

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
    ...

Return Value

Pointer to interface, or nullptr if not found.

Exceptions

SimExc_Lookup Thrown if the interface is not implemented by obj’s class.

SimExc_General Thrown if the interface name is illegal.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_register_interface

Name

SIM_is_restoring_state — check if state restoring phase

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_is_restoring_state(conf_object_t *obj);

Python

import simics

simics.SIM_is_restoring_state(...)

Description

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.

LIMITATION: This function currently returns true for all objects in Simics while some state is being restored and not only for the affected objects.

See Also

SIM_object_is_configured

Execution Context

Cell Context

Name

SIM_marked_for_deletion — is object being deleted

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_marked_for_deletion(const conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_marked_for_deletion(...)

Description

Indicates if the given object is being deleted. This information can be useful by other objects that want to clean up their references.

Return Value

true if the object is being deleted.

Execution Context

Global Context

See Also

SIM_delete_objects

Name

SIM_object_clock — get object clock

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

conf_object_t *
SIM_object_clock(const conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_object_clock(...)

Description

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.

Execution Context

All contexts (including Threaded Context)

Name

SIM_object_data — get object-specific data pointer

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

lang_void *
SIM_object_data(conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_object_data(...)

Description

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.

See Also

SIM_create_class, SIM_register_class

Execution Context

All contexts (including Threaded Context)

Name

SIM_object_id — get object identifier

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_object_id(const conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_object_id(...)

Description

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.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_object_name

Name

SIM_object_is_configured, SIM_set_object_configured — get/set configured status

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_object_is_configured(...)
simics.SIM_set_object_configured(...)

Description

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.

Execution Context

• SIM_object_is_configured: all contexts (including Threaded Context);
• SIM_set_object_configured: Global Context

See Also

SIM_require_object, SIM_register_class, SIM_is_restoring_state

Name

SIM_object_name — get object name

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_object_name(const conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_object_name(...)

Description

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

Execution Context

All contexts (including Threaded Context)

See Also

SIM_object_id

Name

SIM_picosecond_clock — get object picosecond clock

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

conf_object_t *
SIM_picosecond_clock(conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_picosecond_clock(...)

Description

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_time is 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).

See Also

SIM_object_clock

Execution Context

All contexts (including Threaded Context)

Name

SIM_register_attribute, SIM_register_class_attribute, SIM_register_attribute_with_user_data, SIM_register_class_attribute_with_user_data — register attribute

Synopsis

C and DML

#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);

Python

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(...)

Description

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.

Execution Context

Global Context

Name

SIM_register_class — register class

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_class(...)

Description

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.

Return Value

Class structure, or nullptr on error.

Execution Context

Global Context

See Also

SIM_create_class, SIM_register_class_alias, class_data_t

Name

SIM_register_class_alias — register class alias

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_register_class_alias(const char *NOTNULL alias, const char *NOTNULL name);

Python

import simics

simics.SIM_register_class_alias(...)

Description

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.

See Also

SIM_create_class, SIM_register_class

Execution Context

Global Context

Name

SIM_register_clock — register mandatory interface and attributes for clock objects

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_clock(...)

Description

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().

Return Value

Returns non-zero on failure, 0 otherwise.

Exceptions

SimExc_General Thrown if the cycle interface has already been registered for this class.

Execution Context

Global Context

See Also

SIM_register_interface, SIM_register_attribute

Name

SIM_register_compatible_interfaces — register earlier versions of interface

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_compatible_interfaces(...)

Description

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).

Exceptions

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.

Execution Context

Global Context

Name

SIM_register_interface — register interface

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_interface(...)
simics.SIM_register_port_interface(...)

Description

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.

Return Value

Returns non-zero on failure, 0 otherwise.

Exceptions

SimExc_General Thrown if the interface name is illegal, or if this interface has already been registered for this class.

Execution Context

Global Context

See Also

SIM_get_interface

Name

SIM_register_port — register port class

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_port(...)

Description

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.

See Also

SIM_register_simple_port

Execution Context

Global Context

Name

SIM_register_simple_port — register port

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_simple_port(...)

Description

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.

Return Value

The port class is returned.

See Also

SIM_register_port

Execution Context

Global Context

Name

SIM_register_sub_object — register sub-object

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_sub_object(...)

Description

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.

See Also

SIM_register_port, sub_object_flags_t

Execution Context

Global Context

Name

SIM_register_typed_attribute, SIM_register_typed_class_attribute — register attribute

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_register_typed_attribute(...)
simics.SIM_register_typed_class_attribute(...)

Description

The functions SIM_register_typed_attribute and SIM_register_typed_class_attribute are legacy. New code should use SIM_register_attribute or SIM_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.

Return Value

Returns zero if successful, and non-zero otherwise.

Exceptions

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.

Execution Context

Global Context

Name

SIM_require_object — make sure an object is fully configured

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_require_object(conf_object_t *NOTNULL obj);

Python

import simics

simics.SIM_require_object(...)

Description

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.

Execution Context

Global Context

See Also

SIM_object_is_configured, SIM_create_class, SIM_is_restoring_state

Name

SIM_set_attribute_default — set default value for an attribute in a child object

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_set_attribute_default(...)

Description

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.

Return Value

Returns Sim_Set_Ok if successful.

Execution Context

Global Context

See Also

SIM_register_port, SIM_register_class

Name

SIM_set_class_data — set class data

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_set_class_data(conf_class_t *cls, lang_void *data);

Python

import simics

simics.SIM_set_class_data(...)

Description

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.

See Also

SIM_get_class_data

Execution Context

Global Context

Name

SIM_set_thread_name, SIM_get_thread_name — set/get the name of a thread

Synopsis

C and DML

#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);

Python

import simics

simics.SIM_set_thread_name(...)
simics.SIM_get_thread_name(...)

Description

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.

Return Value

On success, SIM_get_thread_name returns a null-terminated string. On error, NULL is returned.

Execution Context

Any context

Name

SIM_cbdata_data — get cbdata data pointer

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void *
SIM_cbdata_data(const cbdata_t *cbd);

Description

Return the data pointer of the callback data cbd.

See Also

cbdata_t

Name

SIM_cbdata_type — get cbdata type pointer

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE const cbdata_type_t *
SIM_cbdata_type(const cbdata_t *cbd);

Description

Return a pointer to the type information of the callback data cbd.

See Also

cbdata_t

Name

SIM_free_cbdata — free cbdata

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_free_cbdata(cbdata_t *cbd);

Description

Free the callback data cbd by calling its dealloc function.

See Also

cbdata_t

Name

SIM_make_cbdata — create cbdata

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE cbdata_t
SIM_make_cbdata(const cbdata_type_t *type, void *data);

Description

Create new callback data of type type and value data.

See Also

cbdata_t

Name

SIM_make_simple_cbdata — create untyped cbdata

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE cbdata_t
SIM_make_simple_cbdata(void *obj);

Description

Create new untyped callback data of value data. An untyped callback data has no dealloc function.

See Also

cbdata_t

Name

SIM_clear_exception — clear pending exception

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

sim_exception_t
SIM_clear_exception();

Description

Clears the currently pending frontend exception and returns the value of it.

Return Value

Returns the exception that was pending before the call, or SimExc_No_Exception.

Execution Context

Cell Context

See Also

SIM_get_pending_exception, SIM_last_error

Name

SIM_describe_pseudo_exception — return pseudo exception description

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_describe_pseudo_exception(exception_type_t ex);

Python

import simics

simics.SIM_describe_pseudo_exception(...)

Description

This function returns a descriptive string for the specified exception_type_t.

Return Value

Exception description, or an error message if input is not a known pseudo-exception.

Execution Context

Global Context

See Also

exception_type_t

Name

SIM_get_pending_exception — get current pending exception

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

sim_exception_t
SIM_get_pending_exception();

Description

This function returns the exception type of the current pending exception, or SimExc_No_Exception if none available.

Execution Context

Cell Context

See Also

SIM_clear_exception, SIM_last_error

Name

SIM_last_error — get error message from last frontend exception

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_last_error();

Python

import simics

simics.SIM_last_error(...)

Description

Returns the error message associated with the most recently raised frontend exception, even if that exception has been cleared.

The returned string is only valid until the next use of the Simics API in the same thread.

Execution Context

Cell Context

See Also

SIM_clear_exception, SIM_get_pending_exception

Name

SIM_add_notifier — add a notifier callback

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

notifier_handle_t *
SIM_add_notifier(
        conf_object_t *NOTNULL obj,
        notifier_type_t type,
        conf_object_t *subscriber,
        void (*callback)(conf_object_t *subscriber,
                         conf_object_t *NOTNULL notifier,
                         lang_void *data),
        lang_void *data);

Python

import simics

simics.SIM_add_notifier(...)

Description

SIM_add_notifier installs a notifier of type type on the object obj.

The subscriber argument should be the object listening for the notification; this object is passed as the first argument to the callback function. The installed callback is automatically removed if the subscriber object is deleted. It is legal to pass NULL in the subscriber argument if there is no object associated with the callback.

The data argument is passed as the last argument to the callback function.

The function returns a handle to the installed notifier or NULL if the notifier type is not supported by the object.

Adding a notifier callback from another notifier callback of the same notifier type and object does not trigger an immediate callback invocation (from the same call to SIM_notify).

Execution Context

Cell Context

See Also

SIM_delete_notifier, SIM_register_notifier

Name

SIM_class_has_notifier — query class for notifier

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_class_has_notifier(conf_class_t *NOTNULL cls, notifier_type_t type);

Python

import simics

simics.SIM_class_has_notifier(...)

Description

SIM_class_has_notifier returns true if the class cls supports the notifier specified by type.

Execution Context

Cell Context

Name

SIM_delete_notifier — delete notifier callback

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_delete_notifier(conf_object_t *NOTNULL obj, notifier_handle_t *handle);

Python

import simics

simics.SIM_delete_notifier(...)

Description

SIM_delete_notifier deletes the notifier callback specified by the handle handle.

Notifiers callbacks are deleted automatically when the subscribing object is deleted.

Deleting a notifier callback from another notifier callback of the same notifier type and object may or may not inhibit the last invocation of the deleted callback; this is undefined.

Execution Context

Cell Context

See Also

SIM_add_notifier

Name

SIM_describe_notifier, SIM_notifier_description — set short description

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_describe_notifier(notifier_type_t type, const char *NOTNULL generic_desc);

const char *
SIM_notifier_description(notifier_type_t type);

Python

import simics

simics.SIM_describe_notifier(...)
simics.SIM_notifier_description(...)

Description

SIM_describe_notifier sets generic_desc as a generic description of the notification specified by the type argument. If the function is called multiple times then the description supplied during the last invocation of the function will be used. The generic description is shown when no description has been provided to the SIM_register_notifier or SIM_register_tracked_notifier functions.

SIM_notifier_description returns a generic description that was set with the SIM_describe_notifier for the notification specified by the type argument, or the empty string if no description has been set.

Execution Context

Global Context

Name

SIM_has_notifier — query object for notifier

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_has_notifier(conf_object_t *NOTNULL obj, notifier_type_t type);

Python

import simics

simics.SIM_has_notifier(...)

Description

SIM_has_notifier returns true if the object obj supports the notifier specified by type.

Execution Context

Cell Context

See Also

SIM_register_notifier

Name

SIM_notifier_type — get notifier type

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

notifier_type_t
SIM_notifier_type(const char *NOTNULL type);

Python

import simics

simics.SIM_notifier_type(...)

Description

Given a notifier type type specified in the form of a string, return a notifier_type_t identifier which uniquely corresponds to this type.

This function always returns a valid notifier type; if a particular type string has not been seen before, then a new notifier type is created and associated with this string.

The string must consist of printable 7-bit ASCII characters, and by convention it should be expressed as a noun with words separated by dashes.

Execution Context

Cell Context

Name

SIM_notify — trigger notification callbacks

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_notify(conf_object_t *NOTNULL obj, notifier_type_t type);

Python

import simics

simics.SIM_notify(...)

Description

The SIM_notify function triggers all callbacks associated with the notifier notifier which have been installed on the object obj.

The order in which notifier callbacks are invoked is undefined, but the same order every time.

Execution Context

Cell Context

See Also

SIM_register_notifier, SIM_add_notifier

Name

SIM_register_notifier, SIM_register_tracked_notifier — register notifier

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_register_notifier(conf_class_t *NOTNULL cls, notifier_type_t type,
                      const char *desc);

void
SIM_register_tracked_notifier(conf_class_t *NOTNULL cls, notifier_type_t type,
                              const char *desc,
                              void (*subscribed_changed)(conf_object_t *obj,
                                                         notifier_type_t type,
                                                         bool has_subscribers));

Python

import simics

simics.SIM_register_notifier(...)
simics.SIM_register_tracked_notifier(...)

Description

These functions add the notifier type (returned by the SIM_notifier_type function) to the set of notifiers supported by the class cls. The desc argument can be used to provide any relevant documentation, e.g., information about when the notifier is triggered and how it should be used by the objects that subscribe to it. For uniformity, we suggest formatting the description similar to this one of the “frequency-change” notifier: “Notifier that is triggered when frequency changes. New frequency can be read via the frequency interface of the object.”

SIM_register_notifier is the base registration function. It should be used in most cases.

SIM_register_tracked_notifier accepts an additional argument - the subscribed_changed callback. This callback can be used to track whether any respective notification subscribers are installed. The callback is invoked in following cases:

• a. there are no objects subscribed to type’s notifications from obj of cls class, and a new object subscribes to such notifications, i.e., calls SIM_add_notifier. In this case the callback is invoked with the has_subscribers argument equal to true.
• b. the only object that was subscribed to type’s notifications from obj of cls class unsubscribes from such notifications, either explicitly by a call to SIM_delete_notifier, or implicitly when the subscriber object is deleted. In this case the callback is invoked with the has_subscribers argument equal to false.

If the subscribed_changed argument is equal to NULL then it is just ignored.

The subscribed_changed callback is not invoked while the notifier object is being deleted. Thus, if the callback relies on data structures owned by the notifier object, then it is still safe for the object’s destructor to deinitialize these data structures needed by the callback.

It is legal to call SIM_register_notifier multiple times for the same class and the same notifier type. All subsequent invocations done after the notifier was registered are ignored. Calling SIM_register_tracked_notifier multiple times registers multiple subscribed_changed callbacks. All of them will be invoked as it is specified above.

Execution Context

Global Context

See Also

SIM_notifier_type, SIM_notify, SIM_add_notifier

Name

SIM_add_global_notifier — add a global notifier callback

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

global_notifier_callback_t *
SIM_add_global_notifier(
        global_notifier_type_t type,
        conf_object_t *subscriber,
        void (*callback)(conf_object_t *subscriber, lang_void *data),
        lang_void *data);

Python

import simics

simics.SIM_add_global_notifier(...)

Description

SIM_add_global_notifier installs a callback on the global notifier of type type. The callback will be executed in Global Context. The callback can uninstall itself, using SIM_delete_global_notifier, but must not uninstall any other global notifiers.

The subscriber argument should be the object listening on the notifier; this object is passed as the first argument to the callback. The installed callback is automatically removed if the subscriber object is deleted. It is legal to pass NULL in the subscriber argument if there is no object associated with the callback.

The function returns a handle to the installed callback or NULL if the notifier type is unknown.

Adding a notifier callback from another notifier callback of the same notifier type does not trigger an immediate callback invocation.

Execution Context

Global Context

Name

SIM_add_global_notifier_once — add a global notifier callback

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

global_notifier_callback_t *
SIM_add_global_notifier_once(
        global_notifier_type_t type,
        conf_object_t *subscriber,
        void (*callback)(conf_object_t *subscriber, lang_void *data),
        lang_void *data);

Python

import simics

simics.SIM_add_global_notifier_once(...)

Description

The SIM_add_global_notifier_once is similar to SIM_add_global_notifier, except that the notifier will be removed automatically after the callback has been called once.

Execution Context

Global Context

Name

SIM_delete_global_notifier — delete global notifier callback

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_delete_global_notifier(global_notifier_callback_t *handle);

Python

import simics

simics.SIM_delete_global_notifier(...)

Description

SIM_delete_global_notifier deletes the global notifier callback specified by the handle handle.

Global notifier callbacks are deleted automatically when the subscribing object is deleted.

Deleting a notifier callback from another notifier callback of the same notifier type may or may not inhibit the last invocation of the deleted callback; this is undefined.

Execution Context

Global Context

Name

SIM_hap_add_type — register a new hap type

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

hap_type_t
SIM_hap_add_type(const char *NOTNULL hap,
                 const char *NOTNULL params,
                 const char *param_desc,
                 const char *index,
                 const char *desc,
                 int unused);

Python

import simics

simics.SIM_hap_add_type(...)

Description

Creates a run-time defined hap type.

The params parameter specifies the argument that callbacks for this hap is called with; e.g., "s" or "II". The first two arguments are always lang_void * and conf_object_t * respectively, and should not be included in that string. The table below shows which characters may be used, and what their meaning is:

param_desc should be a string of space-separated parameter names, or nullptr if params is the empty string. There should be one word in param_desc for each character in params.

index is a string describing the index value for this hap, or nullptr if there is no index value.

desc is a description string for the hap.

Exceptions

SimExc_General Thrown if hap is already defined. However, consequent calls with the same parameters will be successful, and return the same hap type number each time.

Return Value

The hap type number or -1 on error.

Execution Context

Global Context

Name

SIM_hap_get_name — get hap name by number

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_hap_get_name(hap_type_t hap);

Python

import simics

simics.SIM_hap_get_name(...)

Description

Returns the name of hap, or NULL for no such hap. The returned value is a static string that should not be modified or freed by the caller.

Execution Context

Cell Context

Name

SIM_hap_get_number — get hap number by name

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

hap_type_t
SIM_hap_get_number(const char *NOTNULL hap);

Python

import simics

simics.SIM_hap_get_number(...)

Description

Return the runtime number associated with a hap identifier. All haps are listed in the Haps chapter in each reference manual.

Exceptions

SimExc_Lookup Thrown if no hap is associated with name hap.

Return Value

The hap type number, or 0 on failure.

Execution Context

Global Context

Name

SIM_hap_is_active, SIM_hap_is_active_obj, SIM_hap_is_active_obj_idx — check if hap has callbacks

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_hap_is_active(hap_type_t hap);

bool
SIM_hap_is_active_obj(hap_type_t hap, conf_object_t *NOTNULL obj);

bool
SIM_hap_is_active_obj_idx(hap_type_t hap, conf_object_t *NOTNULL obj,
                          int64 index);

Python

import simics

simics.SIM_hap_is_active(...)
simics.SIM_hap_is_active_obj(...)
simics.SIM_hap_is_active_obj_idx(...)

Description

Indicate whether the hap has any callback functions to be called when the hap is triggered with the given arguments (object and index). The return value is approximate: if false, no functions would be called; if true, there may be functions to call.

The SIM_hap_is_active function should be avoided; it may be slower and less precise than the other variants.

Execution Context

Cell Context

Name

SIM_hap_occurred — trigger a hap occurrence

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

int
SIM_hap_occurred_always(hap_type_t hap, conf_object_t *obj,
                        int64 value, attr_value_t *NOTNULL list);

int
SIM_c_hap_occurred_always(hap_type_t hap, conf_object_t *obj,
                          int64 value, ...);

int
SIM_hap_occurred(hap_type_t hap, conf_object_t *obj,
                 int64 value, attr_value_t *NOTNULL list);

int
SIM_c_hap_occurred(hap_type_t hap, conf_object_t *obj,
                   int64 value, ...);

// not available in DML

int
SIM_c_hap_occurred_always_vararg(hap_type_t hap, conf_object_t *obj,
                                 int64 value, va_list ap);

int
SIM_c_hap_occurred_vararg(hap_type_t hap, conf_object_t *obj,
                          int64 value, va_list ap);

Python

import simics

simics.SIM_hap_occurred_always(...)
simics.SIM_hap_occurred(...)

Description

These functions are used to trigger a hap of type hap. When a hap triggers, all callback functions installed on the hap are called.

The obj argument is the object that the hap triggering is associated with. It may be nullptr for haps that are not associated with an object.

The value argument is used for filtering out callback functions to call based on the index or range that they are installed for. What the index or range corresponds to is hap specific, but could for example be the exception number for the Core_Exception hap.

SIM_hap_occurred() will only call the callbacks once every simulated cycle; if this hap is triggered several times during one cycle, the callbacks will still only be called once. The SIM_hap_occurred_always() function will always call the hap callback functions every time. It is recommended that SIM_hap_occurred_always() is used.

These hap triggering functions return whether or not there were any matching callback function registered on the hap. This can be useful information when one wants a default behavior to be triggered (for example, stopping the simulation) if nobody is listening to the hap.

The hap-specific parameters to the callback function can be passed in various ways: The SIM_c_hap_occurred... functions are only available in C/C++ and are variadic or take a va_list as argument. SIM_hap_occurred and SIM_hap_occurred_always are mainly intended to be used from Python, taking the parameters from an attribute value of list type, or an empty list ([]) if no parameters are passed. In all cases, the number and types of passed parameters must agree with the hap type definition.

Return Value

The return value is 0 if no callbacks are registered on the hap and non-zero if there are callbacks registered.

Exceptions

SimExc_General Thrown if hap is not a valid hap type or if the values in the list argument are of the wrong type.

Execution Context

Cell Context

Name

SIM_hap_remove_type — remove a hap type

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_hap_remove_type(const char *NOTNULL hap);

Python

import simics

simics.SIM_hap_remove_type(...)

Description

Remove a run-time defined hap type.

Execution Context

Global Context

Name

SIM_LOG_INFO… — output log message

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_log_info(int level, conf_object_t *NOTNULL dev, int grp,
             const char *NOTNULL fmt, ...);

void
SIM_log_spec_violation(int level, conf_object_t *NOTNULL dev, int grp,
                       const char *NOTNULL fmt, ...);

void
SIM_log_unimplemented(int level, conf_object_t *NOTNULL dev, int grp,
                      const char *NOTNULL fmt, ...);

void
SIM_log_error(conf_object_t *NOTNULL dev, int grp,
              const char *NOTNULL fmt, ...);

void
SIM_log_critical(conf_object_t *NOTNULL dev, int grp,
                 const char *NOTNULL fmt, ...);

void
SIM_log_message(conf_object_t *obj, int level, uint64 group_ids,
                log_type_t log_type, const char *message);

void
SIM_log_message_vararg(conf_object_t *NOTNULL obj, int level, uint64 grp,
                       log_type_t log_type, const char *NOTNULL fmt, ...);

// not available in DML

SIM_LOG_ERROR(dev, grp, ...);
SIM_LOG_CRITICAL(dev, grp, ...);
SIM_LOG_INFO(lvl, dev, grp, ...);
SIM_LOG_SPEC_VIOLATION(lvl, dev, grp, ...);
SIM_LOG_UNIMPLEMENTED(lvl, dev, grp, ...);
SIM_LOG_WARNING(dev, grp, ...);
SIM_LOG_INFO_ONCE(lvl1, lvl2, dev, grp, ...);
SIM_LOG_SPEC_VIOLATION_ONCE(lvl1, lvl2, dev, grp, ...);
SIM_LOG_UNIMPLEMENTED_ONCE(lvl1, lvl2, dev, grp, ...);
SIM_LOG_WARNING_ONCE(dev, grp, ...);

Python

import simics

simics.SIM_log_info(...)
simics.SIM_log_spec_violation(...)
simics.SIM_log_unimplemented(...)
simics.SIM_log_error(...)
simics.SIM_log_critical(...)
simics.SIM_log_message(...)

Description

These logging macros are used to emit information and error messages.

The level parameter indicates the importance; a lower value means a more important message. SIM_LOG_ERROR has no level parameter and will always emit messages.

level should be between 1 and 4:

1. important messages that are always printed
2. “high-level” informative messages
3. standard debug messages
4. detailed information, such as register accesses

The dev argument identifies the object the log message is about. The message is emitted for that object, so the object’s current log settings are used when the message is filtered and timestamped, and the object’s name is what appears in the formatted log message. In other words, pass the object whose behavior or state the message describes, not just the object making the call.

The grp parameter should have a bit set for each log group that the message corresponds to, as defined by the SIM_log_register_groups function, while a value of 0 equals any group.

The level and grp parameters allow the user to selectively display more or fewer messages using the log-level, log-group and log-type commands.

The fmt argument and those following it are used for string formatting in the same way as in the standard sprintf function.

The logging macros are among the few Simics APIs that may be called while a frontend exception is pending.

The use of the different macors is discussed in Simics Model Builder User’s Guide, section “Logging”:

• info: Normal informational message
• warning: Unexpected problem in the model, but simulation can continue.
• error: Unexpected error in the model (indicates a bug in the model).
• critical: Critical error that will interrupt the simulation (indicates a bug that the model may not recover from).
• spec_violation: Target program violates the specification.
• unimplemented: Attempt to use not yet implemented functionality.

If the sim->stop_on_error attribute is set to true, for example if Simics was started with the --stop-on-error command line flag, then Simics will exit with an error code when a log message of the error type is generated.

If the sim->warnings_as_errors attribute is set to true, for example if Simics was started with the --warnings-as-errors command line flag, then a log warning has the same effect as a log error.

From Python use the logging functions instead of the logging macros.

Execution Context

All contexts (including Threaded Context)

See Also

SIM_log_register_groups, SIM_attribute_error

Name

SIM_log_level, SIM_set_log_level — set and get log level

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

unsigned
SIM_log_level(const conf_object_t *NOTNULL obj);

void
SIM_set_log_level(conf_object_t *NOTNULL obj, unsigned level);

Python

import simics

simics.SIM_log_level(...)
simics.SIM_set_log_level(...)

Description

Retrieve or set the log level of an object. The level must be in the range 0..4 inclusive. Higher values mean more detailed logging.

Execution Context

Cell Context

Name

SIM_log_register_groups — register names of log groups

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_log_register_groups(conf_class_t *NOTNULL cls,
                        const char *const *NOTNULL names);

Python

import simics

simics.SIM_log_register_groups(...)

Description

Register a list of log groups that an object can use to separate messages. The order of the groups in the list defines the group ids that should be used in calls to SIM_LOG_INFO and similar functions. The group_ids argument to those functions should have a bit set corresponding to the group; i.e., a value of 1 for the first group, 2 for the second, 4 for the third, etc. names should be a NULL-terminated array.

A class may have up to 63 user-defined log groups.

The Default_Log_Group group is present on all classes. It is used for log entries where no group is specified.

Exceptions

SimExc_General Thrown in case of an error, e.g. if log groups are already registered.

Execution Context

Global Context

See Also

SIM_LOG_INFO

Name

ATOM_flags, ATOM_data, ATOM_size, ATOM_initiator, ATOM_completion, ATOM_list_end — transaction atom’s constructor

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

static inline atom_t ATOM_flags(transaction_flags_t val);
static inline atom_t ATOM_data(uint8 *val);
static inline atom_t ATOM_size(uint32 val);
static inline atom_t ATOM_initiator(conf_object_t *val);
static inline atom_t ATOM_completion(transaction_completion_t val);
static inline atom_t ATOM_list_end(int val);

Description

The functions construct transaction atoms.

ATOM_flags returns a transaction atom specifying transaction flags (see description of transaction_flags_t for information about available transaction flags).

ATOM_data returns a transaction atom that holds the pointer to a buffer that is used to get the data from (for write transactions) to store the data to (for read and instruction fetch transactions).

ATOM_size returns a transaction atom that holds the size of a transaction.

ATOM_initiator returns a transaction atom that holds the initiator of a transaction.

ATOM_completion creates a completion atom - a special atom that holds a callback that is invoked when a transaction is completed asynchronously.

ATOM_list_end returns a special atom that should end the list of transaction atoms. One can use the ATOM_LIST_END macro instead.

Execution Context

All contexts (including Threaded Context)

Example

Sample C code to create a 1-byte read transaction:

    uint8 val;
    atom_t atoms[] = {
        // the flags atom value specifies the transaction type:
        // - 0 defines a read transaction
        // - Sim_Transaction_Write - a write transaction
        // - Sim_Transaction_Fetch - an instruction fetch transaction
        ATOM_flags(0),

        ATOM_data(&val),
        ATOM_size(sizeof val),
        ATOM_initiator(obj),
        ATOM_LIST_END
    };
    transaction_t t = { atoms };

See Also

transaction_t, transaction_flags_t, transaction_completion_t

Name

SIM_complete_transaction — complete a deferred transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_complete_transaction(transaction_t *t, exception_type_t status);

Python

import simics

simics.SIM_complete_transaction(...)

Description

The SIM_complete_transaction completes a previously deferred transaction t using the exception status status. The transaction t must be the return value of a previous call to SIM_defer_transaction or a transaction passed to SIM_defer_owned_transaction.

If the transaction t has not been monitored, then the completion code is stored in an internal transaction field until the transaction is monitored with SIM_monitor_transaction or SIM_monitor_chained_transaction, at which time the completion callback is invoked using the stored completion code.

Note that SIM_complete_transaction is normally only used to complete asynchronous transactions. Synchronous transactions are completed by returning the appropriate return code directly from the issue method.

See Also

SIM_defer_transaction, SIM_monitor_transaction, SIM_monitor_chained_transaction, SIM_poll_transaction

Execution Context

Cell Context

Name

SIM_defer_owned_transaction — defer transaction completion using an existing transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

transaction_t *
SIM_defer_owned_transaction(transaction_t *t);

Python

import simics

simics.SIM_defer_owned_transaction(...)

Description

When a transaction cannot be completed immediately in the issue method of the transaction interface, then the completion can be deferred to a later time by calling SIM_defer_transaction which allocates a new transaction. One alternative is calling SIM_defer_owned_transaction which allows the caller to allocate the deferred transaction explicitly, in which case provides a heap-allocated transaction t which is linked to the transaction which should be deferred through its prev field. The provided transaction should have an owner and a completion atoms, which are used when the deferred transaction is completed.

When a transaction is deferred, the status code Sim_PE_Deferred must be returned from the issue method of the transaction interface.

Return Value

The transaction t, or NULL if the transaction was issued synchronously and cannot be deferred. When a transaction cannot be deferred, the issue method may choose to return the error status Sim_PE_Async_Required.

Execution Context

Cell Context

Name

SIM_defer_transaction — defer transaction completion

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

transaction_t *
SIM_defer_transaction(conf_object_t *obj, transaction_t *t);

Python

import simics

simics.SIM_defer_transaction(...)

Description

When a transaction cannot be completed immediately in the issue method of the transaction interface, then the completion can be deferred to a later time by calling SIM_defer_transaction with the transaction as a parameter.

The SIM_defer_transaction function returns a new transaction pointer which is guaranteed to be available until it is completed with a call to SIM_complete_transaction. When a transaction is deferred, the status code Sim_PE_Deferred must be returned from the issue method of the transaction interface.

Return Value

Deferred transaction, or NULL if the transaction was issued synchronously and cannot be deferred. When a transaction cannot be deferred, the issue method may choose to return the error status Sim_PE_Async_Required.

Execution Context

Cell Context

Name

SIM_get_transaction_bytes, SIM_get_transaction_bytes_offs, SIM_get_transaction_value_le, SIM_get_transaction_value_be — get transaction data payload

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_get_transaction_bytes(const transaction_t *t, buffer_t buf);

void
SIM_get_transaction_bytes_offs(const transaction_t *t, unsigned offs,
                               buffer_t buf, bool zerofill_holes);

uint64
SIM_get_transaction_value_le(const transaction_t *t);

uint64
SIM_get_transaction_value_be(const transaction_t *t);

Python

import simics

simics.SIM_get_transaction_bytes(...)
simics.SIM_get_transaction_bytes_offs(...)
simics.SIM_get_transaction_value_le(...)
simics.SIM_get_transaction_value_be(...)

Description

Copy the data payload from a transaction to the provided buffer buf. The size of the buffer must match the size of the transaction.

SIM_get_transaction_bytes_offs retrieves the bytes of the transaction which starts at offset offs. The sum of the offset and the buffer size must not exceed the transaction size.

SIM_get_transaction_value_le returns the value obtained when the transaction buffer is interpreted as an encoded little endian integer. The size of the transaction must not exceed 8 for this function to be used.

SIM_get_transaction_value_be returns the value obtained when the transaction buffer is interpreted as an encoded big endian integer.

Execution Context

All contexts (including Threaded Context)

Name

SIM_get_transaction_id — obtain checkpoint ID for a deferred a transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

int64
SIM_get_transaction_id(transaction_t *t);

Python

import simics

simics.SIM_get_transaction_id(...)

Description

The SIM_get_transaction_id function is used by objects that checkpoint the transaction state. The returned ID uniquely identifies the transaction and should be stored in a checkpoint together with the relevant state that the object keeps for the transaction. The same ID should then be given to SIM_reconnect_transaction during checkpoint load.

This function must only be called on a deferred transaction.

Execution Context

Global Context

See Also

SIM_reconnect_transaction

Name

SIM_inspect_address_routing — track the route of a transaction through memory hierarchy

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_inspect_address_routing(const map_target_t *NOTNULL mt,
                            transaction_t *NOTNULL t,
                            uint64 addr,
                            bool (*NOTNULL callback)(
                                    const map_target_t *mt,
                                    const transaction_t *t,
                                    uint64 addr,
                                    uint64 base,
                                    uint64 start,
                                    uint64 size,
                                    access_t access,
                                    translation_flags_t flags,
                                    lang_void *data),
                            lang_void *data);

Python

import simics

simics.SIM_inspect_address_routing(...)

Description

This function allows to track the route of a transaction through memory hierarchy. The route is traced as if the transaction t was issued at the address addr to the destination represented by the map target mt. Note that when this function is used the endpoint of the transaction will not be accessed.

The transaction t can be of any type: a read, a write, or an instruction fetch. Please note that the type of the transaction may affect its path through memory hierarchy. The size of the transaction t is ignored: when accesses are done larger transactions may be split depending on how the memory mapping are set up; no such splitting is occurred while the transaction route is traced with SIM_inspect_address_routing. It is allowed to use transactions with zero size.

The callback callback will be called for every device (memory spaces and translator objects) encountered on the transaction’s route to the destination as well as for the destination device (this is usually a device implementing the transaction interface or the io_memory interface). The first invocation of callback is done with the mt argument itself.

The arguments passed to the callback are:

• mt is a map target representing an intermediate device or the endpoint. If nothing is mapped then NULL (or None in Python) value is passed. The map target value should not be cached but it can be inspected
• t is usually the original transaction, but it can be also a new transaction in the case when additional atoms were appended to the original transaction via the transaction chaining (see, e.g., the documentation for the transaction_translator interface)
• addr is address inside the intermediate device or the endpoint where the transaction is sent
• base, start, size, access, and flags arguments describe the mapping which led to the mt map target. These arguments (except for access) are the same as the fields of the translation_t structure. Please refer to the translation_t’s documentation for their description. The access argument is a bitmask specifying access types. The bit corresponding to the type of the t transaction is always set. Other access bits may also be set optionally. But the latter is not guaranteed even if read/write/execute accesses are routed similarly
• data is the data argument passed to SIM_inspect_address_routing

The callback callback may return false to stop inspection. I.e. if the false value is returned callback will not be invoked any more.

Return Value

The function returns false if callback returned false in order to stop the inspection. Otherwise, true is returned.

Example

# The following example shows how one can determine
# the destination of a read transaction sent from a CPU object:

import conf, simics

def get_destination(memory_space, address):
    '''Example function returning destination object for the access
    sent to address in the memory space memory_space.'''
    mt = simics.SIM_new_map_target(memory_space, None, None)
    t = simics.transaction_t()  # read transaction of zero size
    l = [None]  # data for the callback

    def callback(mt, t, addr, base, start, size, access, flags, l):
        l[0] = (simics.SIM_map_target_object(mt)
                if mt is not None
                else None)
        return True

    simics.SIM_inspect_address_routing(mt, t, address, callback, l)

    # We free mt here but it can be saved and reused if needed.
    # Transaction t can also be reused.
    simics.SIM_free_map_target(mt)
    return l[0]

# Please specify here CPU object and address you are interested in:
cpu = simics.SIM_get_processor(0)
address_of_access = 0x1000

dest = get_destination(
    cpu.iface.processor_info_v2.get_physical_memory(),
    address_of_access)

print("Destination: ",
      dest.name if dest is not None else "'nothing is mapped'")

Execution Context

Cell Context

Name

SIM_inspect_breakpoints — find out breakpoints that a transaction would trigger

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_inspect_breakpoints(
        const map_target_t *NOTNULL mt,
        transaction_t *NOTNULL t,
        uint64 start,
        uint64 end,
        bool (*NOTNULL callback)(
                conf_object_t *trigger_object,
                breakpoint_set_t bp_set,
                const transaction_t *t,
                uint64 start,
                uint64 end,
                lang_void *data),
        lang_void *data);

Python

import simics

simics.SIM_inspect_breakpoints(...)

Description

The function allows to find out the breakpoints that would be triggered if a transaction t would be sent to the address range inside the map target mt. The address range is specified by the start and end arguments and includes both start and end of the range. Only breakpoints matching the transaction t’s type (i.e., a read, a write, or an instruction fetch) are reported. The size of the transaction t is ignored and can be zero.

For all matching breakpoints Simics invokes callback. The callback function may be called multiple times: with different trigger_object objects. The callback function gets the following two arguments that describe the breakpoints:

• trigger_object is the object implementing the breakpoint_trigger interface. The interface is used during simulation to signal that an access triggers a breakpoint
• bp_set is a set of breakpoints. The breakpoints match the transaction t’s type and intersect the [start, end] range within the mt map target. Bp_set should only be used inside callback. Data ownership is preserved by the caller (i.e., Simics)

Auxiliary information is provided to callback via the following arguments:

• t is usually the original transaction, but it can be also a new transaction in the case when additional atoms were appended to the original transaction via the transaction chaining (see, e.g., the documentation for the transaction_translator interface)
• callback’s start and end arguments specify an address range inside the trigger_object Simics object where the accesses to the requested address range inside the mt map target would go. The size of the range reported to callback may be smaller than the size of the requested range. This may occur, e.g., when different parts of the original address range are translated to different destinations based the memory mappings of the simulated machine
• callback’s data is the data argument passed to SIM_inspect_breakpoints

The callback function may return false to stop searching for breakpoints. I.e. if the false value is returned callback will not be invoked any more even if more breakpoints are present.

The SIM_inspect_breakpoints function is an inspection function: the endpoint of the transaction is never accessed when the function is used.

Return Value

The function returns false if callback returned false in order to stop the inspection. Otherwise, true is returned.

Execution Context

Cell Context

Name

SIM_issue_read_transaction, SIM_issue_write_transaction — functions for issuing transaction_t transactions

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE exception_type_t
SIM_issue_read_transaction(
        map_target_t *NOTNULL mt, uint64 addr, buffer_t buf,
        bool inquiry, conf_object_t *initiator);

FORCE_INLINE exception_type_t
SIM_issue_write_transaction(
        map_target_t *NOTNULL mt, uint64 addr, bytes_t bytes,
        bool inquiry, conf_object_t *initiator);

Description

These functions provide a simple way to issue read and write transaction_t transactions in C code. In Python, please use the SIM_issue_transaction function.

The functions have the following parameters:

• mt specifies the destination to send a transaction to.

• addr is the address used to issue a transaction.

• The SIM_issue_read_transaction’s buf parameter has buffer_t type and specifies a writable buffer for storing the read data. The data.data field points to the host memory where the results should be stored. The data.len field specifies the number of bytes to read.

• The SIM_issue_write_transaction’s bytes parameter is of bytes_t type and provides the data that should be written. The data.data field points to the buffer holding the data that should be written. The data.len field specifies the number of bytes to write.

• inquiry specifies whether the transaction should have the Sim_Transaction_Inquiry flag set. The flag signifies that side effects normally triggered by the transaction should be suppressed. Examples of side effects include triggering breakpoints and clearing “read-to-clear” device registers.

• initiator specifies the object issuing a transaction. It may be NULL. The value is used for setting the initiator atom of the transaction.

These functions don’t support the case when a model needs to provide custom atoms in transaction_t transactions. For such cases as well as when using Python the SIM_issue_transaction function should be used.

Return Value

Status of the issued transaction, usually Sim_PE_No_Exception or Sim_PE_IO_Not_Taken. See the exception_type_t’s documentation for more information.

Execution Context

Cell Context

Example

    /* Sample C code that reads an 8-byte little-endian value. If in the
       simulated hardware the endpoint stores values in big-endian format then
       macros from <simics/util/swabber.h> can be used for conversion. */

    uint64 value = -1;  // variable to read data into
    exception_type_t ex =
        SIM_issue_read_transaction(mt,
                                   addr,
                                   (buffer_t) {
                                       .data = (uint8 *)&value,
                                       .len = sizeof value,
                                   },
                                   false,  /* inquiry flag */
                                   obj     /* initiator */);

    if (ex == Sim_PE_No_Exception) {
        /* Read was successful: 'value' contains valid data. */
        SIM_LOG_INFO(4, obj, 0, "Read '%#llx' at %#llx", value, addr);
    } else {
        /* Read operation was not successful. There is no valid data
           in 'value'. Put any error handling code here. */
        SIM_LOG_ERROR(obj, 0, "Read at %#llx failed", addr);
    }

    /* Sample C code that writes an 8-byte little-endian value. If in the
       simulated hardware the endpoint stores values in big-endian format then
       macros from <simics/util/swabber.h> can be used for conversion. */

    uint64 write_value = 1;  // Data to write. '1' is written in this example.
    SIM_LOG_INFO(4, obj, 0, "Writing '%#llx' at %#llx", write_value, addr);
    exception_type_t ex =
        SIM_issue_write_transaction(mt,
                                    addr,
                                    (bytes_t) {
                                        .data = (uint8 *)&write_value,
                                        .len = sizeof write_value,
                                    },
                                    false,  /* inquiry flag */
                                    obj     /* initiator */ );

    if (ex == Sim_PE_No_Exception) {
        /* Write was successful. */
    } else {
        /* Write operation was not successful.
           Put any error handling code here. */
        SIM_LOG_ERROR(obj, 0, "Write at %#llx failed", addr);
    }

See Also

exception_type_t, map_target_t, SIM_issue_transaction, transaction_t

Name

SIM_issue_transaction — issue transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

exception_type_t
SIM_issue_transaction(const map_target_t *NOTNULL mt,
                      transaction_t *NOTNULL t, uint64 addr);

Python

import simics

simics.SIM_issue_transaction(...)

Description

SIM_issue_transaction issues the transaction t with the address addr to the destination represented by the map target mt. In Python, the mt argument can also be a conf_object_t.

Return Value

The function returns Sim_PE_Deferred if the transaction was deferred for completion at a some later time. The corresponding pseudo exception is returned if the transaction completed directly (normally Sim_PE_No_Exception or Sim_PE_IO_Not_Taken).

See Also

exception_type_t, transaction_t, SIM_new_map_target, SIM_free_map_target, SIM_issue_read_transaction, SIM_issue_write_transaction, SIM_defer_transaction, SIM_complete_transaction, SIM_monitor_transaction, SIM_transaction_wait

Execution Context

Cell Context

Name

SIM_monitor_transaction, SIM_monitor_chained_transaction — monitor a transaction for deferred completion

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

exception_type_t
SIM_monitor_transaction(transaction_t *t, exception_type_t ex);

exception_type_t
SIM_monitor_chained_transaction(transaction_t *t, exception_type_t ex);

Python

import simics

simics.SIM_monitor_transaction(...)
simics.SIM_monitor_chained_transaction(...)

Description

The SIM_monitor_transaction function monitors an asynchronously issued transaction for completion. A transaction is asynchronously issued if it has a completion atom with a callback which is not NULL. The function should be called after the transaction has been issued, and the ex status code should be the return value from function used to issue the transaction, for example the issue method of the transaction interface.

If ex equals Sim_PE_Deferred, then SIM_monitor_transaction will check if the transaction has in fact been completed already, and in that case, immediately invoke the completion callback. If the transaction is still uncompleted, then it will be marked as monitored and a subsequent call to SIM_complete_transaction will immediately complete the transaction by invoking the completion callback.

If ex is not equal to Sim_PE_Deferred, then the transaction has been completed synchronously, and the completion callback is called using ex as the completion status.

Note that it is illegal to call SIM_monitor_transaction for transactions that do not have a valid completion callback.

SIM_monitor_chained_transaction is similar to SIM_monitor_transaction except that when a deferred transaction is completed, its parent transaction will be completed too.

Return Value

Exception code returned by the completion function, or Sim_PE_Deferred if the transaction is monitored for completion at a later time.

See Also

SIM_defer_transaction, SIM_complete_transaction

Execution Context

Cell Context

Name

SIM_poll_transaction — check if a transaction has completed

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

exception_type_t
SIM_poll_transaction(transaction_t *t);

Python

import simics

simics.SIM_poll_transaction(...)

Description

The SIM_poll_transaction function checks if the transaction t is marked as completed, in which case the associated status code is returned and the completion status for the transaction is cleared. If the transaction is uncompleted, then Sim_PE_Deferred is returned.

It is illegal to call SIM_poll_transaction on a transaction which is monitored for completion using e.g. the SIM_monitor_transaction function.

See Also

SIM_complete_transaction

Execution Context

Cell Context

Name

SIM_reconnect_transaction — register that a deferred transaction has been restored

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_reconnect_transaction(transaction_t *t, int64 id);

Python

import simics

simics.SIM_reconnect_transaction(...)

Description

The SIM_reconnect_transaction function is used by objects that checkpoint the transaction state. It should be called when the relevant state has been read from a checkpoint.

Execution Context

Global Context

See Also

SIM_get_transaction_id

Name

SIM_register_python_atom_type — register an atom type which takes plain Python objects

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_register_python_atom_type(const char *NOTNULL name);

Python

import simics

simics.SIM_register_python_atom_type(...)

Description

Register an atom type named name. The atom type can be used from Python and can hold any Python object.

Execution Context

Global Context

Name

SIM_replace_transaction — replace transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_replace_transaction(transaction_t *t_old, transaction_t *t_new);

Python

import simics

simics.SIM_replace_transaction(...)

Description

Replace a transaction t_old with a new transaction t_new.

A transaction which has been issued and is deferred by some downstream device can be replaced with a different transaction by initiator. This is mostly useful when a transaction is allocated on the stack and it turns out that the transaction is not completed synchronously, in which case SIM_replace_transaction can be used to move the transaction to e.g. the heap.

This function ensures that the deferred transaction is properly linked with the t_new transaction. It is the caller’s responsibility to fill in the contents of the new transaction, including the prev pointer.

It is illegal to replace a transaction which has been monitored.

Execution Context

Cell Context

Name

SIM_set_transaction_bytes, SIM_set_transaction_bytes_offs, SIM_set_transaction_value_le, SIM_set_transaction_value_be, SIM_set_transaction_bytes_constant — set transaction data payload

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_set_transaction_bytes(const transaction_t *t, bytes_t bytes);

void
SIM_set_transaction_bytes_offs(const transaction_t *t, unsigned offs,
                               bytes_t bytes);

void
SIM_set_transaction_value_le(const transaction_t *t, uint64 value);

void
SIM_set_transaction_value_be(const transaction_t *t, uint64 value);

void
SIM_set_transaction_bytes_constant(const transaction_t *t, uint8 value);

Python

import simics

simics.SIM_set_transaction_bytes(...)
simics.SIM_set_transaction_bytes_offs(...)
simics.SIM_set_transaction_value_le(...)
simics.SIM_set_transaction_value_be(...)
simics.SIM_set_transaction_bytes_constant(...)

Description

Set the data payload of a transaction to the contents provided by bytes. The number of provided bytes must match the transaction size exactly.

The SIM_set_transaction_bytes_offs function sets some bytes of the transaction starting at offset offs. The sum of the offset and the number of provided bytes must not exceed the transaction size.

The SIM_set_transaction_value_le function sets the transaction bytes to the little endian representation of value. The size of the transaction must not exceed 8 for this function to be used. Similarly, SIM_set_transaction_value_be sets the transaction bytes to the big endian representation of the provided value. If the transaction is smaller than 8 bytes the functions will truncate the representation of the value.

The SIM_set_transaction_bytes_constant function can be used when an endpoint wants to set all transaction bytes to value.

Execution Context

Cell Context

Name

SIM_transaction_flags, SIM_transaction_is_fetch, SIM_transaction_is_write, SIM_transaction_is_read, SIM_transaction_is_inquiry — return transaction type

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

transaction_flags_t
SIM_transaction_flags(const transaction_t *NOTNULL t);

bool
SIM_transaction_is_fetch(const transaction_t *NOTNULL t);

bool
SIM_transaction_is_write(const transaction_t *NOTNULL t);

bool
SIM_transaction_is_read(const transaction_t *NOTNULL t);

bool
SIM_transaction_is_inquiry(const transaction_t *NOTNULL t);

Python

import simics

simics.SIM_transaction_flags(...)
simics.SIM_transaction_is_fetch(...)
simics.SIM_transaction_is_write(...)
simics.SIM_transaction_is_read(...)
simics.SIM_transaction_is_inquiry(...)

Description

SIM_transaction_flags returns a transaction_flags_t bitmap describing transaction type. Most of the flags can be queried using specific accessors.

The SIM_transaction_is_fetch function returns true if the transaction is an instruction fetch.

The SIM_transaction_is_read function returns true if the transaction is a read operation.

The SIM_transaction_is_write function returns true if the transaction is a write operation.

The SIM_transaction_is_inquiry function returns true if the transaction is an inquiry operation.

Execution Context

All contexts (including Threaded Context)

Name

SIM_transaction_initiator — return transaction initiator

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

conf_object_t *
SIM_transaction_initiator(const transaction_t *t);

Python

import simics

simics.SIM_transaction_initiator(...)

Description

Return the initiator of the transaction.

Execution Context

All contexts (including Threaded Context)

Name

SIM_transaction_is_deferrable — check if a transaction can be deferred for later completion

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_transaction_is_deferrable(const transaction_t *NOTNULL t);

Python

import simics

simics.SIM_transaction_is_deferrable(...)

Description

The function allows to check whether a transaction can be deferred (with the SIM_defer_transaction or SIM_defer_owned_transaction function) for later completion which is done with a call to SIM_complete_transaction.

Usually, this function is not needed since SIM_defer_transaction and SIM_defer_owned_transaction return NULL for transactions that cannot be deferred.

Return Value

false if the transaction was issued synchronously and cannot be deferred. Otherwise, true. When a transaction cannot be deferred, endpoint’s issue method of the transaction interface may choose to return the error status Sim_PE_Async_Required.

Execution Context

Cell Context

Name

SIM_transaction_size — return transaction size

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

unsigned
SIM_transaction_size(const transaction_t *NOTNULL t);

Python

import simics

simics.SIM_transaction_size(...)

Description

Return the size of the transaction, in bytes.

Execution Context

All contexts (including Threaded Context)

Name

SIM_transaction_wait — wait for transaction completion

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

exception_type_t
SIM_transaction_wait(transaction_t *t, exception_type_t ex);

Python

import simics

simics.SIM_transaction_wait(...)

Description

SIM_transaction_wait waits until an issued transaction has completed.

The function may only be invoked for transactions which have a completion atom containing a NULL pointer. The NULL pointer means that the initiator will wait for transaction completion using this function. Moreover, SIM_transaction_wait must always be called after a transaction has been issued with a NULL completion callback.

The ex argument should be the return value of the function or method used to issue the transaction.

SIM_transaction_wait will not return until the transaction has completed. While waiting, a different user-level thread will be activated, which allows simulated time to advance.

Note that the simulator cannot create a checkpoint while a call to the SIM_transaction_wait is in progress. See transaction-wait-all-completed for more information related to checkpointing and SIM_transaction_wait.

Transaction wait is not supported from all contexts. When unsupported, the transaction will appear to be issued synchronously.

Return Value

Completion status of the transaction

Execution Context

Cell Context

Name

SIM_arm_mem_trans_from_generic, SIM_mips_mem_trans_from_generic, SIM_ppc_mem_trans_from_generic, SIM_x86_mem_trans_from_generic, SIM_pci_mem_trans_from_generic — convert generic transaction to CPU specific

Synopsis

C and DML

#include <simics/arch/arm.h> // in C
import "simics/arch/arm.dml"; // in DML

struct arm_memory_transaction *
SIM_arm_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

#include <simics/arch/mips.h> // in C
import "simics/arch/mips.dml"; // in DML

struct mips_memory_transaction *
SIM_mips_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

#include <simics/arch/ppc.h> // in C
import "simics/arch/ppc.dml"; // in DML

struct ppc_memory_transaction *
SIM_ppc_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

#include <simics/arch/x86.h> // in C
import "simics/arch/x86.dml"; // in DML

struct x86_memory_transaction *
SIM_x86_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

#include <simics/devs/pci.h> // in C
import "simics/devs/pci.dml"; // in DML

struct pci_memory_transaction *
SIM_pci_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_arm_mem_trans_from_generic(...)
simics.SIM_mips_mem_trans_from_generic(...)
simics.SIM_ppc_mem_trans_from_generic(...)
simics.SIM_x86_mem_trans_from_generic(...)
simics.SIM_pci_mem_trans_from_generic(...)

Description

Converts a pointer to a generic memory transaction into a pointer to a CPU specific memory transaction. The generic memory transaction must be part of a CPU specific one for this function to succeed. The pointer returned will be the same the input pointer if conversion is allowed, and nullptr on failure.

Exceptions

SimExc_Type Thrown if the generic transaction is not part of a CPU specific transaction.

Return Value

New memory transaction pointer, or nullptr on error.

Execution Context

Cell Context

Name

SIM_c_get_mem_op_value_buf, SIM_get_mem_op_value_buf, SIM_get_mem_op_value_cpu, SIM_get_mem_op_value_le, SIM_get_mem_op_value_be — get value for a memory operation

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_c_get_mem_op_value_buf(const generic_transaction_t *NOTNULL mop,
                           uint8 *NOTNULL dst);

attr_value_t
SIM_get_mem_op_value_buf(const generic_transaction_t *NOTNULL mop);

uint64
SIM_get_mem_op_value_cpu(const generic_transaction_t *NOTNULL mop);

uint64
SIM_get_mem_op_value_le(const generic_transaction_t *NOTNULL mop);

uint64
SIM_get_mem_op_value_be(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_get_mem_op_value_buf(...)
simics.SIM_get_mem_op_value_cpu(...)
simics.SIM_get_mem_op_value_le(...)
simics.SIM_get_mem_op_value_be(...)

Description

Returns load or store value for a memory transaction. If the data size is 8 bytes or less the SIM_get_mem_op_value_be and SIM_get_mem_op_value_le functions can be used. For reads/writes larger than 8 bytes, the functions SIM_c_get_mem_op_value_buf or SIM_get_mem_op_value_buf should be used to get the data.

If your model is compiled with one of the DEVICE_IS_LITTLE_ENDIAN, DEVICE_IS_BIG_ENDIAN pre-processor defines, then the SIM_get_mem_op_value function can be used as an alias to the SIM_get_mem_op_value_le and SIM_get_mem_op_value_be versions.

The SIM_c_get_mem_op_value_buf function is only available from C/C++. It places the data into the buffer pointed to by dst. No endian conversion is performed, i.e. data is returned in target endianness. There is no alignment requirement on the dst parameter.

Warning

When called from a memory-hierarchy (timing-model) only store values can be retrieved, since the load has not yet performed. To get the load value, a snoop-device should be used.

Return Value

SIM_c_get_mem_op_value_buf returns nothing. The out parameter dst is filled with the data buffer of the memory transaction. SIM_get_mem_op_value_buf returns an attr_value_t (type data) containing the data buffer of the memory transaction. SIM_get_mem_op_value_be returns the zero-extended value in host endian order (interpreted as big endian) for the memory transaction. SIM_get_mem_op_value_le returns the zero-extended value in host endian order (interpreted as little endian). SIM_get_mem_op_value_cpu interprets the data in the default endian order for the initiating processor. This function can only be used for processor initiated memory operations. It is recommended that one of the other functions are used instead.

Exceptions

SimExc_Memory Thrown if the size of the operation is illegal.

Execution Context

Cell Context

Name

SIM_c_set_mem_op_value_buf, SIM_set_mem_op_value_buf, SIM_set_mem_op_value_cpu, SIM_set_mem_op_value_le, SIM_set_mem_op_value_be — set value for a memory operation

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_c_set_mem_op_value_buf(generic_transaction_t *NOTNULL mop,
                           const uint8 *NOTNULL src);

void
SIM_set_mem_op_value_buf(generic_transaction_t *NOTNULL mop,
                         attr_value_t value);

void
SIM_set_mem_op_value_cpu(generic_transaction_t *NOTNULL mop, uint64 value);

void
SIM_set_mem_op_value_le(generic_transaction_t *NOTNULL mop, uint64 value);

void
SIM_set_mem_op_value_be(generic_transaction_t *NOTNULL mop, uint64 value);

Python

import simics

simics.SIM_set_mem_op_value_buf(...)
simics.SIM_set_mem_op_value_cpu(...)
simics.SIM_set_mem_op_value_le(...)
simics.SIM_set_mem_op_value_be(...)

Description

Set the value returned to the requester of a memory operation. If the data size is 8 bytes or less the SIM_set_mem_op_value_be and SIM_set_mem_op_value_le functions can be used. For sizes larger than 8 bytes, the functions SIM_c_set_mem_op_value_buf or SIM_set_mem_op_value_buf should be used to set the data as an attr_value_t of data type.

If your model is compiled with one of the DEVICE_IS_LITTLE_ENDIAN, DEVICE_IS_BIG_ENDIAN pre-processor defines, then the SIM_set_mem_op_value function can be used as an alias to the SIM_set_mem_op_value_le and SIM_set_mem_op_value_be versions.

SIM_c_set_mem_op_value_buf is only available from C/C++, it operates on data in target endian order. There is no alignment requirement on the buf parameter.

SIM_set_mem_op_value_be takes data in host endian order and sets it in big-endian.

SIM_set_mem_op_value_le takes data in host endian order and sets it in little-endian.

SIM_set_mem_op_value_cpu takes data in host endian order and sets it in the default endian order for the initiating processor. This function can only be used for processor initiated memory operations. It is recommended that one of the other functions are used instead.

The functions that set the memory operation based on a value will truncate the representation of that value if the memory operation is smaller than 8 bytes.

Warning

These functions cannot be called from a timing-model since the real operation will overwrite the value set. They should instead be used from a snoop-device.

Exceptions

SimExc_Memory Thrown if the size of the operation is illegal.

Execution Context

Cell Context

Name

SIM_get_mem_op_page_cross — detect transaction split

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE unsigned
SIM_get_mem_op_page_cross(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_get_mem_op_page_cross(...)

Description

If a memory transaction was split because it straddled an MMU page, return 1 if it is the first part and 2 for the second. If the transaction was not split, return zero.

Execution Context

Cell Context

Name

SIM_get_mem_op_size — get transaction size

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE unsigned
SIM_get_mem_op_size(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_get_mem_op_size(...)

Description

Retrieve the size, in bytes, of a memory transaction.

Execution Context

Cell Context

Name

SIM_get_mem_op_type — get type of transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE mem_op_type_t
SIM_get_mem_op_type(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_get_mem_op_type(...)

Description

This function returns the type of the memory transaction.

See Also

generic_transaction_t, SIM_set_mem_op_type

Execution Context

Cell Context

Name

SIM_get_mem_op_type_name — get name of memory operation type

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

const char *
SIM_get_mem_op_type_name(mem_op_type_t type);

Python

import simics

simics.SIM_get_mem_op_type_name(...)

Description

Returns a string describing type or NULL if unknown.

Execution Context

Cell Context

Name

SIM_make_mem_op_write, SIM_make_mem_op_read — create a memory transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

generic_transaction_t
SIM_make_mem_op_write(physical_address_t addr, bytes_t data,
                      bool inquiry, conf_object_t *initiator);

generic_transaction_t
SIM_make_mem_op_read(physical_address_t addr, buffer_t buffer,
                     bool inquiry, conf_object_t *initiator);

Description

Create and return a memory transaction for writing data to addr, or reading from addr into buffer. The number of bytes to transfer is specified by data and buffer respectively. The initiator is the object issuing the transaction; it may be nullptr.

These functions do not actually perform any memory operation; they just construct the generic_transaction_t that can be used in other calls.

The buffer argument must refer to an allocated buffer, and data must contain valid data. They must remain valid and allocated during the life-time of the returned value.

Execution Context

All contexts (including Threaded Context)

Name

SIM_mem_op_ensure_future_visibility — request transaction visibility

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_mem_op_ensure_future_visibility(generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_ensure_future_visibility(...)

Description

Request that future accesses from the same virtual address (using a granularity given by the min_cacheline_size processor attribute) will be seen by the memory hierarchy. Otherwise, the simulator may cache accesses to this address for performance so that they are not seen by the memory model.

Execution Context

Cell Context

Name

SIM_mem_op_is_atomic — detect transaction atomicity

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_atomic(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_atomic(...)

Description

Return true if the transaction was part of an atomic instruction (usually a read followed by a write), false otherwise.

Execution Context

Cell Context

Name

SIM_mem_op_is_control — transaction control predicates

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_control(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_control(...)

Description

Checks whether mem_op is a control transaction (one that does not actually transfer any data, such as cache control operations).

Execution Context

Cell Context

Name

SIM_mem_op_is_data, SIM_mem_op_is_instruction — transaction data/instruction predicates

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_data(const generic_transaction_t *NOTNULL mop);

FORCE_INLINE bool
SIM_mem_op_is_instruction(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_data(...)
simics.SIM_mem_op_is_instruction(...)

Description

These functions check whether mem_op is a data or an instruction transaction. Currently, the only transactions that are instruction transactions are instruction fetches.

Execution Context

Cell Context

Name

SIM_mem_op_is_from_cache — Cache initiated transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_from_cache(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_from_cache(...)

Description

Checks whether mem_op is sent from a cache timing model.

Execution Context

Cell Context

Name

SIM_mem_op_is_from_cpu — CPU initiated transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_from_cpu(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_from_cpu(...)

Description

Checks whether mem_op is sent from a processor.

Execution Context

Cell Context

Name

SIM_mem_op_is_from_cpu_arch — CPU initiated transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_from_cpu_arch(const generic_transaction_t *NOTNULL mop,
                            ini_type_t arch);

Python

import simics

simics.SIM_mem_op_is_from_cpu_arch(...)

Description

Checks whether mem_op is sent from a processor of a specific architecture.

Execution Context

Cell Context

Name

SIM_mem_op_is_from_device — Device initiated transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_from_device(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_from_device(...)

Description

Checks whether mem_op is sent from a device.

Execution Context

Cell Context

Name

SIM_mem_op_is_prefetch — transaction control predicates

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_prefetch(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_prefetch(...)

Description

Checks whether mem_op is prefetch transaction.

Execution Context

Cell Context

Name

SIM_mem_op_is_read, SIM_mem_op_is_write — transaction read/write predicates

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_is_read(const generic_transaction_t *NOTNULL mop);

FORCE_INLINE bool
SIM_mem_op_is_write(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_is_read(...)
simics.SIM_mem_op_is_write(...)

Description

These functions check whether mem_op is a read or a write transaction.

Execution Context

Cell Context

Name

SIM_mem_op_may_stall — detect transaction stall possibility

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE bool
SIM_mem_op_may_stall(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_mem_op_may_stall(...)

Description

If true, the simulator will allow the transaction to stall execution. When false, a memory hierarchy must not attempt any stalling.

Execution Context

Cell Context

Name

SIM_set_mem_op_exception, SIM_get_mem_op_exception — get/set transaction exception

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_exception(generic_transaction_t *NOTNULL mop,
                         exception_type_t exc);

FORCE_INLINE exception_type_t
SIM_get_mem_op_exception(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_set_mem_op_exception(...)
simics.SIM_get_mem_op_exception(...)

Description

Retrieve or change the transaction exception. If set to a value other than Sim_PE_No_Exception, the transaction will be interrupted and an exception will be taken.

Execution Context

Cell Context

Name

SIM_set_mem_op_initiator, SIM_get_mem_op_initiator, SIM_get_mem_op_ini_type — get/set transaction initiator

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_initiator(generic_transaction_t *NOTNULL mop,
                         ini_type_t type, conf_object_t *obj);

FORCE_INLINE conf_object_t *
SIM_get_mem_op_initiator(const generic_transaction_t *NOTNULL mop);

FORCE_INLINE ini_type_t
SIM_get_mem_op_ini_type(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_set_mem_op_initiator(...)
simics.SIM_get_mem_op_initiator(...)
simics.SIM_get_mem_op_ini_type(...)

Description

Retrieve or change the transaction initiator type and object. These two parameters must agree.

Execution Context

Cell Context

Name

SIM_set_mem_op_inquiry, SIM_get_mem_op_inquiry — get/set transaction inquiry flag

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_inquiry(generic_transaction_t *NOTNULL mop, bool inquiry);

FORCE_INLINE bool
SIM_get_mem_op_inquiry(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_set_mem_op_inquiry(...)
simics.SIM_get_mem_op_inquiry(...)

Description

Retrieve or change the transaction inquiry flag. An inquiry read has no side-effects. An inquiry write has no other side-effect than changing the bytes at the specified address and size.

Execution Context

Cell Context

Name

SIM_set_mem_op_physical_address, SIM_get_mem_op_physical_address, SIM_set_mem_op_virtual_address, SIM_get_mem_op_virtual_address — get or set transaction address

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_physical_address(generic_transaction_t *NOTNULL mop,
                                physical_address_t pa);

FORCE_INLINE physical_address_t
SIM_get_mem_op_physical_address(const generic_transaction_t *NOTNULL mop);

FORCE_INLINE void
SIM_set_mem_op_virtual_address(generic_transaction_t *NOTNULL mop,
                               logical_address_t va);

FORCE_INLINE logical_address_t
SIM_get_mem_op_virtual_address(const generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_set_mem_op_physical_address(...)
simics.SIM_get_mem_op_physical_address(...)
simics.SIM_set_mem_op_virtual_address(...)
simics.SIM_get_mem_op_virtual_address(...)

Description

Retrieve or set the physical or virtual (logical) addresses of a memory transaction.

Execution Context

Cell Context

Name

SIM_set_mem_op_reissue — request transaction reissue

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_reissue(generic_transaction_t *NOTNULL mop);

Python

import simics

simics.SIM_set_mem_op_reissue(...)

Description

Request that the transaction will be re-issued if a non-zero stall time is returned from a memory hierarchy. Otherwise, the memory model will not see the transaction again.

Execution Context

Cell Context

Name

SIM_set_mem_op_type — set type of transaction

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_type(generic_transaction_t *NOTNULL mop, mem_op_type_t type);

Python

import simics

simics.SIM_set_mem_op_type(...)

Description

This function sets the type of the memory transaction.

See Also

generic_transaction_t, SIM_get_mem_op_type

Execution Context

Cell Context

Name

SIM_set_mem_op_user_data, SIM_get_mem_op_user_data — get/set transaction user data

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

FORCE_INLINE void
SIM_set_mem_op_user_data(generic_transaction_t *NOTNULL mop,
                         void *data);

FORCE_INLINE void *
SIM_get_mem_op_user_data(const generic_transaction_t *NOTNULL mop);

Description

Retrieve or change user data associated with the transaction. This data is not touched by Simics in any way and its handling and interpretation is left to the user. It can be used to pass information from a timing model to a snoop device, but the data does not survive across a stall.

Execution Context

Cell Context

Name

SIM_free_map_target — free a map target

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

void
SIM_free_map_target(map_target_t *mt);

Python

import simics

simics.SIM_free_map_target(...)

Description

Releases a map target and all associated resources. Safely does nothing if the argument is NULL.

Execution Context

Cell Context

See Also

SIM_new_map_target

Name

SIM_map_target_flush — ensure that old translations are not used

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

bool
SIM_map_target_flush(const map_target_t *NOTNULL mt,
                     uint64 base, uint64 size, access_t access);

Python

import simics

simics.SIM_map_target_flush(...)

Description

This API function is intended to be used for the implementation the translation_flush interface. The documentation for the translation_flush interface describes how to use this function for the interface implementation.

Additionally, this function can be used as a replacement for the SIM_translation_changed function to do a more fine-grain invalidation in the case when a previously returned translation becomes invalid.

When a previously returned translation becomes invalid the translator object should notify Simics which can have translations cached. To notify Simics the translator object can either do the call to the SIM_translation_changed function or, as a potential performance optimization, do a more fine-grain invalidation by using the SIM_map_target_flush function.

The translator object is expected to call the SIM_map_target_flush function for all targets of all previously returned translations which became invalid. If there are too many translations which are to be invalidated, then, performance-wise, it may be better just to do a single call to the SIM_translation_changed function. Also, if, during invalidation, any of the calls to the SIM_map_target_flush fails (i.e. the false value is returned by the function) then the translator is expected to call the SIM_translation_changed function which always succeeds.

Please note that there is no need to call the SIM_map_target_flush function for the translations which were tagged with the Sim_Translation_Dynamic flag. Either, no invalidation is needed for the destinations where nothing is mapped.

Execution Context

Cell Context

Name

SIM_map_target_object, SIM_map_target_port, SIM_map_target_target — inspect a map target

Synopsis

C and DML

#include <simics/device-api.h> // in C
// always available in DML

conf_object_t *
SIM_map_target_object(const map_target_t *NOTNULL mt);

const char *
SIM_map_target_port(const map_target_t *NOTNULL mt);

const map_target_t *
SIM_map_target_target(const map_target_t *NOTNULL mt);

Python

import simics

simics.SIM_map_target_object(...)
simics.SIM_map_target_port(...)
simics.SIM_map_target_target(...)

Description

Helper functions allowing inspection of the map_target_t objects.

Return Value

Returns a Simics object, port, or chained target which was used for the creation of the mt map target, i.e., the respective argument passed to SIM_new_map_target when the map target was created.

Execution Context

Cell Context

See Also

SIM_new_map_target

Name

SIM_new_map_target — create a map target