API Reference Manual

1 Introduction

This manual contains the reference documentation for most Simics APIs. It describes the Device API, as well as the interfaces and haps that are available for developing models. The manual also describes the Simulator API and its interfaces, for use when developing extensions to Simics. Furthermore, the manual details the Link Library API - that's used to create link models to connect devices in different cells. The Processor API is used to create models of processors for use in Simics; the reference documentation for the Processor API is also present in this manual. The manual is concluded with the reference documentation of the Python API.

This manual is primarily meant to be used as reference documentation, but it also describes some concepts of central importance closely related to the API. Refer to the other Simics manuals, listed in the Documentation Contents document, for more details about other things.

1.1 Programming Concepts

This chapter describes the major programming concepts in Simics. It is intended for anyone who wants to write extensions or modules for Simics.

A Simics module is just some executable code loaded dynamically into the simulator, so it could perform virtually any operation. To be of any practical use however, a module has to interact with Simics, other modules, or the user. Simics provides a set of functions (the Simics API) for the modules to work within the simulator framework. The API defines a number of concepts like classes, objects, interfaces, haps, and events, which will be presented below.

Simics modules can be written using different programming languages:

DML

Device Modeling Language (DML) has been designed to make writing new device model as simple as possible. It integrates in the language many of the concepts defined by the Simics API so that the user can focus on the model rather than on the interaction with Simics. This is by far the best language for writing device models. Note that although it was designed with device models in mind, DML can be used to develop other types of modules.

Python

Python can be used to quickly write a new Simics module. It is well suited for Simics extensions that are not called very often, like some types of statistics gathering, or BIOS emulation. It can also be used for fast prototyping of more complex extensions that later on will be rewritten in a compiled language like DML or C. Note that in all cases, DML is easier to use than Python to write a device model.

C/C++

C and C++ can be used for writing any type of Simics module. Writing in C or C++ exposes all interactions with Simics, which can be sometimes cumbersome. C or C++ development is only recommended for specialized cases when DML or Python do not provide the functionality needed. A few specialized functions in the API are only available to C and C++ modules.

SystemC

Integrating existing SystemC device models into Simics simulations is supported by the SystemC Library. The library provides a set of gaskets that bridge from TLM-2.0 interface to Simics interfaces and from Simics interfaces to TLM-2.0 interface. See the SystemC Library Programming Guide for details. For new device modeling, DML is recommended since it is more efficient to model in and automatically supports all Simics features.

This chapter will cover the concepts that the Simics API defines. It will also present how to use them, first in DML, then in Python and C/C++.

1.1.1 Classes and Objects

Each device is represented by an object whose attributes correspond to the state of the device.

Most Simics modules work the same way: they define classes describing the properties of an object. This includes its attributes, interfaces and the class name. The objects are created by instantiating a class and setting the required attributes.

Note that modules and classes are not the same thing. A module can define two or more classes, or none at all. But many modules define a single class with the same name as the module.

1.1.2 Type

When registering an attribute, a type definition should be provided for Simics to check that the attribute is always set properly. This type definition is a string that is defined according to the following rules:

• A simple type is represented by a single letter: i (integer), f (floating), s (string), b (boolean), d (data), o (object), D (dictionary), n (nil) or a (all).
• You can match several types by using the operator | like in s|o (string OR object).
• Lists are defined by square brackets: [ and ]. Lists can be specified in three ways:
  • Lists with a fixed elements: [iffsb] matches a list of five elements; an integer, two floating-point values, a string and a boolean value.
  • lists of an arbitrary number of elements: [i*] and [i+] both match any list containing only integers, with the difference that [i*] will match an empty list, while [i+] requires at least one list element.
  • lists with a size specifier: [i{1:4}] matches lists of integers with 1 to 4 elements. [i{4}] is the same as [i{4:4}] or [iiii], i.e., a list of four integers.

• The | operator has higher precedence than juxtaposition in the list type definitions, which means that [i|si|s] matches any two-elements list with integer or string elements. For clarity you can use a comma anywhere in the type definition, it will be ignored. The example could be written as [i|s,i|s]

As an example, the "[s*]|s" string defines an attribute that can hold either a string or a (possibly empty) list of strings.

When writing complex attributes, you may notice that the type description strings do not cover all the possibilities offered by the attribute structure definition. If you need to register attributes that cannot be described in a type string (like complex variable size lists), you will need to use the a type and perform the type checking by yourself in the set() function. You may also want to review your attribute and change its definition to match a possible type description, or divide your attribute into several simpler attributes.

For example, an attribute accepting a list composed of one object and one or more integers can not be described in a type string (list definition with variable size can only have one element). You may want to rewrite your attribute to use a sub-list for the integers: [o[i+]], or you can perform type checking yourself.

1.1.3 Interfaces

Interfaces allow objects to interact with each other. An interface defines a number of functions. Every class that implements an interface (by registering it) must define those functions. In some cases, it is sufficient to implement just a subset of the functions. An object A may then ask for an interface registered by an object B, and thus use the interface's functions to communicate with B. Simics comes with many predefined interfaces but it is also possible to define new interfaces.

One of the most important interfaces for a device class is probably the io_memory interface. Implementing the io_memory interface enables a class to be mapped into a memory space and be accessed by the simulated machine. In C or DML, it is defined as:

typedef struct io_memory_interface {
        int (*_deprecated_map)(conf_object_t *NOTNULL obj,
                               addr_space_t memory_or_io,
                               map_info_t map_info);
        exception_type_t (*operation)(conf_object_t *NOTNULL obj,
                                      generic_transaction_t *NOTNULL mem_op,
                                      map_info_t map_info);
      } io_memory_interface_t;

Other interfaces can be used for things like raising processor interrupts or implementing PCI device functionality.

Interfaces are either implemented by the device class itself, or by one of its ports. This way, a device can have several ports implementing the same interface, for example interrupt controllers with several sources or memory mapped devices with separate banks of registers.

1.1.4 Logging

A device model should log its activities so that it is possible to see what happens. It is useful both while developing the model and while developing target software, or to help finding problems in the system. Logging should not be used in attribute accessor functions or in CLI commands where there are other ways to report errors. The Simics API provides logging facilities that classifies log messages based on the following criteria:

level

The verbosity level ranging from 1 through 4 in decreasing importance order. The term 'high' and 'low' for log-level is based on its priority, thus 1 is the highest log-level.

type

Each log message belongs to a specific category:

info

Info or debug message without any consequence on the simulation.

warning

Warning message about a problem in the simulation, which however still allows the simulation to continue.

error

An error occurred that prevents the simulation (or part of the simulation) from running properly. Note that error messages do not have any logging level and are always printed. If the sim->fail_on_warnings attribute is set to true, for example if Simics was started with the -werror command line flag, then Simics will exit with an error code when a log message of the error type is generated.

critical

Used to signal serious errors that the model may not be able to resume from. Simics will stop the simulation as soon as a critical error is logged.

unimplemented

A model does not implement a specific functionality, bit or register.

spec_violation

A model received commands from the target program that violates the device specification.

group

A bit-field, defined and registered by the module, used to separate different part of the device, for example to separate between the configuration of a device and using the device's services, or the PCI interface and the Ethernet interface, etc.

1.1.5 Events

When a device model wants some action to be taken at a later time, it posts an event and returns control to the simulation engine. This will cause a callback to be called after the requested simulated time has passed.

For example, a device that wants to raise a time interrupt every 10 ms would post an event with a callback that raises the interrupt and then reposts the event with a 10 ms delay.

The events are posted on a clock, which is usually one of the processor cores in the system. Typically, each device is associated with one clock on which it posts all its events, but it is possible to choose which clock to post on, as long as it is in the same simulation cell as the device.

1.1.6 Haps

Another way that models may react to Simics events is to use haps. (The term was chosen because happenstance was considered too long.) To react to a hap, a module can register a callback function to the hap. This callback function will then be called every time the hap occurs. A complete list of all haps, descriptions of what parameters the callback functions should take and all functions used to register callbacks and manipulate haps can be found in chapter 12.

In general, haps are slower than notifiers, and therefore less suitable for communication between models. However, haps allow sending additional parameters to the callback function.

1.1.7 Commands

A user interface for a module can be created by adding new commands to the Simics command line interface. Commands can be bound to a specific namespace (i.e., a class or an interface) or to the global namespace.

• Commands that are bound to classes can be used to manipulate individual instances of that class. For example, all devices should have an info command that prints static information about the device and a status command that prints the state of the device.
• Commands that are bound to interfaces can be used on all objects implementing that interface.
• Global commands can be used for actions that do not pertain to a specific object. This is the case of commands like output-radix or print.

1.2 Simics API Information

This chapter describes the organization of the Simics API, and how to use it. It also shows how it interacts with system, Device, Simulator, Processor, and Link Library APIs.

1.2.1 The Simics API

Simics provides a number of unique APIs designed to allow the integration of new modules with the Simics family of products.

The Simics API is partitioned into three major parts, and an additional three groups of interfaces. There is one header file to include for each part of the Simics API, while the interfaces are split over several independent header files.

With a partitioned API the part needed by models can be kept as small and simple as possible, and the boundary between models and the simulator infrastructure is more clearly defined. A small Device API makes device modeling easier and reduces the risk of writing code with the potential to break determinism or multi-threading.

For a model representing a piece of hardware, you should only need to use the Device API together with the necessary model-to-model and model-to-simulator interfaces.

To find out how to get access to a particular API function or data type, you can use the api-help CLI command. This will tell you which header file, if any, to include (in either DML or C/C++).

1.2.1.1 Device API

The basic functionality of the Simics API and the only part available to device models.
The Device API is always accessible from DML; from C/C++ it is available using:

C:   #include <simics/device-api.h>
C++: #include <simics/cc-api.h>

1.2.1.2 Model-to-Model Interfaces

Interfaces between models typically represent standard hardware interfaces such as PCI, IC, Ethernet and interrupt lines. These interfaces are included in the Device API.

Accessible from DML and C/C++ using:

DML:   import "simics/devs/interface.dml";
C:     #include <simics/devs/interface.h>
C++:   #include <simics/c++/devs/interface.h>

where interface should be replaced with the actual header file name.

To find out which header file the foo interface is defined in, you can use the Simics CLI command api-help foo_interface_t.

1.2.1.3 Model-to-Simulator Interfaces

These interfaces fall into two categories:

• Interfaces that models may implement, which are called by the Simics framework.
• Interfaces implemented by the Simics framework or by Simics simulator objects, which may be called by simulation models.

They are accessed from DML and C/C++ using:

DML:   import "simics/model-iface/interface.dml";
C:     #include <simics/model-iface/interface.h>
C++:   #include <simics/c++/model-iface/interface.h>

where interface should be replaced with the actual header file name.

To find out which header file the foo interface is defined in, you can use the Simics CLI command api-help foo_interface_t.

1.2.1.4 Simulator API

The Simulator API contains the complete Simics API, including parts that are not available to models. This API may be used by simulator extensions.

Accessible from DML and C/C++ using:

DML:   import "simics/simulator-api.dml";
C/C++: #include <simics/simulator-api.h>

1.2.1.5 Simulator-to-Simulator Interfaces

Interfaces that are only used between simulator extensions and that should not be used by any model are collected into this group. These interfaces are part of the Simulator API.

Accessible from DML and C/C++ using:

DML:   import "simics/simulator-iface/interface.dml";
C:     #include <simics/simulator-iface/interface.h>
C++:   #include <simics/c++/simulator-iface/interface.h>

where interface should be replaced with the actual header file name.

To find out which header file the foo interface is defined in, you can use the Simics CLI command api-help foo_interface_t.

1.2.1.6 Processor API

The Processor API extends the Device API with functions needed when modeling processors in Simics.
Accessible from DML and C/C++ using:

DML:   import "simics/processor-api.dml";
C/C++: #include <simics/processor-api.h>

1.2.1.7 Link Library API

The Link Library API extends device modeling capabilities with Simics by allowing users to write Simics link models.
Accessible from DML and C/C++ using:

DML:   import "simics/devs/liblink.dml";
C/C++: #include <simics/devs/liblink.h>

1.2.1.8 Python API

Simics users may utilize Python to interact with the Simics API. For example, Python can be used to write or run Simics commands. Python may also be used to write components and modules for Simics.

The API is accessible from Python by importing the respective modules listed in chapter 10.

Python can also be used directly from the Simics command line and in set-up scripts.

1.2.2 API Version

Device makefiles have a variable called SIMICS_API, which specifies which version of the Simics API the model uses. It is a good idea to set SIMICS_API to the current Simics API. This will cause compile errors for uses of deprecated features.

SIMICS_API := 6

Python modules do not have a SIMICS_API flag to force compiler checking and thus need to be checked manually. Command line options can be passed to Simics to ensure any runtime usage of deprecated features trigger errors.

1.2.3 System Calls and Signals

On Linux, Simics will register its built-in signal handlers to make system calls restartable after the signal has been handled (cf. the SA_RESTART flag in the sigaction(2) man page).

However, only some system calls are restartable, so when writing modules for Simics, you have to make sure that you restart the other system calls yourself:

do {
        res = accept(sock, &saddr, &slen);
} while (res == -1 && errno == EINTR);

1.2.4 Text Output

Simics has its own text output routines that use the command-line window for display and also allow output to be directed elsewhere. To maintain this functionality these output routines should be used instead of the standard C library output routines: Use SIM_printf instead of printf, SIM_putchar instead of putchar, and so on.

The Simics output functions (SIM_write, SIM_printf, etc.) also send the resulting text to handlers registered using SIM_add_output_handler.

Here is an example showing how a module could get Simics to write a copy of all its text output to a log file:

static void
output_handler(void *file, const void *buf, size_t count)
{
    fwrite(buf, 1, count, (FILE *)file);
}

static void
init_local(void)
{
    SIM_add_output_handler(output_handler,
                           (void *)fopen("my.log", "a"));
}

1.2.5 Using Threads in Simics Modules

It is possible to write modules for Simics that use POSIX threads, but only a restrictive part of the Simics API can be used directly from such threads. It is possible, however, to post callbacks that have access to the entire API. One way to do that is through the SIM_thread_safe_callback API function. It is also possible to enter a context where a larger part of the Simics API is available. This, and the threading model in general, is discussed in some detail in chapter 2.

1.2.6 Header Inclusion Order

For modules written in C or C++, the general order of header file inclusion should be from most to least general:

When this order is observed problems related to interference between include files should be minimized. In particular, Simics may redefine some standard functions with preprocessor macros and this can cause problems unless the standard headers are included first.

1.3 API usage rules

1.3.1 Simics API value ownership rules

The owner of a value in memory is the code or object responsible for freeing the value when it is no longer needed. Failure to do so may cause excessive memory consumption (a memory leak). Deallocation of objects that are not owned, or use of objects after they have been freed, will likely result in a crash.

The ownership rules only apply to code written in C, C++ and DML. In Python, memory management is entirely automatic.

The general rules in Simics are:

• The caller of a function retains ownership of the arguments it passes to that function. Called functions do not assume ownership of the arguments they receive.
• The caller of a function receives ownership of the value returned from that function. Called functions must relinquish ownership of values they return.
• A return type const T *, for some type T, is taken to mean that ownership of the returned value is not transferred to the caller, overriding the previous rule.

Exceptions to the rules above are documented for each interface or API call.

Each data type has its own way of deallocation. It is generally documented where objects of that type are created; see below for some specific examples.

Strings

Null-terminated strings are freed using MM_FREE in C/C++, delete in DML. They are created using MM_MALLOC, MM_STRDUP or other functions that create heap-allocated strings. (The standard C library functions malloc, free etc should not be used.)

The pointer-to-const rule applies: a string returned as char * becomes owned by the caller, but not one returned as const char *.

Attribute values

Values of type attr_value_t are freed using SIM_attr_free.

Since the values may refer to heap-allocated data, they cannot be copied by simple (shallow) assignment. To create a (deep) copy of an attr_value_t that is safe to access after the original has been freed, use SIM_attr_copy.

The attr_value_t accessor functions return values that borrow references to parts of the argument. Therefore, the returned values cannot be altered, and cannot be used beyond the life-time of the argument. (This obviously does not apply to non-allocated values such as numbers or booleans.)

Simics-managed types

Values of some types are always owned and managed by Simics itself and should never be freed by the user. Examples are conf_object_t and conf_class_t.

1.3.2 API Execution Contexts

The set of Simics API functions and interface methods that can be called at a given point depends on the state of the execution thread at the time of the call. The thread states are classified into API execution contexts. Three distinct execution contexts are defined, and they are inclusive, as illustrated in the figure below:

The execution context defines the part of the Simics API that may be used

Below is a description of the defined execution contexts:

Global Context

Previously, this context was known as Outside Execution Context (OEC).

The most permissive context. A thread running in Global Context has exclusive access to all objects in the simulation.

In Global Context, either the simulation is not running or all simulation activity has temporarily been suspended. The front-end runs in this context, as do the callbacks from SIM_run_alone, SIM_thread_safe_callback and SIM_notify_on_socket with the run_in_thread argument set to 0. Module initialisation, object creation and object destruction are also performed in this context.

The full API is available, including functions and methods documented as callable in other contexts.

Cell Context (EC/IC)

This is a single context which was introduced in Simics 6 instead of Execution Context (EC) and Instruction Context (IC) that were around before.

The context used for most device simulation. Typically used when the simulation is running.

Only functions and methods documented as callable in Cell Context or Threaded Context are available in this context.

Other objects in the simulation may be accessed or referenced, but only objects belonging to the same simulation cell. The cell concept is discussed in some detail in section 2.3, but basically it is a partitioning of the simulation into groups of objects. Cell Context is always tied to a specific cell.

Most device code run in this context, for instance when a CPU accesses a device register, as do event callbacks and many hap handlers.

Threaded Context

Previously, this context was known as Foreign Thread Context (FTC).

The most restrictive context, denoting a thread which is in neither Cell Context nor Global Context.

Manually created threads and SIM_run_in_thread callbacks are examples where this context is applicable. Thread-aware models, like a CPU with support for multicore threading, also perform most of its simulation in Threaded Context.

The available API is limited to functions explicitly declared as being available in Threaded Context, but a more permissive context can be entered when needed. For example, SIM_thread_safe_callback posts a callback which is invoked in Global Context, and Cell Context can be reached with the SIM_ACQUIRE_CELL primitive.

While objects can be accessed in this context, it is only permitted after special primitives are used to ensure single-threaded access. This usually amounts to entering Cell Context, but thread-aware models can actually access their own object state directly from Threaded Context. This is discussed in chapter 2.

The reference manuals detail the permitted API execution context for each API function and interface method. Calls are allowed in the specified and more permissive contexts.

Violations of the API execution context rules have undefined consequences. They may result in warnings or error messages, but this is not guaranteed. In particular, a class implementing an interface method is under no obligation to perform any such checks.

1.4 Simics API Syntax

Most of the information in this chapter uses C syntax, extended with two additional keywords:

NOTNULL

The NOTNULL keyword means that this function argument must not be a null pointer. In Python, where None is used as the null pointer value, there will be an exception thrown if such a function is called with a None value.

PYTHON_METHOD

Most interfaces are in canonical form; i.e., they only contain function pointers, and the first argument is always the object whose interface is called.

For non-canonical interfaces, the keyword PYTHON_METHOD is used to mark regular methods. These should be called without their first argument when used from Python.

Note that there is no special mark-up for canonical interfaces.

2 Threading Model

This chapter describes the Simics threading model from a device model perspective. Important concepts as cells, thread domains and execution context are explained in some detail. The Standard Device Model and the Threaded Device Model are also defined.

2.1 Overview

At the highest level, a Simics configuration is partitioned into one or multiple simulation cells. Each cell can be simulated in parallel with the other cells, with maintained determinism.

Figure 1. Configuration is partitioned into cells. Cell membership is determined
by following queue and cell attributes to an actual cell object.

Distinct cells are loosely coupled. A typical example is a multi-machine configuration, where each machine consists of a single cell, and where the machines are connected with a simulated Ethernet network. Communication between cells occurs through special objects called links that forward messages between cells.

A device model should not access objects belonging to a different cell directly.

Each cell is partitioned into one or more thread domains. Models belonging to different thread domains can be simulated in parallel. However, objects within a single thread domain can only be accessed by a single thread at a time, namely by the thread currently holding the domain. A thread domain should be thought of as a high-level locking construct ensuring single-threaded access to the objects it contains.

Figure 2. Each cell is partitioned into thread domains.

Unlike the cell partitioning, which is static and given by the configuration, the partitioning of a cell into thread domains is performed by Simics as a function of the selected simulation mode, model capabilities, and any declared thread domain constraints.

The thread domains in a cell are not all equal. The thread domain which contains the cell object itself is special and is called the cell thread domain (cell TD). Objects residing in this domain use a very permissive device model, the Standard Device Model, described in section 2.6. Among other things, such models do not need to worry about thread domain boundary crossings or threading issues. Most models use this device model.

Models located in thread domains other than the cell TD are called thread-aware, and use the more restrictive Threaded Device Model, which is described in section 2.7.

The threads used to actually simulate the models are usually created by Simics, but models can also create their own threads. The Simics scheduler is briefly discussed in section 2.9.

2.2 Basic Module Requirements

To use multi-threading in Simics, all modules used in the simulation must be thread safe. This section describes what it means for a module to be thread safe, and what conditions must be fulfilled.

• It must run without execution context violations.
• The module makefile variable THREAD_SAFE must be set to yes when compiling the module.

Below is an example makefile for a module marked as thread safe. It can be found in the [project]/modules/sample-user-decoder directory if the sample-user-decoder has been copied to the project.

MODULE_CLASSES = sample-user-decoder

SRC_FILES = sample-user-decoder.c

SIMICS_API := 6
THREAD_SAFE = yes

include $(MODULE_MAKEFILE)

To make a module thread safe, global state should be avoided, both in the form of global variables and in the form of local static variables in C. Having constant global variables are fine. Modules written in pure DML do not have this problem since the DML compiler does not emit any non-constant global state.

Simics checks for some execution context violations during run-time and emits warnings if they occur. When running with multi-threading disabled, violations result in warnings that can optionally be turned off. With multi-threading enabled, violations cause hard errors.

If a module that is not marked with THREAD_SAFE=yes is loaded, multi-threading will be turned off automatically and a warning will be shown. The list-modules command will show whether a module is marked thread safe or not.

2.3 Simulation Cells

A cell is a group of configuration objects which may interact with each other through direct function calls. If a model needs to communicate with objects in other cells during the simulation, it needs to do this through links (see section 2.3.4 or the Link Library Programming Guide). A link introduces a delay in the communication (unless immediate_delivery is set), which means that messages cannot be sent and received in the same cycle.

In a configuration, a cell is represented by a configuration object of class cell. All objects that implement the cycle interface (referred to as clocks) automatically have a cell attribute that will point to the cell they belong to. Since all Simics objects have a queue attribute pointing at a clock object, they will by extension belong to the cell of their clock object. This is illustrated in the figure below:

Figure 3. Configuration is partitioned into cells

OBJECT cell0 TYPE cell {
}
OBJECT cell1 TYPE cell {
}
OBJECT cpu0 TYPE cpu {
       cell: cell0
}
OBJECT cpu1 TYPE cpu {
       cell: cell0
}
OBJECT cpu2 TYPE cpu {
       cell: cell1
}
OBJECT device0 TYPE device {
       queue = cpu0
}
OBJECT device1 TYPE device {
       queue = cpu0
}
OBJECT device2 TYPE device {
       queue = cpu2
}

In this example, device0 has cpu0 as a queue, and thus belongs to cell0, while device2 has cpu2 as a queue, and thus belongs to cell1.

2.3.1 Cells and Components

Simics provides an automatic cell partitioning based on top-level components. Each component object implements a create_cell() method that can return True or False to the question: should a simulation cell be created to contain this component and all its sub-components? By default, top-level components return True and all other components return False. By overriding this method, it is possible to automatically create cells at lower levels in the component hierarchy, or to disable cell creation altogether. In the latter case, the create_cell() should return False and the components should define cell objects themselves and assign clocks to them as appropriate, just as normal configuration objects.

The code snippets below show how to overload the create_cell() function for both old-style and hierarchical way of writing components.

class mycomp(component_object):
    ...
    def create_cell(self):
        return False

class mycomp(StandardConnectorComponent): # or StandardComponent
    ....
    class component(comp.StandardComponent.component):
        def create_cell(self):
            return False

Cells can also be created independently of components, by creating cell objects and setting the cell attribute of the clock objects which should belong to the cell.

2.3.2 Compatibility

If clock objects are created that do not point to a cell, then a default_cell object will be created, unless it exists already, to make sure these clock objects are scheduled as intended. This is a simple compatibility mechanism for use with older scripts. If you are building your configurations in several steps, but without using components, you will have to introduce your own cells and configure them.

2.3.3 Verifying the Cell Partitioning

The check-cell-partitioning command checks either a checkpoint or the currently loaded configuration for violations of the cell partitioning rules—namely, that objects belonging to one cell do not have any references to objects in another cell. Such references will be shown in the form of a chain of attributes connecting the cells.

An object is considered to belong to a cell if either it is a cell object, or if it refers to or is referred to by an object belonging to that cell. Object references are object values in (checkpointed) attributes.

False positives can be suppressed by defining the attribute outside_cell and setting it to true for objects that should not be considered part of any cell but still refer to other objects in cells. This can be necessary for objects that only use these references in safe ways, e.g., in Global Context.

2.3.4 Links

Links are the only Simics objects that should connect different cells together. In other words, link components are allowed to connect to device components belonging to different cells without breaking the cell isolation rules. This works because all communication over the links are asynchronous with a delay that is constrained by the synchronization parameters so that the information exchange never becomes indeterministic.

2.3.5 Synchronization domains

All cells are connected to a synchronization domain that controls the execution in the cells to ensure that they do not run too far apart in virtual time. The domain has a min_latency parameter that limits the allowed difference in time between clocks in all the cells connected to it. This works as a lower limit for the latency that link objects can use when communicating between cells.

2.4 Thread Domains

Each object in the simulation has a thread domain associated with it. The same thread domain can be associated with multiple objects.

The basic rule is that before the state of an object is accessed, the corresponding thread domain needs to be held by the thread performing the access. This ensures that an object is never accessed concurrently by two different threads.

The thread domain containing the cell object, the cell thread domain (cell TD), has some special properties. Sometimes it is referred to as just the "cell" for brevity, as in "acquiring the cell", and "holding the cell", which should be read as "acquiring the cell thread domain", and "holding the cell thread domain" respectively.

Division of a cell into thread domains

The cell TD should be thought of as a single-threaded domain. To a model in the cell TD, everything in the entire cell appears to be simulated from a single thread, even if this is not the case.

2.4.1 Relationship with API Execution Context

The relationship between the API execution context, defined in section 1.3.2, and thread domains is as follows:

Global Context

All thread domains (and by implication, all cells) in the simulation are held by the thread. The thread has exclusive access to all objects. CLI scripts, Python scripts, CLI commands, script-branches, and object initialization code, all run in Global Context.

Cell Context

The cell TD is held by the thread. The thread can freely access all other objects in the cell. Normal device models (i.e. models which are not thread-aware) can assume that they are invoked in this context.

Threaded Context

No thread domains are required to be held, but thread-aware models often hold their own thread domain.

2.4.2 Lock Semantics

A thread domain has the following basic properties:

• Exclusive - a thread domain can only be held by a single thread at a time
• Recursive - a thread domain can be acquired multiple times by the same thread
• Extendable - multiple thread domains can be held simultaneously by a thread, and the thread may access any object whose thread domain is held.

SIM_ACQUIRE_OBJECT

Acquires the thread domain associated with the object.

This function is intended to be used by thread-aware objects to obtain its own thread domain before modifying internal state protected by the domain.

This primitive does not enter Cell Context, even if the cell TD is acquired. The reason is that the retention mechanism is not activated (see below).

SIM_ACQUIRE_TARGET

Enters Cell Context if the specified object belongs to the cell TD. As part of entering Cell Context, the cell TD is acquired.

This primitive does nothing if the object does not belong to the cell TD. In other words, it is a no-op if the specified object is thread-aware.

Thread-aware code, which is not running in Cell Context, uses this function before invoking an interface method on an external object.

SIM_ACQUIRE_CELL

Enters Cell Context unconditionally. The specified object is associated with a cell whose TD is acquired as part of entering Cell Context.

The function should be used before calling an API function, or callback, requiring Cell Context.

Each primitive above should be used together with the corresponding release function. Macros are used in order to allow lock statistics to be collected with information about where the lock was acquired. There are also corresponding SIM-functions available.

2.4.3 Contention

• The thread is assigned a priority, using the table below.
• All domains held by the thread are released and marked as contended
• The current holder of the requested domain is notified that a thread is waiting for the domain, and the domain is marked as contended.
• The thread is blocked until all needed domains are available and can be assigned to the thread. Among all threads waiting for a domain, the domain can only be assigned to the thread with the highest priority.

The priority is assigned as follows:

 

Priority	Name	Situation
1	Execute	TD acquired for instruction execution (lowest priority)
2	Yield	domains reacquired after explicit yield
3	Entry	TD acquired, no other domains held
4	Entry 2	TD acquired, other TDs already held
5	Cell Entry	cell acquired with SIM_ACQUIRE_CELL/TARGET
6	Elevated	TD acquired in Cell Context
7	Message	TD acquired for delivery of direct memory message

In the table above, TD stands for a thread domain which is not the cell TD.

A contended thread domain is always assigned to the waiting thread with the highest priority. The domain is never released to a thread with lower priority, even if the domain is unused and the highest priority thread is waiting upon some other domain.

The priority scheme serves two purposes:

• It ensure that a deadlock situation cannot occur.
• It ensures that a thread in Cell Context is not preempted by other threads when there is lock contention.

2.4.4 Domain Retention

In Cell Context, a special mechanism is used when additionally acquired thread domains are released:

Domain retention mechanism

The release of additionally acquired domains is deferred until Cell Context is exited, or in other words, until the cell TD is released.

As an example, consider a thread doing the following, with CPU1 belonging to thread domain TD_cpu1, CPU2 to TD_cpu2, and device DEV to TD_cell, respectively:

1. CPU1 is simulated while holding TD_cpu1
2. EC is entered before the model calls an interface on DEV. TD_cell is acquired when EC is entered.
3. device DEV queries CPU2 for its cycle count. The TD_cpu2 domain is acquired and released during this operation, but the actual release of TD_cpu2 is deferred by the retention mechanism
4. device DEV posts an event on CPU2, again taking and releasing TD_cpu2
5. TD_cell is released when the DEV interface call returns, and the thread leaves Cell Context. The retention mechanism causes TD_cpu2 to be released for real at this point

2.5 Concurrency Modes

A device model can run in one of three concurrency modes. The modes are as follows:

Sim_Concurrency_Mode_Serialized

The model can assume Cell Context.

The model is put in the cell thread domain.

The device may interact with all objects in the cell without having to acquire any thread domains or take threading into account.

Objects in the same cell, including objects belonging in other thread domains, always have a stable state when queried.

Sim_Concurrency_Mode_Serialized_Memory

The model runs in Threaded Context.

The model is put in a separate thread domain.

The model is required to handle locking explicitly for both incoming and outgoing interface calls.

Whenever the model crosses a thread domain boundary, or enters Cell Context, all devices in the cell can potentially undergo state transitions.

Models that share memory must be grouped together (see the section on Thread Domain Groups below).

Sim_Concurrency_Mode_Full

The model runs in Threaded Context.

The model is put in a separate thread domain.

The model is required to handle locking explicitly for both incoming and outgoing interface calls.

Whenever the model crosses a thread domain boundary, or enters Cell Context, all devices in the cell can potentially undergo state transitions.

The model cannot assume that pages granted through the direct-memory subsystem are not accessed concurrently from a different thread, unless exclusive access have been requested explicitly.

2.5.1 Mode Selection

A model advertises its supported concurrency modes through the concurrency_mode interface. If the interface is omitted, and the object is not grouped with an object implementing the concurrency_mode interface (see the next section), then the model is assumed to only support Sim_Concurrency_Mode_Serialized.

If the model supports multiple modes, the interface is also used by Simics to select the concurrency mode the model should use. The mode is derived from the simulation mode set through the set-threading-mode command.

Device models normally run in the serialized concurrency mode, whereas CPU models preferably should support all the modes.

2.5.2 Thread Domain Groups

Objects that are part of a thread domain group will be put in the same thread domain. There can be different reasons for models to be part of the same thread domain. To keep memory accesses serialized when subsystem threading is used all models that share memory should be put in the same group. Even when running in multithreading mode there are objects that should reside in the same thread domain. Examples include:

• a CPU and an object representing its TLB
• a CPU and a CPU-specific timer
• two hyper threads which share a substantial amount of registers and whose implementation is not thread safe

1. constraints that are used in all concurrency modes
2. constraints that are only used in the serialized memory mode.

A port object is always placed in the same thread domain as its parent, unless it implements the concurrency_mode interface or is grouped explicitly with such an object.

For CPU models, the following is recommended:

Sim_Concurrency_Mode_Serialized_Memory

Tightly connected CPUs are grouped together.

In this context, tightly connected really means CPUs that run the same OS instance. CPUs which run distinct OS instances, but share memory, or devices, through some fabric, do not need to be placed in the same group.

Sim_Concurrency_Mode_Full

All CPU cores are placed in separate thread domains.

The above allows groups of tightly coupled CPUs to be simulated in parallel when the simulation is configured to use subsystem threading, while allowing all the CPUs to run in parallel in multicore mode.

2.6 Standard Device Model

By default, devices in Simics use the Standard Device Model. Such models run in the Sim_Concurrency_Mode_Serial concurrency mode.

Using the Standard Device Model amounts to being able to assume at least Cell Context when interface methods are invoked. Certain things, like object initialization, run in Global Context, which is the most permissive context.

2.6.1 Properties

Cell Context has the following properties:

• Any object belonging to the same cell may be accessed or referenced. Interfaces marked as available in Cell Context can be called directly without any additional steps.
• Accessed objects always have a stable state.
• The cell thread domain is held.
• The direct memory subsystem ensures that there is no observable concurrency with respect to simulated RAM.

2.7 Threaded Device Model

An object using one of the concurrency modes Sim_Concurrency_Mode_Serialized_Memory or Sim_Concurrency_Mode_Full is called a thread-aware model. The Threaded Device Model must be followed by such objects.

Thread-aware models run mostly in Threaded Context.

This section primarily discusses thread-aware models, but much of the contents also applies to code invoked directly from a "foreign" thread.

2.7.1 Programming Model

Thread-aware models need to take the following into account:

Incoming Interface Calls

Interfaces implemented by thread-aware models can be invoked in Threaded Context rather than Cell Context, and the thread domain associated with the object cannot be assumed to be held on entry.

It is the responsibility of the model to ensure that its state is protected, usually by calling SIM_ACQUIRE_OBJECT from its interface methods, as in the following example:

      static void
      some_interface_method(conf_object *obj)
      {
          domain_lock_t *lock;
          SIM_ACQUIRE_OBJECT(obj, &lock);
          /* ... internal state is protected by the TD ... */
          SIM_RELEASE_OBJECT(obj, &lock);
      }
    

No extra protection is needed for interfaces which are only available in OEC. All thread domains are already held on entry.

Note: There are a few situations when the model is invoked with its thread domain already held:

• The run method of the execute interface is invoked with the object's thread domain held. The model should not acquire the domain again, since this would block the signaling mechanism used to notify the model when another thread tries to acquire the domain.
• The methods in the the direct_memory_update interface are always invoked with the thread domain held.

Outgoing Interface Calls

When a thread-aware model invokes an interface method on an object which is not known to reside in the same thread domain, then the call must be protected with SIM_ACQUIRE_TARGET, with the interface object provided as an argument. This ensures that Cell Context is entered, when necessary.

Example of an "outgoing" interface call:

      domain_lock_t *lock;
      /* incoming interface calls may occur here */
      SIM_ACQUIRE_TARGET(target_obj, &lock);
      some_interface->some_method(target_obj, ...);
      SIM_RELEASE_TARGET(target_obj, &lock);
    

Note: If the target object is thread-aware, then SIM_ACQUIRE_TARGET will actually be a no-op.

Note: If the cell TD is busy when SIM_ACQUIRE_TARGET is executed, then the model may see incoming interface calls while waiting for the domain, since all held domains are temporarily released while waiting.

API Calls

Cell Context must be entered before any API function can be called which requires this context. The context is entered with the SIM_ACQUIRE_CELL primitive, as in this example:

      domain_lock_t *lock;
      /* incoming interface calls may occur here */
      SIM_ACQUIRE_CELL(obj, &lock);
      /* this code runs in Cell Context */
      breakpoint_id = SIM_breakpoint(...);
      SIM_RELEASE_CELL(obj, &lock);
    

Some functions that need this protection:

• HAP functions (SIM_hap_add_callback, ...)
• SIM_breakpoint, SIM_delete_breakpoint
• SIM_issue_transaction

There are, however, many functions that can be called directly in Threaded Context, e.g.

• functions performing logging (SIM_log_info, ...)
• functions returning constant object properties (SIM_object_name, SIM_get_interface, ...)
• allocations (MM_MALLOC, SIM_alloc_attr_list, ...)
• accessors (SIM_attr_integer, SIM_transaction_is_read, ...)
• dbuffer API (but the dbuffer itself is not thread safe)
• SIM_run_unrestricted, SIM_run_alone

Some API functions can be called directly, as long as the TD has been acquired for the object in question:

• event related functions (SIM_event_post_cycle, ...)
• time related functions (SIM_time, SIM_cycle_count, ...)

Callbacks

Callbacks triggered by the model are often expected to be dispatched in Cell Context. The model must enter Cell Context using SIM_ACQUIRE_CELL before dispatching such callbacks.

Note: Events registered with the Sim_Event_No_Serialize flag and callbacks used by the CPU instrumentation framework do not need to be protected. For these callbacks, it is the callee's responsibility to be aware that the context can be more limited than Cell Context. This is a performance optimization to allow fast callbacks with minimal overhead.

Attributes

Registered attribute setters and getters are automatically protected; an object's thread domain is always held when attribute setters and getters are invoked.

Note: Attributes should be used for configuration and to hold state. Attributes should never be used for communication between objects during simulation.

2.7.2 Domain Boundary Crossings

Whenever a thread-domain boundary is crossed, already held domains may temporarily be released to avoid deadlock situations. This allows unrelated, incoming, interface calls to occur at such points.

A thread-aware model must ensure that potential state changes caused by incoming interface calls are taken into account. This is one of the challenging points when writing a thread-aware model.

In Cell Context, boundary crossings are not an issue, since this context is prioritized exactly to avoid unexpected interface calls. Thread-aware models, running in Threaded Context, are not as fortunate and need to be aware of the possibility.

It is recommended that incoming interface calls are kept as simple as possible for thread-aware models. If possible, the interface action should be deferred and handled from an inner loop, especially for CPUs. For instance, a RESET interface should not perform the reset immediately, but instead set a flag that a reset should be performed before dispatching the next instruction.

2.7.3 Mixing Thread Domains and Mutexes

It is easy to run into problems when different locking schemes are combined. This is also the case when mixing mutexes and thread domains. The following examples illustrate some pitfalls:

Example 1

Acquiring a thread domain while holding a lock:

      Thread 1                  Thread 2
      Locks Mutex1              Acquires TD1
      Acquires TD1 (blocks)     Locks Mutex1 (blocks)
    

Thread 1 will never be able to acquire TD1 since this domain is held by thread 2 which blocks on Mutex1.

Note that the above example will also cause a deadlock if two mutexes are used rather than one mutex and one thread domain:

      Thread 1                  Thread 2
      Locks Mutex1              Locks Mutex2
      Locks Mutex2 (blocks)     Locks Mutex1 (blocks)
    

Whereas no deadlock occurs with two thread domains:

      Thread 1                  Thread 2
      Acquires TD2              Acquires TD1
      Acquires TD1*             Acquires TD2*
       *Not a deadlock - Simics detects and resolves this situation
    

Example 2

Waiting for a condition variable while holding a thread domain:

      Thread 1               Thread 2
      Acquires TD1           .
      Waits for COND1	     Acquires TD1 (blocks)
                             Releases TD1 (not reached)
	                     .
                             Signals COND1 (not reached)
    

Sleeping on a condition while holding a thread domain easily leads to deadlocks. Threads requiring the thread domain will get stuck and potentially prevent the condition from being signaled.

In practice, code can seldom make assumptions about which thread domains are held. For instance, an interface function can be invoked with an unknown set of thread domains already acquired. The domain retention mechanism also makes the picture more complex.

To avoid deadlocks, the following general principles are encouraged:

• Do not acquire a thread domain while holding a lock
• Do not sleep while holding a thread domain
• Use thread domains to prevent concurrent simulation
• Use mutexes to protect specific data structures

  domain_lock_t *lock;
  SIM_DROP_THREAD_DOMAINS(obj, &lock);
  /* no thread domains are held here... */
  SIM_REACQUIRE_THREAD_DOMAINS(obj, &lock);

2.7.4 Thread-Aware CPUs

Thread-aware CPUs have a few extra things to consider.

Execution

CPU models are driven from the run method of the execute interface. The method is invoked in Threaded Context, with the CPU thread domain already held.

The thread calling run is a simulation thread managed by the Simics scheduler. It is possible that this thread is used to simulate more than one model.

The model is not guaranteed that the run function is always invoked by the same thread.

Signaling

Whenever another CPU, or a device model, tries to acquire the CPU domain, the CPU is notified through the execute_control interface.

When a CPU is signaled in this way, it should as soon as possible call SIM_yield_thread_domains. The yield function ensures that pending direct memory update messages are delivered and allows other threads to invoke interfaces on the CPU object.

The signaling methods are invoked asynchronously, and the implementation must not acquire any thread domains or call API functions.

The signaling only occurs when the CPU's thread domain is the only domain held. Acquiring an additional domain, even the already held domain, temporarily blocks the signaling mechanism. Due to this, it is important that the CPU thread domain is not acquired in the run method, since it is already held on entry.

Note: To minimize the waiting time for other threads, it is important that the signaling is detected quickly.

Direct Memory

The methods of the direct_memory_update interface are invoked with the CPU thread domain already acquired. The model should service requests quickly and without acquiring additional thread domains.

2.7.5 Thread Domain Contention

Statistics about thread-domain acquisition can be collected with the enable-object-lock-stats command. This functionality is useful when a model is optimized to avoid unnecessary thread-domain crossings or to investigate thread-domain contention.

There is a definite overhead associated with collecting the statistics; it should not be turned on by default.

The collected statistics can be shown with the print-object-lock-stats command:

┌─────┬───────┬─┬────────────────────────────┬─────────────────────────────────┐
│Count│Avg(us)│ │          Function          │               File              │
├─────┼───────┼─┼────────────────────────────┼─────────────────────────────────┤
│  396│   1.94│ │get_cycles                  │core/clock/clock.c:172           │
│  369│   1.91│ │post                        │core/clock/clock.c:254           │
│   27│   2.00│C│handle_event                │core/clock/clock-src.c:211       │
│   12│   2.33│ │pb_lookup                   │core/common/image.c:3965         │
│    7│   2.86│C│cpu_access                  │cpu/cpu-common/memory.c:508      │
│    8│   2.38│C│perform_io                  │cpu/x86/x86-io.c:128             │
│    6│   1.83│ │dml_lookup                  │core/common/memory-page.c:431    │
│    3│   3.00│C│call_hap_functions_serialize│core/common/hap.c:1410           │
│    3│   2.33│ │cancel                      │core/clock/clock.c:280           │
└─────┴───────┴─┴────────────────────────────┴─────────────────────────────────┘

The command basically displays the location in the source where thread domains have been acquired, and how quickly the domains were acquired. The 'C' indicates that Cell Context was entered.

2.8 Foreign Threads

Threads created explicitly by models are called foreign threads. Such threads run in Threaded Context. There are also various API functions that registers callbacks that are called in FTC, like SIM_run_in_thread and SIM_notify_on_socket with the run_in_thread argument set to 1.

Many of the things stated in the preceding section is also relevant to foreign threads. One difference, however, is that foreign threads can be created by models using the Standard Device Model.

2.8.1 Device Interactions

The following outlines how a foreign thread can interact with the rest of the simulation:

Accessing a Device Object

A foreign thread can enter Cell Context using the SIM_ACQUIRE_CELL function. Once in Cell Context, the thread can interact with the object just like a normal device would do, and without needing any additional locking.

      /* foreign thread */
      SIM_ACQUIRE_CELL(obj, &lock);
      /* safe to access the device */
      SIM_RELEASE_CELL(obj, &lock);
    

Entering Global Context

A foreign thread can post callbacks that are run in Global Context, and hence allowed to access everything in the simulation. This is done using SIM_thread_safe_callback

      static void
      global_context_callback(void *data)
      {
          /* this code runs in Global Context */
      }

      {
          /* ... Threaded Context ... */
          SIM_thread_safe_callback(global_context_callback, data);
      }
    

It should be noted that the function posting the callback returns immediately, usually before the callback has started executing. Also, posting a Global Context callback is a relatively expensive operation since it involves stopping all running CPUs.

2.9 Simics Scheduler

The Simics scheduler is responsible for ensuring that models implementing the execute interface are scheduled. It is also responsible for mapping actual threads to the simulation workload and for keeping distinct CPUs synchronized in virtual time.

2.9.1 Basic Operation

The Simics Scheduler compiles a list of simulation tasks that can be run in parallel. Each task consists of a thread domain with one or more models implementing the execute interface.

The number of tasks that can be simulated in parallel depends on the thread domain partitioning, which in turn depends on the selected simulation mode. The simulation mode is configurable with the set-threading-mode command.

The available tasks are mapped to a set of execution threads managed by the scheduler. The number of threads used depends on the host hardware and any limit imposed by the user. The latter is settable with the set-thread-limit command.

A particular simulation task is usually simulated from a specific simulation thread in order to maximize cache locality. However, a task can be migrated to another thread when this is needed for load-balancing reasons. Thus, a model should not make any assumptions about the thread it is simulated from.

2.9.2 Virtual Time Synchronization

The scheduler ensures that all CPUs (and clocks) are kept synchronized in virtual time. More specifically, the virtual time for a pair of CPUs are not allowed to differ more than a fixed amount. A simulation task becomes blocked when it is about to break this invariant.

If a single thread domain contains more than one object implementing the execute interface, then the scheduler switches between them in a round-robin fashion. Each executor is simulated until the virtual time has advanced one time-quantum. The interval is settable with the set-time-quantum command.

The time difference for CPUs in the same cell, but in distinct thread domains, is not allowed to exceed the max-time-span limit. The limit is settable with the set-max-time-span command and is usually of the same order of magnitude as the time quantum.

The time difference between CPUs in distinct cells is kept below the min-latency limit. This limit is set with the set-min-latency command. The min-latency is often allowed to be a bit higher than the other limits.

3 Device API

The Simics Device API is a set of types and functions that provide access to Simics functionality from device models, usually written in DML or C/C++. The Device API is the same in all languages but the syntax of the types and functions declarations will of course differ.

3.1 Frontend Exceptions

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.

The following exception types are defined in the Simics API:

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;

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.

3.2 Device API Data Types

3.2.1 Generic Data Types

attr_value_t

NAME

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:

Kind	C payload	Python type
Invalid	-	raises exception
String	const char *	str or unicode
Integer	int64 or uint64	int or long
Boolean	bool	bool
Floating	double	float
Object	conf_object_t *	simics.conf_object_t
List	array of attr_value_t	list
Dict	array of pairs of attr_value_t	dict
Data	array of bytes	tuple of small integers
Nil	-	None

The members inside attr_value_t should not be accessed directly. Instead, use the corresponding functions for each type:

Constructor	SIM_make_attr_TYPE
Destructor	SIM_attr_free
Type predicate	SIM_attr_is_TYPE
Access	SIM_attr_TYPE

Values of type List and Dict can be modified using SIM_attr_TYPE_set_item and SIM_attr_TYPE_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

buffer_t

NAME

buffer_t

SYNOPSIS

typedef struct {
        uint8 *data;
        size_t len;
} 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.

bytes_t

NAME

bytes_t

SYNOPSIS

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

cbdata_t, cbdata_call_t, cbdata_register_t, cbdata_type_t

NAME

cbdata_t, cbdata_call_t, cbdata_register_t, cbdata_type_t

SYNOPSIS

typedef struct {
        const char *name;
        void (*dealloc)(void *data);
} cbdata_type_t;

typedef struct cbdata cbdata_t;

typedef cbdata_t cbdata_register_t, cbdata_call_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

class_data_t

NAME

class_data_t, class_kind_t

SYNOPSIS

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;

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.

Note: The old class functions are legacy. New code should use class_info_t and SIM_create_class.

.

class_info_t

NAME

class_info_t, class_kind_t

SYNOPSIS

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;

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, and in all other objects that are created at the same time. This method is supposed to do any object initialization that require attribute values. Communication with other objects, e.g. via interfaces, should ideally be deferred until the objects_finalized method, but is permitted if SIM_require_object is first called.

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.

conf_object_t

NAME

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.

data_or_instr_t

NAME

data_or_instr_t

SYNOPSIS

typedef enum {
        Sim_DI_Instruction      = 0,
        Sim_DI_Data             = 1
} data_or_instr_t;

DESCRIPTION

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

endianness_t

NAME

endianness_t

SYNOPSIS

typedef enum {
        Sim_Endian_Target,
        Sim_Endian_Host_From_BE,
        Sim_Endian_Host_From_LE
} endianness_t;

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.

exception_type_t

NAME

exception_type_t

SYNOPSIS

typedef enum {
        SIM_PSEUDO_EXC(SIM_PSEUDO_EXC_ENUM)
} exception_type_t;

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.

Simics internal:

Sim_PE_Silent_Break, Sim_PE_Instruction_Finished, Sim_PE_Last.

generic_transaction_t

NAME

generic_transaction_t

DESCRIPTION

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

global_notifier_type_t

NAME

global_notifier_type_t

SYNOPSIS

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,
} global_notifier_type_t;

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,

hap_type_t

NAME

hap_type_t

SYNOPSIS

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

init_arg_t

NAME

init_arg_t

SYNOPSIS

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.

int8, int16, int32, int64, uint8, uint16, uint32, uint64, intptr_t, uintptr_t

NAME

int8, int16, int32, int64, uint8, uint16, uint32, uint64, intptr_t, uintptr_t

SYNOPSIS

These data types have host-dependent definitions. Use the api-help Simics command line command to get their exact definition.

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.

lang_void

NAME

lang_void

SYNOPSIS

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 void * 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

logical_address_t, physical_address_t, generic_address_t, linear_address_t

NAME

logical_address_t, physical_address_t, generic_address_t, linear_address_t

SYNOPSIS

These data types are target architecture independent, and always large enough to hold 64-bit addresses.

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.

map_info_t

NAME

map_info_t, swap_mode_t

SYNOPSIS

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;

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.

map_list_t

NAME

map_list_t, map_type_t

SYNOPSIS

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;

DESCRIPTION

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

map_target_t

NAME

map_target_t

SYNOPSIS

typedef struct map_target 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 SPECIFICS

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_interface_t

mem_op_type_t

NAME

mem_op_type_t

SYNOPSIS

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;

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,

notifier_type_t

NAME

notifier_type_t

SYNOPSIS

/* 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;

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

processor_mode_t

NAME

processor_mode_t

SYNOPSIS

typedef enum {
        Sim_CPU_Mode_User       = 0,
        Sim_CPU_Mode_Supervisor = 1,
        Sim_CPU_Mode_Hypervisor
} processor_mode_t;

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.

read_or_write_t

NAME

read_or_write_t

SYNOPSIS

typedef enum {
        Sim_RW_Read  = 0,
        Sim_RW_Write = 1
} read_or_write_t;

DESCRIPTION

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

set_error_t

NAME

set_error_t

SYNOPSIS

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;

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.

simtime_t, cycles_t, pc_step_t, nano_secs_t

NAME

simtime_t, cycles_t, pc_step_t, nano_secs_t

SYNOPSIS

typedef int64 simtime_t;

typedef simtime_t cycles_t;

typedef simtime_t pc_step_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, and 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⁻⁹ seconds).

translation_t

NAME

translation_t

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.

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;

SEE ALSO

SIM_map_target_flush, SIM_translation_changed

3.2.2 Model Specific Data Types

arm_device_type_t

NAME

arm_device_type_t

SYNOPSIS

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;

DESCRIPTION

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

arm_mem_attr_t

NAME

arm_mem_attr_t

SYNOPSIS

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;

DESCRIPTION

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

arm_mem_hint_t

NAME

arm_mem_hint_t

SYNOPSIS

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;

DESCRIPTION

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

arm_mem_instr_origin_t

NAME

arm_mem_instr_origin_t

SYNOPSIS

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,

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

DESCRIPTION

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

arm_mem_transient_t

NAME

arm_mem_transient_t

SYNOPSIS

typedef enum {
        Arm_Transient_True,
        Arm_Transient_False,
        Arm_Transient_Unknown
} arm_mem_transient_t;

DESCRIPTION

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

arm_mem_type_t

NAME

arm_mem_type_t

SYNOPSIS

typedef enum {
        Arm_MemType_Normal,
        Arm_MemType_Device
} arm_mem_type_t;

DESCRIPTION

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

arm_memory_attributes_encoding_t

NAME

arm_memory_attributes_encoding_t

SYNOPSIS

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.

arm_memory_transaction_t

NAME

arm_memory_transaction_t

SYNOPSIS

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;

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.

arm_smmu_attributes_t

NAME

arm_smmu_attributes_t

SYNOPSIS

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.

arm_translation_regime_t

NAME

arm_translation_regime_t

SYNOPSIS

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;

,

DESCRIPTION

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

i2c_status_t

NAME

i2c_status_t

SYNOPSIS

typedef enum {
        /* The ACK bit related to the operation was 0. This typically
           means that the operation was successful */
        I2C_status_success = 0,
        /* The ACK bit related to the operation was 1. This typically
           means that the operation was unsuccessful */
        I2C_status_noack = 1,
        /* The operation could not be carried out, because the link is
           currently in use by another master */
        I2C_status_bus_busy
} i2c_status_t;

DESCRIPTION

The i2c_status_t type is used to communicate the results of various operations on the I2C link. The type is an enum, with the values I2C_status_success, I2C_status_noack and I2C_status_bus_busy.

The i2c_status_t type typically represents an ACK bit; in this case I2C_status_success corresponds to 0, and I2C_status_noack corresponds to 1. In the start_response function of the i2c_master interface, the i2c_status_t parameter is additionally allowed to take the value I2C_status_bus_busy, meaning that the start failed since some other master is active using the i2c link. The value I2C_status_bus_busy is disallowed in all other function parameters in the i2c_link, i2c_slave and i2c_master interfaces.

SEE ALSO

i2c_link_interface_t, i2c_master_interface_t, i2c_slave_interface_t

interrupt_source_t

NAME

interrupt_source_t

SYNOPSIS

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;

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_t

mips_memory_transaction_t

NAME

mips_memory_transaction_t

SYNOPSIS

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;

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.

nios_memory_transaction_t

NAME

nios_memory_transaction_t

SYNOPSIS

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

pci_memory_transaction_t

NAME

pci_memory_transaction_t

SYNOPSIS

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;

DESCRIPTION

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

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

ppc_mem_instr_origin_t

NAME

ppc_mem_instr_origin_t

SYNOPSIS

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;

DESCRIPTION

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

ppc_memory_transaction_t

NAME

ppc_memory_transaction_t

SYNOPSIS

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;

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.

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

The type field specifies whether the transaction is decorated or not, and if it is, the decoration type. It will be one of:

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

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

Note that not all processors implement decorated storage.

riscv_cpu_mode_t

NAME

riscv_cpu_mode_t

SYNOPSIS

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;

DESCRIPTION

List of privilege levels of the RISC-V core.

serial_peripheral_interface_flags_t

NAME

serial_peripheral_interface_flags_t

SYNOPSIS

typedef enum serial_peripheral_interface_flags {
        SPI_Flags_CPHA = 0x1,
        SPI_Flags_CPOL = 0x2
} serial_peripheral_interface_flags_t;

DESCRIPTION

The serial_peripheral_interface_flags_t type is used to describe some properties of an SPI connection. The type is a bitfield, currently defining two values, CPOL and CPHA. If a master device connects to a slave using a CPOL/CPHA combination incompatible with the slave device, then the results of any SPI transfer are undefined.

The SPI_Flags_CPOL bit defines the polarity of the clock pin (SCK): A value of zero means that the pin is low when the bus is idle, while a value of one means that the pin is high when the bus is idle.

The SPI_Flags_CPHA bit defines the phase of the clock pin. If the CPHA and CPOL bits are equal, data bits are read on the falling edge of the SCK pin and changed on the rising edge of the pin; if the bits are not equal, data bits are read on the rising edge and changed on the falling edge of the SCK pin.

SEE ALSO

serial_peripheral_interface_slave_interface_t

usb_transfer_t

NAME

usb_transfer_t

SYNOPSIS

typedef enum {
        USB_Transfer_Completed,
        USB_Transfer_Not_Ready
} usb_transfer_completion_t;

typedef enum {
        USB_Direction_None,
        USB_Direction_In,
        USB_Direction_Out
} usb_direction_t;

typedef enum {
        USB_Status_Undef,
        USB_Status_Ack,
        USB_Status_Nak,
        USB_Status_Stall
} usb_status_t;

typedef enum {
        USB_Type_Control,
        USB_Type_Interrupt,
        USB_Type_Isochronous,
        USB_Type_Bulk
} usb_type_t;

typedef enum {
        USB_Speed_Low,
        USB_Speed_Full,
        USB_Speed_High
} usb_speed_t;

typedef struct {
        uint8  bmRequestType;
        uint8  bRequest;
        uint16 wValue;
        uint16 wIndex;
        uint16 wLength;
} usb_device_request_t;

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;

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.

x86_execution_mode_t

NAME

x86_execution_mode_t

SYNOPSIS

typedef struct x86_execution_mode {
        uint64 ac:1,
               seam:1,
               sgx:1,
               smm:1,
               vmx_root:1,
               vmx_non_root:1;
} x86_execution_mode_t;

DESCRIPTION

Processor execution mode for x86. Used by x86_execution_mode_interface_t interface.

x86_memory_transaction_t

NAME

x86_memory_transaction_t

SYNOPSIS

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 */
} x86_memory_transaction_t;

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 contains the type of the transaction. See online help for expanded output of this type: api-help x86_access_type_t

typedef enum x86_access_type {
        FOR_X86_ACCESS_TYPES(X86_ACCESS_TYPE_ENUM)
} x86_access_type_t;

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.

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;

x86_sync_instruction_type_t

NAME

x86_sync_instruction_type_t

SYNOPSIS

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

DESCRIPTION

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

xtensa_memory_transaction_t

NAME

xtensa_memory_transaction_t

SYNOPSIS

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

3.2.3 Internal Data Types

Collection of Internal Data Types

NAME

addr_type_t, byte_string_t, struct ether_addr, event_queue_type_t, icode_mode_t, image_spage_t, instruction_trace_callback_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

DESCRIPTION

These data types are exported for Simics internal use.

3.3 Device API Functions

Attribute Values

SIM_alloc_attr_dict()

NAME

SIM_alloc_attr_dict — create empty attribute dictionary

SYNOPSIS

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

SIM_alloc_attr_list()

NAME

SIM_alloc_attr_list — create uninitialized attribute list

SYNOPSIS

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

SIM_attr_copy()

NAME

SIM_attr_copy — copy attribute value

SYNOPSIS

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

SIM_attr_dict_resize()

NAME

SIM_attr_dict_resize — resize dict attribute value

SYNOPSIS

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

SIM_attr_dict_set_item()

NAME

SIM_attr_dict_set_item — set dict attribute element

SYNOPSIS

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

SIM_attr_free()

NAME

SIM_attr_free, SIM_free_attribute — free attribute

SYNOPSIS

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.

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

EXECUTION CONTEXT

All contexts (including Threaded Context)

SIM_attr_integer()

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

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⁶³,2⁶³−1]. (Converting the return value to uint64 gives the integer attribute value modulo-reduced to [0,2⁶⁴−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)

SIM_attr_is_integer()

NAME

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, SIM_attr_is_nil, SIM_attr_is_int64, SIM_attr_is_uint64 — attr_value_t type predicates

SYNOPSIS

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

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

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

SIM_attr_list_resize()

NAME

SIM_attr_list_resize — resize list attribute value

SYNOPSIS

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

SIM_attr_list_set_item()

NAME

SIM_attr_list_set_item — set list attribute element

SYNOPSIS

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

SIM_attr_scanf()

NAME

SIM_attr_scanf, SIM_ascanf — parse list attribute values

SYNOPSIS

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:

format char	argument type	element must be
i	int64 *	integer
b	int *	boolean
f	double *	floating
s	const char **	string
S	const char **	string or nil
o	conf_object_t **	object
O	conf_object_t **	object or nil
l	attr_value_t **	list
d	attr_value_t **	data
a	attr_value_t **	any except invalid

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)

SIM_make_attr_boolean()

NAME

SIM_make_attr_boolean — make boolean attribute

SYNOPSIS

FORCE_INLINE attr_value_t
SIM_make_attr_boolean(bool b);

DESCRIPTION

Returns an attr_value_t of boolean type.

EXECUTION CONTEXT

Cell Context

SIM_make_attr_data()

NAME

SIM_make_attr_data, SIM_make_attr_data_adopt — create raw data attribute

SYNOPSIS

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)

SIM_make_attr_floating()

NAME

SIM_make_attr_floating — make floating point attribute

SYNOPSIS

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

SIM_make_attr_int64()

NAME

SIM_make_attr_int64, SIM_make_attr_uint64 — make integer attribute

SYNOPSIS

FORCE_INLINE attr_value_t
SIM_make_attr_int64(int64 i);

FORCE_INLINE attr_value_t
SIM_make_attr_uint64(uint64 i);

DESCRIPTION

Returns an attr_value_t of integer type with value i.

EXECUTION CONTEXT

Cell Context

SIM_make_attr_invalid()

NAME

SIM_make_attr_invalid — make invalid attribute

SYNOPSIS

FORCE_INLINE attr_value_t
SIM_make_attr_invalid(void);

DESCRIPTION

Returns an attr_value_t of invalid type.

EXECUTION CONTEXT

Cell Context

SIM_make_attr_list()

NAME

SIM_make_attr_list, SIM_make_attr_list_vararg — make list attribute

SYNOPSIS

attr_value_t
SIM_make_attr_list(unsigned length, ...);

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

SIM_make_attr_nil()

NAME

SIM_make_attr_nil — make nil attribute

SYNOPSIS

FORCE_INLINE attr_value_t
SIM_make_attr_nil(void);

DESCRIPTION

Returns an attr_value_t of type nil.

EXECUTION CONTEXT

Cell Context

SIM_make_attr_object()

NAME

SIM_make_attr_object — make object attribute

SYNOPSIS

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

SIM_make_attr_string()

NAME

SIM_make_attr_string, SIM_make_attr_string_adopt — make string attribute

SYNOPSIS

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)

Configuration

SIM_attribute_error()

NAME

SIM_attribute_error, SIM_c_attribute_error — specify reason for attribute error

SYNOPSIS

void
SIM_attribute_error(const char *NOTNULL msg);

void
SIM_c_attribute_error(const char *NOTNULL msg, ...);

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

SIM_class_port()

NAME

SIM_class_port — check if class has specified port object

SYNOPSIS

conf_class_t *
SIM_class_port(const conf_class_t *NOTNULL cls, const char *NOTNULL name);

DESCRIPTION

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

SEE ALSO

SIM_register_port, SIM_register_simple_port

EXECUTION CONTEXT

Cell Context

SIM_copy_class()

NAME

SIM_copy_class — create a copy of an existing class

SYNOPSIS

conf_class_t *
SIM_copy_class(const char *NOTNULL name, const conf_class_t *NOTNULL src_cls,
               const char *desc);

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

SIM_create_class()

NAME

SIM_create_class — create class

SYNOPSIS

conf_class_t *
SIM_create_class(const char *NOTNULL name,
                 const class_info_t *NOTNULL class_info);

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.

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;

RETURN VALUE

Class structure, or NULL on error.

EXECUTION CONTEXT

Global Context

SEE ALSO

SIM_register_class_alias, class_info_t

SIM_ensure_partial_attr_order()

NAME

SIM_ensure_partial_attr_order — ensure attribute order

SYNOPSIS

void
SIM_ensure_partial_attr_order(conf_class_t *NOTNULL cls,
                              const char *NOTNULL before,
                              const char *NOTNULL after);

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

SIM_extend_class()

NAME

SIM_extend_class — extend class with contents from an extension class

SYNOPSIS

void
SIM_extend_class(conf_class_t *NOTNULL cls, conf_class_t *NOTNULL ext);

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 NULL 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_extension_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

SIM_extension_data()

NAME

SIM_extension_data — get class extension data

SYNOPSIS

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

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

SIM_get_class()

NAME

SIM_get_class — get class

SYNOPSIS

conf_class_t *
SIM_get_class(const char *NOTNULL name);

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

SIM_get_class_data()

NAME

SIM_get_class_data — get class data

SYNOPSIS

lang_void *
SIM_get_class_data(conf_class_t *cls);

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

SIM_get_class_name()

NAME

SIM_get_class_name — get class name

SYNOPSIS

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

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

SIM_get_interface()

NAME

SIM_get_interface, SIM_c_get_interface, SIM_get_class_interface, SIM_c_get_class_interface, SIM_get_port_interface, SIM_c_get_port_interface, SIM_get_class_port_interface, SIM_c_get_class_port_interface — get interface

SYNOPSIS

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

DESCRIPTION

Get the interface with name name from object obj. Returns NULL, 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 NULL 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

SIM_is_restoring_state()

NAME

SIM_is_restoring_state — check if state restoring phase

SYNOPSIS

bool
SIM_is_restoring_state(conf_object_t *obj);

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.

	SIM_object_is_configured	SIM_is_restoring_state
Creating object	false	false
Loading checkpoint	false	true
Loading persistent state	true	true
Loading snapshot	true	true
Manual attribute access (hot plug)	true	false

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

SEE ALSO

SIM_object_is_configured

EXECUTION CONTEXT

Cell Context

SIM_marked_for_deletion()

NAME

SIM_marked_for_deletion — is object being deleted

SYNOPSIS

bool
SIM_marked_for_deletion(const conf_object_t *NOTNULL obj);

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

SIM_object_clock()

NAME

SIM_object_clock — get object clock

SYNOPSIS

conf_object_t *
SIM_object_clock(const conf_object_t *NOTNULL obj);

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)

SIM_object_data()

NAME

SIM_object_data — get object-specific data pointer

SYNOPSIS

lang_void *
SIM_object_data(conf_object_t *NOTNULL obj);

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)

SIM_object_id()

NAME

SIM_object_id — get object identifier

SYNOPSIS

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

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

SIM_object_is_configured()

NAME

SIM_object_is_configured, SIM_set_object_configured — get/set configured status

SYNOPSIS

bool
SIM_object_is_configured(const conf_object_t *NOTNULL obj);

void
SIM_set_object_configured(conf_object_t *NOTNULL obj);

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

SIM_object_name()

NAME

SIM_object_name — get object name

SYNOPSIS

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

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

SIM_picosecond_clock()

NAME

SIM_picosecond_clock — get object picosecond clock

SYNOPSIS

conf_object_t *
SIM_picosecond_clock(conf_object_t *NOTNULL obj);

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.

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

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

SIM_register_attribute()

NAME

SIM_register_attribute, SIM_register_class_attribute, SIM_register_attribute_with_user_data, SIM_register_class_attribute_with_user_data — register attribute

SYNOPSIS

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

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:

  i	integer
  f	floating-point
  s	string
  b	boolean
  o	object
  d	data
  n	nil
  a	any type (not valid when the attribute is marked with Sim_Attr_Required)

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

    {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

SIM_register_class()

NAME

SIM_register_class — register class

SYNOPSIS

conf_class_t *
SIM_register_class(const char *NOTNULL name,
                   const class_data_t *NOTNULL class_data);

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.

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;

RETURN VALUE

Class structure, or NULL on error.

EXECUTION CONTEXT

Global Context

SEE ALSO

SIM_create_class, SIM_register_class_alias, class_data_t

SIM_register_class_alias()

NAME

SIM_register_class_alias — register class alias

SYNOPSIS

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

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

SIM_register_clock()

NAME

SIM_register_clock — register mandatory interface and attributes for clock objects

SYNOPSIS

int
SIM_register_clock(conf_class_t *NOTNULL cls,
                   const cycle_interface_t *NOTNULL iface);

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

SIM_register_compatible_interfaces()

NAME

SIM_register_compatible_interfaces — register earlier versions of interface

SYNOPSIS

void
SIM_register_compatible_interfaces(conf_class_t *NOTNULL cls,
                                   const char *NOTNULL name);

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

SIM_register_interface()

NAME

SIM_register_interface, SIM_register_port_interface — register interface

SYNOPSIS

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

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

SIM_register_port()

NAME

SIM_register_port — register port class

SYNOPSIS

void
SIM_register_port(conf_class_t *NOTNULL cls, const char *NOTNULL name,
                  conf_class_t *NOTNULL port_cls, const char *desc);

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

SIM_register_simple_port()

NAME

SIM_register_simple_port — register port

SYNOPSIS

conf_class_t *
SIM_register_simple_port(conf_class_t *NOTNULL cls, const char *NOTNULL name,
                         const char *desc);

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

SIM_register_typed_attribute()

NAME

SIM_register_typed_attribute, SIM_register_typed_class_attribute — register attribute

SYNOPSIS

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

DESCRIPTION

Note: 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 NULL 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:

  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:

    {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

SIM_require_object()

NAME

SIM_require_object — make sure an object is fully configured

SYNOPSIS

void
SIM_require_object(conf_object_t *NOTNULL obj);

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

SIM_set_attribute_default()

NAME

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

SYNOPSIS

set_error_t
SIM_set_attribute_default(conf_object_t *NOTNULL obj, const char *NOTNULL name,
                          attr_value_t val);

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

SIM_set_class_data()

NAME

SIM_set_class_data — set class data

SYNOPSIS

void
SIM_set_class_data(conf_class_t *cls, lang_void *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

Callbacks

SIM_cbdata_data()

NAME

SIM_cbdata_data — get cbdata data pointer

SYNOPSIS

FORCE_INLINE void *
SIM_cbdata_data(const cbdata_t *cbd);

DESCRIPTION

Return the data pointer of the callback data cbd.

SEE ALSO

cbdata_t

SIM_cbdata_type()

NAME

SIM_cbdata_type — get cbdata type pointer

SYNOPSIS

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

SIM_free_cbdata()

NAME

SIM_free_cbdata — free cbdata

SYNOPSIS

FORCE_INLINE void
SIM_free_cbdata(cbdata_t *cbd);

DESCRIPTION

Free the callback data cbd by calling its dealloc function.

SEE ALSO

cbdata_t

SIM_make_cbdata()

NAME

SIM_make_cbdata — create cbdata

SYNOPSIS

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

SIM_make_simple_cbdata()

NAME

SIM_make_simple_cbdata — create untyped cbdata

SYNOPSIS

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

Errors and Exceptions

SIM_clear_exception()

NAME

SIM_clear_exception — clear pending exception

SYNOPSIS

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

SIM_describe_pseudo_exception()

NAME

SIM_describe_pseudo_exception — return pseudo exception description

SYNOPSIS

const char *
SIM_describe_pseudo_exception(exception_type_t ex);

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

SIM_get_pending_exception()

NAME

SIM_get_pending_exception — get current pending exception

SYNOPSIS

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

SIM_last_error()

NAME

SIM_last_error — get error message from last frontend exception

SYNOPSIS

const char *
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

Notifiers

SIM_add_notifier()

NAME

SIM_add_notifier — add a notifier callback

SYNOPSIS

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

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

SEE ALSO

SIM_delete_notifier, SIM_register_notifier

SIM_class_has_notifier()

NAME

SIM_class_has_notifier — query class for notifier

SYNOPSIS

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

DESCRIPTION

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

EXECUTION CONTEXT

Cell Context

SIM_delete_notifier()

NAME

SIM_delete_notifier — delete notifier callback

SYNOPSIS

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

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

SIM_describe_notifier()

NAME

SIM_describe_notifier, SIM_notifier_description — set short description

SYNOPSIS

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

const char *
SIM_notifier_description(notifier_type_t type);

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

SIM_has_notifier()

NAME

SIM_has_notifier — query object for notifier

SYNOPSIS

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

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

SIM_notifier_type()

NAME

SIM_notifier_type — get notifier type

SYNOPSIS

notifier_type_t
SIM_notifier_type(const char *NOTNULL 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

SIM_notify()

NAME

SIM_notify — trigger notification callbacks

SYNOPSIS

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

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

SIM_register_notifier()

NAME

SIM_register_notifier, SIM_register_tracked_notifier — register notifier

SYNOPSIS

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

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

Global Notifiers

SIM_add_global_notifier()

NAME

SIM_add_global_notifier — add a global notifier callback

SYNOPSIS

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

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

SIM_add_global_notifier_once()

NAME

SIM_add_global_notifier_once — add a global notifier callback

SYNOPSIS

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

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

SIM_delete_global_notifier()

NAME

SIM_delete_global_notifier — delete global notifier callback

SYNOPSIS

void
SIM_delete_global_notifier(global_notifier_callback_t *handle);

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

Haps

SIM_hap_add_type()

NAME

SIM_hap_add_type — register a new hap type

SYNOPSIS

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

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:

i	an int
I	an int64 (64 bit integer)
e	an exception_type_t
o	a script specific object; i.e., void * in C and any Python object in Python
s	a string
m	a memory transaction (generic_transaction_t * in C)
c	a configuration object (conf_object_t * in C)

param_desc should be a string of space-separated parameter names, or NULL 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 NULL 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

SIM_hap_get_name()

NAME

SIM_hap_get_name — get hap name by number

SYNOPSIS

const char *
SIM_hap_get_name(hap_type_t hap);

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

SIM_hap_get_number()

NAME

SIM_hap_get_number — get hap number by name

SYNOPSIS

hap_type_t
SIM_hap_get_number(const char *NOTNULL hap);

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

SIM_hap_is_active()

NAME

SIM_hap_is_active, SIM_hap_is_active_obj, SIM_hap_is_active_obj_idx — check if hap has callbacks

SYNOPSIS

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

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

SIM_hap_occurred_always()

NAME

SIM_hap_occurred_always, SIM_c_hap_occurred_always_vararg, SIM_c_hap_occurred_always, SIM_hap_occurred, SIM_c_hap_occurred_vararg, SIM_c_hap_occurred — trigger a hap occurrence

SYNOPSIS

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_vararg(hap_type_t hap, conf_object_t *obj,
                                 int64 value, va_list ap);

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_vararg(hap_type_t hap, conf_object_t *obj,
                          int64 value, va_list ap);

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

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

SIM_hap_remove_type()

NAME

SIM_hap_remove_type — remove a hap type

SYNOPSIS

void
SIM_hap_remove_type(const char *NOTNULL hap);

DESCRIPTION

Remove a run-time defined hap type.

EXECUTION CONTEXT

Global Context

Logging

SIM_log_info()

NAME

SIM_log_info, SIM_log_spec_violation, SIM_log_unimplemented, SIM_log_error, SIM_log_critical, SIM_log_message, SIM_log_message_vararg — output log message

SYNOPSIS

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

DESCRIPTION

SIM_log_warning(dev, grp, msg)  #  Python-only

Logging functions and macros are used to emit information and error messages.

The functions above should only be used in Python. In C they are deprecated and the following preprocessor macros can be used instead.

#define SIM_LOG_INFO(level, dev, grp, ...)
#define SIM_LOG_SPEC_VIOLATION(level, dev, grp, ...)
#define SIM_LOG_UNIMPLEMENTED(level, dev, grp, ...)
#define SIM_LOG_ERROR(dev, grp, ...)
#define SIM_LOG_WARNING(dev, grp, ...)
#define SIM_LOG_CRITICAL(dev, grp, ...)
#define SIM_LOG_INFO_ONCE(level1, level2, dev, grp, ...)
#define SIM_LOG_SPEC_VIOLATION_ONCE(level1, level2, dev, grp, ...)
#define SIM_LOG_UNIMPLEMENTED_ONCE(level1, level2, dev, grp, ...)
#define SIM_LOG_WARNING_ONCE(dev, grp, ...)

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

The level parameter indicates the importance; a lower value means a more important message.

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

SIM_LOG_ERROR has no level parameter and will always emit messages.

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 use of the different functions and macros 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.

EXECUTION CONTEXT

All contexts (including Threaded Context)

SEE ALSO

SIM_log_register_groups, SIM_attribute_error

SIM_log_level()

NAME

SIM_log_level, SIM_set_log_level — set and get log level

SYNOPSIS

unsigned
SIM_log_level(const conf_object_t *NOTNULL obj);

void
SIM_set_log_level(conf_object_t *NOTNULL obj, unsigned 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

SIM_log_register_groups()

NAME

SIM_log_register_groups — register names of log groups

SYNOPSIS

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

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

Transaction Types

atom_id_t

NAME

atom_id_t

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.

atom_t

NAME

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.

transaction_completion_t

NAME

transaction_completion_t

SYNOPSIS

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.

transaction_flags_t

NAME

transaction_flags_t

SYNOPSIS

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;

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.

transaction_t

NAME

transaction_t

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.

Transactions

ATOM_flags()

NAME

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

SYNOPSIS

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.

RETURN VALUE

An atom value

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

SIM_complete_transaction()

NAME

SIM_complete_transaction — complete a deferred transaction

SYNOPSIS

void
SIM_complete_transaction(transaction_t *t, exception_type_t status);

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

SIM_defer_owned_transaction()

NAME

SIM_defer_owned_transaction — defer transaction completion using an existing transaction

SYNOPSIS

transaction_t *
SIM_defer_owned_transaction(transaction_t *t);

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

SIM_defer_transaction()

NAME

SIM_defer_transaction — defer transaction completion

SYNOPSIS

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

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

SIM_get_transaction_bytes()

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

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

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)

SIM_get_transaction_id()

NAME

SIM_get_transaction_id — obtain checkpoint ID for a deferred a transaction

SYNOPSIS

int64
SIM_get_transaction_id(transaction_t *t);

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.

SEE ALSO

SIM_reconnect_transaction

EXECUTION CONTEXT

Global Context

SIM_inspect_address_routing()

NAME

SIM_inspect_address_routing — track the route of a transaction through memory hierarchy

SYNOPSIS

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

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

SIM_inspect_breakpoints()

NAME

SIM_inspect_breakpoints — find out breakpoints that a transaction would trigger

SYNOPSIS

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

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

SIM_issue_read_transaction()

NAME

SIM_issue_read_transaction, SIM_issue_write_transaction — functions for issuing transaction_t transactions

SYNOPSIS

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

SIM_issue_transaction()

NAME

SIM_issue_transaction — issue transaction

SYNOPSIS

exception_type_t
SIM_issue_transaction(const map_target_t *NOTNULL mt,
                      transaction_t *NOTNULL t, uint64 addr);

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

SIM_monitor_transaction()

NAME

SIM_monitor_transaction, SIM_monitor_chained_transaction — monitor a transaction for deferred completion

SYNOPSIS

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

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

SIM_poll_transaction()

NAME

SIM_poll_transaction — check if a transaction has completed

SYNOPSIS

exception_type_t
SIM_poll_transaction(transaction_t *t);

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

SIM_reconnect_transaction()

NAME

SIM_reconnect_transaction — register that a deferred transaction has been restored

SYNOPSIS

void
SIM_reconnect_transaction(transaction_t *t, int64 id);

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.

SEE ALSO

SIM_get_transaction_id

EXECUTION CONTEXT

Global Context

SIM_register_python_atom_type()

NAME

SIM_register_python_atom_type — register an atom type which takes plain Python objects

SYNOPSIS

void
SIM_register_python_atom_type(const char *NOTNULL name);

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

SIM_replace_transaction()

NAME

SIM_replace_transaction — replace transaction

SYNOPSIS

void
SIM_replace_transaction(transaction_t *t_old, transaction_t *t_new);

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

SIM_set_transaction_bytes()

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

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

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

SIM_transaction_flags()

NAME

SIM_transaction_flags, SIM_transaction_is_fetch, SIM_transaction_is_write, SIM_transaction_is_read, SIM_transaction_is_inquiry — return transaction type

SYNOPSIS

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

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)

SIM_transaction_initiator()

NAME

SIM_transaction_initiator — return transaction initiator

SYNOPSIS

conf_object_t *
SIM_transaction_initiator(const transaction_t *t);

DESCRIPTION

Return the initiator of the transaction.

EXECUTION CONTEXT

All contexts (including Threaded Context)

SIM_transaction_is_deferrable()

NAME

SIM_transaction_is_deferrable — check if a transaction can be deferred for later completion

SYNOPSIS

bool
SIM_transaction_is_deferrable(const transaction_t *NOTNULL t);

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

SIM_transaction_size()

NAME

SIM_transaction_size — return transaction size

SYNOPSIS

unsigned
SIM_transaction_size(const transaction_t *NOTNULL t);

DESCRIPTION

Return the size of the transaction, in bytes.

EXECUTION CONTEXT

All contexts (including Threaded Context)

SIM_transaction_wait()

NAME

SIM_transaction_wait — wait for transaction completion

SYNOPSIS

exception_type_t
SIM_transaction_wait(transaction_t *t, exception_type_t ex);

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

Memory Transactions

SIM_arm_mem_trans_from_generic()

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

struct arm_memory_transaction *
SIM_arm_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

struct mips_memory_transaction *
SIM_mips_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

struct ppc_memory_transaction *
SIM_ppc_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

struct x86_memory_transaction *
SIM_x86_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

struct pci_memory_transaction *
SIM_pci_mem_trans_from_generic(generic_transaction_t *NOTNULL mop);

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 NULL 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 NULL on error.

EXECUTION CONTEXT

Cell Context

SIM_c_get_mem_op_value_buf()

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

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

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

SIM_c_set_mem_op_value_buf()

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

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

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

SIM_get_mem_op_page_cross()

NAME

SIM_get_mem_op_page_cross — detect transaction split

SYNOPSIS

FORCE_INLINE unsigned
SIM_get_mem_op_page_cross(const generic_transaction_t *NOTNULL mop);

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

SIM_get_mem_op_size()

NAME

SIM_get_mem_op_size — get transaction size

SYNOPSIS

FORCE_INLINE unsigned
SIM_get_mem_op_size(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Retrieve the size, in bytes, of a memory transaction.

EXECUTION CONTEXT

Cell Context

SIM_get_mem_op_type()

NAME

SIM_get_mem_op_type — get type of transaction

SYNOPSIS

FORCE_INLINE mem_op_type_t
SIM_get_mem_op_type(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

This function returns the type of the memory transaction.

SEE ALSO

generic_transaction_t, SIM_set_mem_op_type

EXECUTION CONTEXT

Cell Context

SIM_get_mem_op_type_name()

NAME

SIM_get_mem_op_type_name — get name of memory operation type

SYNOPSIS

const char *
SIM_get_mem_op_type_name(mem_op_type_t type);

DESCRIPTION

Returns a string describing type or NULL if unknown.

EXECUTION CONTEXT

Cell Context

SIM_make_mem_op_write()

NAME

SIM_make_mem_op_write, SIM_make_mem_op_read — create a memory transaction

SYNOPSIS

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

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)

SIM_mem_op_ensure_future_visibility()

NAME

SIM_mem_op_ensure_future_visibility — request transaction visibility

SYNOPSIS

FORCE_INLINE void
SIM_mem_op_ensure_future_visibility(generic_transaction_t *NOTNULL mop);

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

SIM_mem_op_is_atomic()

NAME

SIM_mem_op_is_atomic — detect transaction atomicity

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_atomic(const generic_transaction_t *NOTNULL mop);

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

SIM_mem_op_is_control()

NAME

SIM_mem_op_is_control — transaction control predicates

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_control(const generic_transaction_t *NOTNULL mop);

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

SIM_mem_op_is_data()

NAME

SIM_mem_op_is_data, SIM_mem_op_is_instruction — transaction data/instruction predicates

SYNOPSIS

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

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

SIM_mem_op_is_from_cache()

NAME

SIM_mem_op_is_from_cache — Cache initiated transaction

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_from_cache(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is sent from a cache timing model.

EXECUTION CONTEXT

Cell Context

SIM_mem_op_is_from_cpu()

NAME

SIM_mem_op_is_from_cpu — CPU initiated transaction

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_from_cpu(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is sent from a processor.

EXECUTION CONTEXT

Cell Context

SIM_mem_op_is_from_cpu_arch()

NAME

SIM_mem_op_is_from_cpu_arch — CPU initiated transaction

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_from_cpu_arch(const generic_transaction_t *NOTNULL mop,
                            ini_type_t arch);

DESCRIPTION

Checks whether mem_op is sent from a processor of a specific architecture.

EXECUTION CONTEXT

Cell Context

SIM_mem_op_is_from_device()

NAME

SIM_mem_op_is_from_device — Device initiated transaction

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_from_device(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is sent from a device.

EXECUTION CONTEXT

Cell Context

SIM_mem_op_is_prefetch()

NAME

SIM_mem_op_is_prefetch — transaction control predicates

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_is_prefetch(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is prefetch transaction.

EXECUTION CONTEXT

Cell Context

SIM_mem_op_is_read()

NAME

SIM_mem_op_is_read, SIM_mem_op_is_write — transaction read/write predicates

SYNOPSIS

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

DESCRIPTION

These functions check whether mem_op is a read or a write transaction.

EXECUTION CONTEXT

Cell Context

SIM_mem_op_may_stall()

NAME

SIM_mem_op_may_stall — detect transaction stall possibility

SYNOPSIS

FORCE_INLINE bool
SIM_mem_op_may_stall(const generic_transaction_t *NOTNULL mop);

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

SIM_set_mem_op_exception()

NAME

SIM_set_mem_op_exception, SIM_get_mem_op_exception — get/set transaction exception

SYNOPSIS

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

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

SIM_set_mem_op_initiator()

NAME

SIM_set_mem_op_initiator, SIM_get_mem_op_initiator, SIM_get_mem_op_ini_type — get/set transaction initiator

SYNOPSIS

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

DESCRIPTION

Retrieve or change the transaction initiator type and object. These two parameters must agree.

EXECUTION CONTEXT

Cell Context

SIM_set_mem_op_inquiry()

NAME

SIM_set_mem_op_inquiry, SIM_get_mem_op_inquiry — get/set transaction inquiry flag

SYNOPSIS

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

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

SIM_set_mem_op_physical_address()

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

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

DESCRIPTION

Retrieve or set the physical or virtual (logical) addresses of a memory transaction.

EXECUTION CONTEXT

Cell Context

SIM_set_mem_op_reissue()

NAME

SIM_set_mem_op_reissue — request transaction reissue

SYNOPSIS

FORCE_INLINE void
SIM_set_mem_op_reissue(generic_transaction_t *NOTNULL mop);

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

SIM_set_mem_op_type()

NAME

SIM_set_mem_op_type — set type of transaction

SYNOPSIS

FORCE_INLINE void
SIM_set_mem_op_type(generic_transaction_t *NOTNULL mop, mem_op_type_t 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

SIM_set_mem_op_user_data()

NAME

SIM_set_mem_op_user_data, SIM_get_mem_op_user_data — get/set transaction user data

SYNOPSIS

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

Device Translators