Simics Migration Guide

1 Introduction

This document describes how to migrate to Simics 7 from Simics 6.

Chapter 2 describes how Simics ABI and API compatibility works, including API deprecation and removal, between minor and major versions. Other areas covered include checkpoint compatibility and build environment compatibility.

Chapter 3 gives an overview on how to migrate from an old Simics version to Simics 7.

Finally, chapter 7 lists all currently deprecated functionality and the future release when it is slated for removal.

2 Compatibility

This chapter describes the compatibility Simics provides and how to keep scripts, modules and checkpoints from previous versions of Simics working in new versions.

Simics uses semantic versioning. This is defined at http://semver.org/ and here we use the terminology defined there without further explanation.

This implies that new features can be introduced in minor versions, but in a backwards compatible way, so Simics is ABI backward compatible between minor versions. As a result, user-written modules and add-on packages can be used with a newer minor (or patch) version without recompilation.

Major versions introduce incompatible changes, which are mainly removals of previously deprecated functionality. In rare cases cases there can also be incompatible changes to existing functionality.

This implies that add-on packages compiled for a particular major version will work with the next major version as long as they do not use any deprecated functionality.

Simics maintains backward compatibility for checkpoints one major version older than the oldest of the currently supported API versions, i.e. Simics 7 supports loading checkpoints from versions 6 and 5. This assumes that the model also supports older checkpoints.

2.1 Supported Simics API

The API consists of all functions which have a SIM_ prefix, as well as any types required by those functions. There are also functions prefixed VT_ and DBG_ that are not supported and usually not documented. Such functions may for instance implement experimental functionality or, in rare cases, used to implement parts of the API, e.g. via macros. They should generally be considered internal and not used directly unless explicitly advised to.

The Simics API can be accessed from C/C++ by including one of the simics/device-api.h, simics/processor-api.h and simics/simulator-api.h header files, or in DML by including the corresponding files. There are also several additional header files defining Simics interfaces. The Simics specific memory allocation functions defined in simics/alloc.h are also supported.

Part of the Simics API is only available when programming in Python. The supported classes and functions belonging to the Simics Python API are listed in the Simics API Reference Manual.

Simics also defines some utility functions in simics/utils.h, that can be useful when programming in C/C++. These functions are currently not part of the supported Simics API.

2.2 API Deprecation

In a particular Simics major version, some features can be marked as deprecated. Deprecations are introduced only in major, not in minor, versions.

Features marked as deprecated in a particular major Simics version are supported in the subsequent major release. Using only non-deprecated features of one Simics release guarantees that an upgrade to the next major version will be without major hurdles.

Starting in Simics 7, features can also be marked as legacy in a particular major Simics version. Such features continue to exist until further notice, but are typically not supported for use in new functionality, and receive only critical bug fixes. Legacy features may be re-classified as deprecated in a future major version.

The lifespan of a SIM-prefixed API call is:

Major release A: Supported
The function is a fully supported feature. Most features remain supported for all major releases and are never deprecated.
Major releases B: Deprecated or Legacy
Documented as deprecated or legacy but still supported. Using deprecated functionality generates both compile-time and run-time warnings, which helps in migrating from deprecated API calls. When applicable, documentation in the form of release notes or porting guides points to replacement functionality. Using legacy functionality do not generate any warnings.

By default, deprecated functionality cannot be used when building modules. It is however still available by explicitly specifying an older major version as the API version, see Section 2.3.

Major release C: Removed or still Legacy
Deprecated features are removed in the subsequent major version. Legacy features remain (but can be re-classified as deprecated).

Calls with other prefixes such as VT or DBG do not necessarily follow the same process.

2.3 Compiling Modules Written for an Older Simics Version

Modules from older versions must specify what API they are written for by setting the make variable SIMICS_API. This variable must have one of the following values:

latest
Use the most recent Simics API.
7
Compile module for the 7 API.
6
Compile module for the 6 API.

In order to simplify upgrades to the future major Simics releases, it is recommended that this variable be set even when writing new modules. The recommendation is to always specify an explicit version number, not use latest.

2.3.1 Migrating Modules to the Most Recent Simics Version

Simics features are added and improved with every product release. At major releases some features may be deprecated in favor of improved implementations or solutions to the same problem.

Although the recommendation for developers is to avoid such deprecated features, they continue to work until the next major version. In these cases Simics provides both compile-time and run-time checks for use of deprecated features. The compile-time checks make deprecated parts of the API not visible during module compilation, resulting in compilation errors or warnings when such parts are being used. The compile time checks work for modules written in C or DML, but not for modules written in Python. To enable the compile-time checks, set the SIMICS_API make variable to the version of the new Simics release, for example 7:

    SIMICS_API = 7

A run-time check triggers when a feature is actually being used. Run-time checks complement compile time checks, since not all checks can be done statically. For example, static checking can not capture if passing a NULL pointer in an argument is deprecated.

The following Simics command-line options are related to warnings about deprecated features:

-wdeprecated
Issue a warning when a deprecated feature is used, or in many cases when a used feature will become deprecated in the next major release. This is equivalent to setting the sim→deprecation_level attribute to 2.
-no-wdeprecated
Never warn for use of deprecated features. This is equivalent to setting the sim→deprecation_level attribute to 0.

The default warning level, if none of the above flags is given, is for the sim→deprecation_level attribute to have the value 1. The resulting behaviour is to warn about all used features that were deprecated in the latest major release, but to issue no warnings about deprecations that will appear in the next major release.

Note: The compile-time and run-time checks does not catch all uses of deprecated parts of the API. Direct accesses to struct and enum members are not caught. Check the reference documentation to find deprecated struct and enum members. Most direct accesses to members in structs defined in the Simics API are deprecated.

2.4 Running Python Code Written for an Older Simics Version

To run a Python module, or some other Python code, that was written for an older Simics version, the old API module has to be included early in the Python source file. To run Python code written for Simics 6, add the following line:

import simics_6_api as simics

and then access old API functions as simics.SIM_old_function(), for example.

2.5 Build Environment Compatibility

Only the make variables, and makefiles described in the Model Builder User's Guide are supported. User written scripts and makefiles that rely on the internals of the Simics makefiles and other parts of the build environment may break in future Simics versions.

3 Migrating to a New Simics Version

3.1 Introduction

This chapter gives a short overview of the process of updating code and scripts from any older Simics version to the most recent one. The following chapters, on the other hand, contain version specific descriptions.

It is assumed that the migration is from Simics 6, the supported Simics version at the time of the Simics 7 release.

3.2 Step-by-step Guide

  1. First make sure that any C/C++, DML and Python modules compile with the most recent API in the version of Simics that you are migrating from. In Simics 6, set SIMICS_API to 6 in the module Makefile. If the code does not compile cleanly, consult the Migration Guide for that Simics version.
  2. Update Python modules to the most recent API in the version of Simics that you are migrating from. This can be done by importing the Simics API using a specified version:
    import simics_6_api as simics

    This will simplify the migration of code to a newer version of Simics later. Please note that you'll need to import modules and components after this.

    from simics import example

  3. Run all scripts in Simics with the -wdeprecated command line flag to the Simics binary. This will catch uses of some deprecated features that can only be detected in run time. An alternative is to set the sim→deprecation_level attribute to 2.
  4. When all modules and scripts run fine using the most recent API in the old version of Simics, it is time to migrate to Simics 7. Update the existing project to point to a Simics 7 installation or, even better, create a new project for Simics 7 development, since the old project may be needed for comparison purposes.
  5. Build all modules using the API version corresponding to the Simics version that you are migrating from. This should simply be a recompilation, since the old API version is already selected in the Makefiles and Python source files.
  6. In a few cases there are API changes that the pre-processor cannot hide. They may cause the build to fail even when an old API is selected. Use the table in chapter 7 to figure out what changes are necessary.
  7. Run all your tests and scripts to ensure that everything works in Simics 7 when using the old API. Make sure to pass -no-wdeprecated to suppress deprecation warnings in the process. Once everything works, you can start using the new version of Simics for actual work. The following steps are optional at this point, but still strongly recommended.
  8. Change the API used for modules and scripts to the most recent version, one module or script at a time. Update the code according to the following chapters.
  9. Turn off the -no-wdeprecated flag when running tests and scripts. Update any code that yields deprecation warnings according to the following chapters.

4 Migrating from Simics 6

4.1 Introduction

This chapter describes issues related to migrating to Simics 7 from Simics 6. For information about what is new in Simics 7, read the product release notes.

4.2 Launching Simics

When launching Simics 5 or 6 on Linux, the shell script file $HOME/.simics-5.sh was sourced if it existed. In Simics 7 this is no longer done.

4.3 DML migration

When migrating to Simics API 7 from Simics API 6, there are a few differences that may need to be addressed for DML code or modules. It is important to note that the migration to the Simics 7 API can be performed gradually. A single module in a large system can be migrated individually and each feature to be migrated can be migrated individually.

A comprehensive description of migration concerns and a process for migration is documented in Appendix C of the Device Modeling Language 1.4 Reference Manual. The below provide a brief list and brief description of some items to be addressed in the migration.

For migrating DML 1.2 code, please refer to Appendix B of the Device Modeling Language 1.4 Reference Manual.

5 Migrating from IO Memory to Transactions

With the io_memory interface now considered legacy in Simics 7, all new modelling should implement the transaction interface. Migrating existing code to transaction interface from io_memory is also strongly recommended. With this in mind, the challenge to port existing platforms to entirely use transactions can be significant. Therefore Simics supports automatic internal conversion from io_memory to transaction and vice versa to allow incremental migration from io_memory to transaction.

To make this work, memory accesses shall not use direct interface calls for memory accesses but shall instead use function SIM_issue_transaction. If your model has to forward a generic_transaction_t and cannot construct the transaction_t itself, then function VT_map_target_access can be used but is considered an exception and the modeller shall construct a transaction_t whenever possible.

An important concept with the new transaction framework is the type map_target_t. Simics objects, i.e. conf_object_t, that implement any of the memory/IO related interfaces can be converted to a map_target_t through function SIM_new_map_target. A map_target_t must be freed at end of use by calling function SIM_free_map_target.
See API Reference Manual Chapter 3.2 Device API Data Types for detailed information about map_target_t.

5.1 Example porting external IO Memory dependency to Transactions in DML

The device example_dev contains two connects: memory and target_dev, implementing interfaces memory_space and io_memory. It contains two methods write_to_dev32 and read_memory32. These methods create a generic_transaction_t to do a 32-bit io_memory write and read. The question now is how to port device example_dev to the new transaction framework.

dml 1.4;

device example_dev;

import "utility.dml";

connect memory {
    interface memory_space;
}
connect target_dev {
    interface io_memory;
}

method write_to_dev32(uint64 addr, uint32 value) {
    local bytes_t buf;
    buf.data = cast(&value, uint8*);
    buf.len = sizeof(value);

    local generic_transaction_t mop = SIM_make_mem_op_write(addr,
                                                            buf,
                                                            false,
                                                            dev.obj);

    local map_info_t map_info;
    dev.target_dev.io_memory.operation(&mop, map_info);
}
method read_memory32(uint64 addr) -> (uint32) {
    local uint32 value;
    local buffer_t buf;
    buf.data = cast(&value, uint8*);
    buf.len = sizeof(value);

    local generic_transaction_t mop = SIM_make_mem_op_read(addr,
                                                           buf,
                                                           false,
                                                           dev.obj);

    dev.memory.memory_space.access(&mop);
    return value;
}
  

The code below ports the device to use transactions and map targets. The model is now ported to the new transaction framework and is at the same time Memory/IO interface agnostic. Making the model possible to be used in legacy platforms where the connected target_dev implements io_memory and in new platforms the connected target_dev can be using transactions. The target_dev object can still use io_memory but can now be ported to transactions at a later point without breaking its dependency to device example_dev. This way, incremental migration of a platform away from io_memory to transactions is possible.

dml 1.4;

device example_dev;

import "utility.dml";

method validate_map_target(conf_object_t *obj) -> (bool) {
    local map_target_t *tmp = SIM_new_map_target(obj, NULL, NULL);
    if (!tmp) {
        local exception_type_t _exc = SIM_clear_exception();
        SIM_attribute_error(SIM_last_error());
        return false;
    }
    SIM_free_map_target(tmp);
    return true;
}
connect memory {
    session map_target_t *map_target;
    method validate(conf_object_t *obj) -> (bool) {
        return validate_map_target(obj);
    }
    method set(conf_object_t *obj) {
        SIM_free_map_target(this.map_target);
        default(obj);
        this.map_target = obj ? SIM_new_map_target(obj, NULL, NULL) : NULL;
    }
}
connect target_dev {
    session map_target_t *map_target;
    method validate(conf_object_t *obj) -> (bool) {
        return validate_map_target(obj);
    }
    method set(conf_object_t *obj) {
        SIM_free_map_target(this.map_target);
        default(obj);
        this.map_target = obj ? SIM_new_map_target(obj, NULL, NULL) : NULL;
    }
}

method write_to_dev32(uint64 addr, uint32 value) throws {
    if (!target_dev.map_target)
        throw;
    local uint8 buf[4];
    local atom_t atoms[5] = {
        ATOM_data(buf),
        ATOM_size(4),
        ATOM_flags(Sim_Transaction_Write),
        ATOM_initiator(dev.obj),
        ATOM_list_end(0)
    };
    local transaction_t t;
    t.atoms = atoms;
    SIM_set_transaction_value_le(&t, value);
    if (SIM_issue_transaction(target_dev.map_target, &t, addr) != Sim_PE_No_Exception)
        throw;
}
method read_memory32(uint64 addr) -> (uint32) throws {
    if (!memory.map_target)
        throw;
    local uint8 val[4];
    local atom_t atoms[4] = {
        ATOM_data(val),
        ATOM_size(4),
        ATOM_initiator(dev.obj),
        ATOM_list_end(0)
    };
    local transaction_t t;
    t.atoms = atoms;
    if (SIM_issue_transaction(memory.map_target, &t, addr) != Sim_PE_No_Exception)
        throw;
    return SIM_get_transaction_value_le(&t);
}
  

In DML there is a template map_target that can be applied to any connect that implements any of the Memory/IO interfaces defined in the bullet list above. The code can be rewritten very compactly because of the helper functions provided by the map_target template. See Device Modeling Language 1.4 Reference Manual chapter Standard Templates for a detailed description of the map_target template.

dml 1.4;

device example_dev;

import "utility.dml";

connect memory is map_target;
connect target_dev is map_target;

method write_to_dev32(uint64 addr, uint32 value) throws {
    target_dev.write(addr, 4, value);
}
method read_memory32(uint64 addr) -> (uint32) throws {
    return memory.read(addr, 4);
}
  

5.2 Porting device implementing IO Memory to Transactions

We have now covered how to remove dependency on external devices implementing io_memory interfaces by interacting with them through a map_target. Another scenario is when the device itself implements an io_memory type of interface and you cannot port that until the devices communicating with it transitions to map_target usage. In cases where the device forwards the memop to another device a partial migration is still possible.

dml 1.4;

device example_dev2;

import "utility.dml";

connect target_dev1 {
    interface io_memory;
}
connect target_dev2 {
    interface io_memory;
}
port demux is signal_port;

implement io_memory {
    method operation(generic_transaction_t *mem_op,
                     map_info_t map_info) -> (exception_type_t) {
        if (demux.signal.high)
            return target_dev1.io_memory.operation(mem_op, map_info);
        else
            return target_dev2.io_memory.operation(mem_op, map_info);
    }
}

Doing a partial migration of this code where we keep our own implementation of io_memory but remove the dependency of target_dev1 and target_dev2 to implement io_memory would require us to either convert generic_transaction_t to a transaction_t and issue a SIM_issue_transaction or to use the convenient help function VT_map_target_access which allows the user to use a generic_transaction_t together with a map_target_t. In the code below we utlize the VT_map_target_access function since it is a lot more convenient in this scenario.

dml 1.4;

device example_dev2;

import "utility.dml";

connect target_dev1 is map_target;
connect target_dev2 is map_target;

port demux is signal_port;

implement io_memory {
    method operation(generic_transaction_t *mem_op,
                     map_info_t map_info) -> (exception_type_t) {
        SIM_set_mem_op_physical_address(mem_op,
            SIM_get_mem_op_physical_address(mem_op) - map_info.base + map_info.start);

        if (demux.signal.high)
            return VT_map_target_access(target_dev1.map_target, mem_op);
        else
            return VT_map_target_access(target_dev2.map_target, mem_op);
    }
}

When a full migration can be done, the code should be rewritten as:

dml 1.4;

device example_dev2;

import "utility.dml";

connect target_dev1 is map_target;
connect target_dev2 is map_target;

port demux is signal_port {
    implement signal {
        method signal_raise() {
            default();
            SIM_translation_changed(dev.obj);
        }
        method signal_lower() {
            default();
            SIM_translation_changed(dev.obj);
        }
    }
}

implement translator {
    method translate(uint64 addr, access_t access,
                     const map_target_t *default_target) -> (translation_t)
    local translation_t t;

    if (demux.signal.high)
        t.target = target_dev1.map_target;
    else
        t.target = target_dev2.map_target;
    return t;
}

5.3 Port usage of generic_transaction_t user_data

5.3.1 IO Memory with user_data

With generic_transaction_t custom meta data could be added to IO Memory transactions through user_data.
The example device below showcases setting user_data to a generic_transaction_t through function SIM_set_mem_op_user_data.

dml 1.4;

device example_user_data_set;

typedef struct {
    int id;
} example_message_t;

connect endpoint {
    interface io_memory;
}

bank regs {
    register msg_id size 4 @ 0x0 "Message id";
    register msg_send size 8 @ 0x8 "Send message" {
        is write;
        method write(uint64 value) {
            if (endpoint.io_memory.val) {
                local bytes_t buf;
                buf.data = cast(&value, uint8*);
                buf.len = sizeof(value);

                local generic_transaction_t mop = SIM_make_mem_op_write(0,
                                                                        buf,
                                                                        false,
                                                                        dev.obj);
                local example_message_t msg = { .id = msg_id.val, ... };
                SIM_set_mem_op_user_data(&mop, &msg);
                local map_info_t map_info;
                endpoint.io_memory.operation(&mop, map_info);
            }
        }
    }
}

The example device below showcases retrieving the meta data from a generic_transaction_t through function SIM_get_mem_op_user_data.

dml 1.4;

device example_user_data_read;

typedef struct {
    int id;
} example_message_t;

implement io_memory {
    method operation(generic_transaction_t *mem_op,
                     map_info_t map_info) -> (exception_type_t) {
        local example_message_t* msg = SIM_get_mem_op_user_data(mem_op);

        if (msg != NULL)
            log info, 1: "Received message #%d", msg->id;
        return Sim_PE_No_Exception;
    }
}

5.3.2 Transactions with atoms

With generic_transaction_t a void pointer is passed between the initiator and the target making the data type unsafe. With transactions meta data can be shared through atoms which are type safe. The target shall declare its own custom atoms for the meta data. A declaration consists of a type and methods to create, retrieve and set atom values. The target can check if a specific atom is part of the transaction making the meta data exchange type safe. Custom atoms are defined in a Simics Interface Module similar to custom interfaces.

The below file example-atom.h declares an atom with the same signature as in the previous example.

#ifndef MESSAGE_ATOM_H
#define MESSAGE_ATOM_H
#include  <simics/device-api.h>

#if defined(__cplusplus)
extern "C" {
#endif

typedef struct {
        int id;
} example_message_t;

// Allow creation from Python, if required
SIM_PY_ALLOCATABLE(example_message_t);
#define ATOM_TYPE_example_message example_message_t *
SIM_CUSTOM_ATOM(example_message);

#if defined(__cplusplus)
}
#endif

#endif /* MESSAGE_ATOM_H */

File example-atom.c creates an interface module which at runtime registers the example_message atom for runtime usage.

#include "example-atom.h"

void
init_local(void)
{
        ATOM_register_example_message();
}

File example-atom.dml adds DML wrappers for the example_message atom data type and its accessors. Devices written in DML shall import this file.

dml 1.4;

header %{
#include "example-atom.h"
%}

extern typedef struct {
    int id;
} example_message_t;

// Create atom
extern atom_t ATOM_example_message(const example_message_t *msg);
// Get atom
extern const example_message_t* ATOM_get_transaction_example_message(const transaction_t *t);

The code below is class example_user_data_set ported to instead use an atom for sending the message.

dml 1.4;

device example_user_data_set;

import "utility.dml";
import "example-atom.dml";

connect endpoint is map_target;

bank regs {
    register msg_id size 4 @ 0x0 "Message id";
    register msg_send size 8 @ 0x8 "Send message" {
        is write;
        method write(uint64 value) {
            local buffer_t buf;
            buf.data = cast(&value, uint8*);
            buf.len = sizeof(value);
            local example_message_t msg = { .id = msg_id.val, ... };

            local atom_t atoms[6] = {
                ATOM_initiator(dev.obj),
                ATOM_data(buf.data),
                ATOM_size(buf.len),
                ATOM_flags(Sim_Transaction_Write),
                ATOM_example_message(&msg),
                ATOM_list_end(0)
            };
            local transaction_t t;
            t.atoms = atoms;
            endpoint.issue(&t, 0);
        }
    }
}


The code below is class example_user_data_read ported to instead use an atom for the message.

dml 1.4;

device example_user_data_read;
import "example-atom.dml";

implement transaction {
    method issue(transaction_t *t, uint64 addr) -> (exception_type_t) {
        local example_message_t* msg = ATOM_get_transaction_example_message(t);

        if (msg != NULL)
            log info, 1: "Received message #%d", msg->id;
        return Sim_PE_No_Exception;
    }
}

5.4 Devices that rely on align-size based transaction splitting

For interfaces that used the generic_transaction_t structure a memory space would split transactions into individual transactions according to the align-size setting of the memory space map entry. For transaction_t based interfaces this is no longer the case. The memory space will still apply byte swapping according to the byte swap and align-size settings, but it will no longer split the transactions.

There are some rare cases where a device might rely on the fact that transactions arrive only in chunks that are equal to or smaller than the align-size setting of its mapping. In such a case, the splitting needs to be handled by the device code or a transaction splitter needs to be inserted between the memory space and the device expecting the split transactions.

Device code handling of splitting is case specific and depends on the language used. In DML or C++, one can address oversized transactions in the function transaction_access of a bank, while in C one might do that directly in the implementation of the issue function of the transaction interface.

The easiest and a language agnostic way is inserting a transaction splitter. An example of such a splitter is the class transaction_splitter shipped with Simics. The source code can be found in src/devices/transaction-splitter. Assume that originally you had a case like shown below in Python.

# - mem refers to a memory space object
# - dev refers to an io-memory based device with a bank called "regs"

# map regs at offset 0x30, with length 0x100 and an align-size of 2
mem.map.append([0x30, dev.bank.regs, 0, 0, 0x100, None, 0, 2])

If that device was migrated from IO Memory to transaction but you still want to ensure that all transactions carry at most 2 bytes, you could insert the transaction splitter as shown below.

# - mem refers to a memory space object
# - dev refers to an io-memory based device with a bank called "regs"

# create a splitter, point it to the actual bank and configure it to split
# into two bytes
splitter = SIM_create_object('transaction_splitter',
                              'splitter',
                              target = dev.bank.regs,
                              split_size = 2)

# only change in the mapping is that it now points to the splitter object
mem.map.append([0x30, splitter, 0, 0, 0x100, None, 0, 2])

6 SystemC Library

6.1 Package 1013

The SystemC Library has been moved out of the Simics Base package to a separate package 1013 (*SystemC-Library*). Users migrating to Simics version 6.0.207 or later will need to install package 1013 to continue using SystemC.

The build process and usage of the SystemC Library remain unchanged, and no modifications are required for users' existing SystemC modules. However, since the SCL_VERSION has been updated, both the SystemC Library and the SystemC modules must be rebuilt following the migration.

7 Deprecated and Legacy Functionality

This chapter describes all functionality that is currently deprecated or legacy, and, in the former case, when it will be removed, including items removed in the current release. There are also suggestions on replacements.

7.1 Legacy in Simics 7

Functionality classified as legacy in Simics 7.

7.1.1 Product Features

Functionality Notes
The -echo command line option can be used to include command invocations as part of Simics output, which can be directed to file
The script declaration system. New code should use the target parameter framework.
The component system. New code should use the blueprint framework.
DML 1.2 New code should use DML 1.4.
Haps New code should use notifiers.
GNU make based module build system. New modules should use CMake instead.
Ports and port interfaces. New devices should use port objects.
The [obj, "name"] syntax for device connects. New devices should use port objects and regular interfaces, e.g. use syntax obj.port.name or obj.bank.name.

7.1.2 CLI

Functionality Notes
break-io bp.bank.break is a replacement in most cases
unbreak-io bp.bank.break and bp.delete is a replacement in most cases
trace-io bp.bank.trace is a replacement in most cases
trace-io-setup No replacement.
untrace-io bp.bank.trace and bp.delete is a replacement in most cases
wait-for-io-break bp.bank.wait-for is a replacement in most cases
restart-simics It only works when running Simics locally.
The ports attribute (e.g. dev.ports.HRESET.signal). Use port objects and the port or the bank sub-namespace (e.g. dev.port.HRESET.iface.signal).

7.1.3 Interfaces

Interface Notes
io_memory New code should use transaction

7.1.4 API

Functionality Replacement
SIM_register_class SIM_create_class
SIM_register_typed_attribute SIM_register_attribute or SIM_register_attribute_with_user_data
SIM_register_typed_class_attribute SIM_register_class_attribute or SIM_register_class_attribute_with_user_data
class_data_t class_info_t
dbuffer_t frags_t, bytes_t, buffer_t
SIM_register_port_interface and SIM_get_port_interface SIM_register_port together with SIM_register_interface
SIM_mem_op_is_prefetch Check if flag Sim_Transaction_Control is part of bitmap returned by function SIM_transaction_flags

7.2 To Be Removed in Simics 7

Functionality deprecated in Simics 6.

7.2.1 Product Features

Removed Replacement
The use of workspace in identifiers, file names, function names, and program arguments project
Non-hierarchical components Hierarchical component system
trace module tracer tool in Instrumentation API
Simics command line parameters: -py3k-warnings, -fast, -stall, -2, -3, -abi-version, -alt-wx, -application-mode, -dont-use-license-feature, -expire, -extra-arg, -gui-only, -license-file, -no-analyzer, -no-py3k-warnings, -workspace
Sim_Attr_Doc attribute type
Sim_Attr_Session attribute type Sim_Attr_Pseudo
.tar and .exe Simics package formats .ispm package format
packageinfo files in packages .ispm package metadata files
Reverse execution In-memory snapshots
Simics Eclipse The new standalone Simics GUI
The Simics Frontend protocol
The Simics GUI (winsome) The new standalone Simics GUI
Simics Server
The Simics binaries, simics-common, simics-gui Simics Python module
MIL-STD-1553

7.2.2 CLI

Removed Replacement
log-group -add | -sub log-group -enable | -disable
<object>.log-group -add | -sub <object>.log-group -enable |-disable
log-type -add | -sub log-type -enable | -disable
<object>.log-type -add | -sub <object>.log-type -enable | -disable
current-processor cpu or pselect
<component>.connect connect cnt0 cnt1
<component>.disconnect disconnect cnt0 cnt1
connect-components connect cnt0 cnt1
list-objects-with-interface list-objects
command-list list-commands
get-simics-search-path list-simics-search-paths
object-lock-stats print-object-lock-stats
-ipv4 flag to new-gdb-remote <prefs>→force_ipv4 or <sim>→force_ipv4
-ipv4 flag to telnet-frontend <prefs>→force_ipv4 or <sim>→force_ipv4
<textcon>.break bp.console_string.break
<graphcon>.break bp.console_string.break
<textcon>.list-break-strings bp.list
<graphcon>.list-break-strings bp.list
<textcon>.unbreak bp.delete
<graphcon>.unbreak bp.delete
<textcon>.wait-then-write bp.console_string.wait-then-write
<graphcon>.wait-then-write bp.console_string.wait-then-write
<textcon>.wait-for-string bp.console_string.wait-for
<graphcon>.wait-for-string bp.console_string.wait-for
break-log bp.log.break
unbreak-log bp.delete
wait-for-log bp.log.wait-for
cycle-break bp.cycle.break
cycle-break-absolute bp.cycle.break
wait-for-cycle bp.cycle.wait-for
step-break bp.step.break
step-break-absolute bp.step.break
wait-for-step bp.step.wait-for
wait-for-time bp.time.wait-for
break bp.memory.break
tbreak bp.memory.break
wait-for-breakpoint Use bp.memory.wait-for to wait for a memory access, or use bp.wait-for-breakpoint to wait for any breakpoint created by the breakpoint manager.
unbreak bp.memory.unbreak
delete bp.delete
enable bp.enabled
disable bp.enabled
ignore bp.ignore-count
set-prefix prefix argument on bp.memory commands
set-substr substr argument on bp.memory commands
set-pattern pattern argument on bp.memory commands
list-breakpoints bp.list
trace-breakpoint bp.memory.trace
break-cr bp.control_register.break
break-cr-read bp.control_register.break
trace-cr bp.control_register.trace
trace-cr-read bp.control_register.trace
wait-for-register-read bp.control_register.wait-for
wait-for-register-write bp.control_register.wait-for
break-line bp.source_line.break
run-until-line bp.source_line.run-until
wait-for-line bp.source_line.wait-for
break-location bp.source_location.break
run-until-location bp.source_location.run-until
wait-for-location bp.source_location.wait-for
<graphcon>.break-gfx bp.gfx.break
<graphcon>.wait-for-gfx-break bp.gfx.wait-for
<graphcon>.unbreak-gfx bp.delete
<graphcon>.list-gfx-breaks bp.list
break-hap bp.hap.break
trace-hap bp.hap.trace
wait-for-hap bp.hap.wait-for
<accel_vga>.wait-for-string bp.console_string.wait-for
new-usb-disk-from-image Use new-usb-disk-comp with no flags if the command was used with the -full flag. Otherwise, no replacement is available.
create-partition commands defined for various storage models No replacement.
substring argument on log-filter and bp.log commands substr argument
-re flag on bp.log commands -regexp flag
offset argument on <image>.x address argument
trace-io-setup <prefs>→default_log_endianness
<os_awareness>.break-enter bp.os_awareness.break
<os_awareness>.break-exit bp.os_awareness.break
<os_awareness>.wait-for-activated bp.os_awareness.wait-for
<os_awareness>.wait-for-deactivated bp.os_awareness.wait-for
<os_awareness>.unbreak <bp_manager>.delete
<pci-device>.print-pci-config-regs print-device-regs bank
dev-reg-list print-device-regs
dev-reg-info print-device-reg-info
get-class-list list-classes
Parameter component of the list-objects, get-object-list, list-objects-with-interface and change-namespace commands. Parameter namespace for the commands.
<conf_object>.list-attributes, <conf_object>.list-interfaces, <conf_object>.log, <conf_object>.log-size, <conf_object>.log-setup, <conf_object>.log-type, <conf_object>.(un)break-hap, <conf_object>.(un)trace-hap, <conf_object>.wait-for-log commands. Respective global command with the object parameter.
<conf_object>.get-attribute-list, Global list-attributes command with object parameter.
<conf_object>.get-interface-list, <conf_object>.get-interface-port-list <conf_object>.list-interfaces list-interfaces
type parameter to list-objects class or iface parameters
The integer values to the queue argument of the print-event-queue command queue can be either "step" or "cycle"
set-memory-limit set-image-memory-limit
output-file-start start-command-line-capture
output-file-stop stop-command-line-capture
-z flag to checkpoint commands
get-object-list list-objects
list-namespaces list-objects
get-breakpoint-list bp.list
get-component-list list-components
enable-multimachine-accelerator enable-multithreading
disable-multimachine-accelerator disable-multithreading
-n flag to list-objects No replacement. The default behaviour is now to sort objects by name, which previously required that flag.
params.dump -yml flag to params.list
-list-all flag of list-object-references max-len argument
<break_strings>.break bp.console_string.break
<break_strings>.unbreak bp.delete
<break_strings>.list-breakpoints bp.list
<break_strings>.wait-for-string bp.console_string.wait-for
<break_strings>.wait-then-write bp.console_string.wait-then-write
<exception>.break-exception <exception>.bp-break-exception
break-exception bp.exception.break
<exception>.unbreak-exception bp.exception.delete
unbreak-exception bp.exception.delete
<exception>.trace-exception <exception>.bp-trace-exception
trace-exception bp.exception.trace
<exception>.untrace-exception bp.delete
untrace-exception bp.delete
<exception>.wait-for-exception <exception>.bp-wait-for-exception
<ide-disk>.print-partition-info <ide-disk>.print-partition-table
<simple-scsi-disk>.print-partition-info <simple-scsi-disk>.print-partition-table
<gdb-remote>.follow-context No replacement.
disable-magic-breakpoint bp.magic.break
enable-magic-breakpoint bp.magic.break
magic-breakpoint-enabled bp.magic.break
disable bp.disable
wait-for-notifier bp.notifier.wait-for
<exception>.wait-for-exception <exception>.bp-wait-for-exception
<ide-disk>.print-partition-info <ide-disk>.print-partition-table
<scsi-disk>.print-partition-info <scsi-disk>.print-partition-table

7.2.3 Classes and Attributes

Removed Replacement
arm-simple arm_simple_comp
cell-and-clocks cell_and_clocks_comp
ddr-memory-module ddr_memory_module_comp
ddr2-memory-module ddr2_memory_module_comp
ddr3-memory-module ddr3_memory_module_comp
integrator-cm1176
integrator-cm926-be
integrator-cm926
integrator-cortex-a9
integrator-cp-baseboard
integrator_cmxx6_comp
integrator_cmxx6_fpga
integrator_cp_baseboard_comp
integrator_cp_baseboard_fpga
isa-lance isa_lance_comp
isa-vga isa_vga_comp
leon2-simple leon2_simple_comp
pc-dual-serial-ports pc_dual_serial_ports_comp
pc-floppy-controller pc_floppy_controller_comp
pc-quad-serial-ports pc_quad_serial_ports_comp
pc-single-parallel-port pc_signal_parallel_port_comp
pci-accel-vga pci_accel_vga_comp
pci-am79c973 pci_am79c973_comp
pci-bcm5703c pci_bcm5703c_comp
pci-bcm5704c pci_bcm5704c_comp
pci-dec21041 pci_dec21041_comp
pci-dec21140a pci_dec21140a_comp
pci-dec21140a-dml pci_dec21140
pci-dec21143 pci_dec21143_comp
pci-i21152 pci_i21152_comp
pci-i82543gc pci_i82543gc_comp
pci-i82546bg pci_i82546bg_comp
pci-isp1040 None
pci-sym53c810 pci_sym53c810_comp
pci-sym53c875 pci_sym53c875_comp
pci-sym53c876 pci_sym53c876_comp
pci-vga pci_vga_comp
phy-mii-transceiver phy_comp
ppc-simple ppc_simple_comp
ps2-keyboard-mouse ps2_keyboard_mouse_comp
sdram-memory-module sdram_memory_module_comp
sio-w83627hf sio_w83627hf_comp
std-service-node service_node_comp
std-super-io super_io_comp
usb-disk usb_disk_comp
usb3_disk_comp usb3_disk_component
usb-tablet-comp usb_tablet_component
<component>→process_tracker The new OS Awareness system
leon2-simple leon2_simple_comp
<textcon>→telnet_use_ipv4 <prefs>→force_ipv4 or <sim>→force_ipv4
<graphcon>→vnc_use_ipv4 <prefs>→force_ipv4 or <sim>→force_ipv4
<telnet_frontend>→use_ipv4 <prefs>→force_ipv4 or <sim>→force_ipv4
<gdb-remote>→use_ipv4 <prefs>→force_ipv4 or <sim>→force_ipv4
<textcon>→telnet_port <textcon>→server and <tcp-server>→port
<textcon>→telnet_unix_socket <textcon>→server and <unix-socket-server>→socket_name
<graphcon>→vnc_port <graphcon>→server and <tcp-server>→port
<graphcon>→vnc_unix_socket <graphcon>→server and <unix-socket-server>→socket_name
<telnet_frontend>→port <telnet_frontend>→server and <tcp-server>→port
<telnet_frontend>→unix_socket <telnet_frontend>→server and <unix-socket-server>→socket_name
<gdb-remote>→listen <gdb-remote>→server and <tcp-server>→port
real-network-host real_network_host_comp
real-network-bridge real_network_bridge_comp
setting <sim>→max_worker_threads to 0 setting <sim>→use_jit_threads to false
text-console textcon
gfx-console graphcon
text_console_comp txt_console_comp
graphics_console_comp gfx_console_comp
text_graphics_console_comp gfx_console_comp
<prefs>→compress_images
osa_admin os_awareness
nfs_server
breakpoints-old bp-manager
<sim>→frontend_current_processor <sim>→current_frontend_object
<prefs>→command_log

7.2.4 Interfaces

Removed Replacement
io_memory._deprecated_map (function not called)
pool_protect direct_memory
add_map in map_demap map_simple or map_bridge
remove_map in map_demap unmap
add_default in map_demap map_simple
remove_default in map_demap unmap
gfx_console gfx_con
link_endpoint link_endpoint_v2
slave_agent follower_agent
slaver_message leader_message
break_strings break_strings_v2
rapidio_v3, rapidio_v4, rapidio_v5
recorder recorder_v2
osa_tracker_state_query.get_trackers
p2_memory_transaction x86_memory_transaction
memory_space.timing_model_operate
pci_device._deprecated_interrupt_acknowledge, pci_device._deprecated_special_cycle
pci_bus.memory_access, pci_bus.interrupt_acknowledge, pci_bus.special_cycle, pci_bus.add_default, pci_bus.remove_default
data_profiler.accum_in_range address_profile
NULL value of bank_before_read.initiator, bank_after_read.initiator, bank_before_write.initiator, bank_after_write.initiator
breakpoint_query breakpoint_query_v2
telnet_connection telnet_connection_v2 and <textcon>→server with tcp_connection_info
vnc_server vnc_server_v2 and <textcon>→server with tcp_connection_info

7.2.5 API

Removed Replacement
Hyphens (-) in attribute, interface and port names underscores (_)
Hyphens (-) in object names underscores (_)
Files commands.py and gcommands.py in module source directories Rename to module_load.py and simics_start.py. Then list them in the PYTHON_FILES make variable in the module Makefile
Python import statements on the form import mod_module_name_gcommands or import mod_module_name_commands import simmod.module_name.simics_start, import simmod.module_name.module_load
The support for .py files listed in SRC_FILES variable found in Simics module makefile. New mechanism of using Python in a Simics module should be used which involves PYTHON_FILES makefile variable usage to list .py files contained in a Simics module.
CASSERT, CASSERT_STMT STATIC_ASSERT
Sim_Hap_Simulation 0
hap_flags_t Should not be used by user code.
current_processor Python function current_cpu_obj Python function
set_current_processor Python function set_current_frontend_obj Python function
current_clock Python function current_cycle_obj Python function
assert_cpu Python function current_cpu_obj Python function
The integer_t and uinteger_t types int64 and uint64
MIN_INTEGER_T, MAX_UINTEGER_T, etc. constants INT64_MIN, UINT64_MAX etc. from <limits.h>
SIM_current_processor On a case by case basis, use available interfaces, or make sure a CPU object is passed explicitly
SIM_unload_module No replacement. SIM_unload_module has never done anything
<simics/util/data-structs.h> header file <simics/utils.h>
Implicit include of <simics/util/dbuffer.h> by using <simics/utils.h>. Include <simics/util/dbuffer.h> directly in legacy code. New code should not use this file since dbuffer_t is deprecated.
ignore field in generic_transaction_t and SIM_get_mem_op_ignore, SIM_set_mem_op_ignore functions Use translator interface to direct or sink operations
ABS_POINTER_BUTTON_LEFT, ABS_POINTER_BUTTON_RIGHT and ABS_POINTER_BUTTON_MIDDLE constants Abs_Pointer_Button_Left, Abs_Pointer_Button_Right and Abs_Pointer_Button_Middle
C++ API v1 C++ API v2
mm_malloc_low No replacement. mm_malloc_low was always only for internal use.
SIM_get_attribute_idx and SIM_set_attribute_idx on non-indexed attributes SIM_get_attribute and SIM_set_attribute to read/write the entire attribute.
SIM_init_simulator SIM_init_simulator2
SIM_register_copyright
Xterm_Break_String Console_Break_String
Vga_Break_String hap Console_Break_String hap
<simics/vtutils.h> header file <simics/utils.h>
<simics/global.h> header file
<simics/simulator/slave-time.h> header file <simics/simulator/follower-time.h>
<simics/simulator-iface/slave.h> header file <simics/simulator-iface/follower.h>
pseudo_exceptions_t enum exception_type_t enum
enums Probe_Key_Global_Sum, Probe_Key_Cell_Sum Probe_Key_Aggregates
ppc_spr_user_setter_func_t gen_spr_user_setter_func_t
ppc_spr_user_getter_func_t gen_spr_user_getter_func_t
ppc_spr_ret_t gen_spr_ret_t
ppc_spr_access_type_t gen_spr_access_type_t
Core_Global_Message hap Sim_Global_Notify_Message global notifier

7.2.6 Other

Removed Replacement
workspace-setup[.bat] script project-setup[.bat]
-workspace option -project option
SIMICS_WORKSPACE build variable SIMICS_PROJECT
WORKSPACE_SRC_DIR build variable PROJECT_SRC_DIR
DEEP_SOURCE_SEARCH build variable MODULE_DIRS
The --copy-device argument to the project-setup script --copy-module
The kdcom-proxy proxy utility No replacement
bin/debug-simics[.bat] script bin/gdb[.bat] script
gen-keymap utility
aescrypt utility
The old installer install-simics.pl The Intel Simics Package Manager
The documentation target parameter key The description target parameter key
Sourcing of $HOME/.simics-5.sh when launching on Simics on Linux None

7.3 To Be Removed in Simics 8

Functionality deprecated in Simics 7.

7.3.1 Product Features

Removed Replacement
Command line options: -config, -dstc, -gui, -gui-only, -istc, -n, -no-gui, -no-dstc, -no-istc, -no-jit, -no-stc, -obscure, -p, -python-verbose, -stc, -x Use the -e command line option. I.e: -e dstc-enable, -e dstc-disable, -e istc-enable, -e istc-disable, -e disable-jit, -e enable-jit
Old log file related command line parameters: -log, -no-log, -log-file New command line parameter --log-file
Old warning/error command line parameters: --werror, --no-werror New command line parameters --warnings-as-errors and --deprecations-as-errors
Single dash command line parameters: -batch-mode, -core, -echo, -echofile, -help, -licence, -no-copyright, -no-settings, -no-upgrade-info, -no-wdeprecated, -no-werror, -no-win, -quiet, -script-trace, -version, -v-short, -verbose, -wdeprecated, -werror Corresponding POSIX style command line parameters: --batch-mode, --dump-core, --echo, --help, --licence, --no-copyright, --no-settings, --no-upgrade-info, --no-wdeprecated, --no-win, --quiet, --script-trace, --version, --base-version, --verbose, --wdeprecated
Direct embedding of libsimics-common in another application. Embedding of Python and Simics Python module.
Modulo calculation in fixed sized arguments will be deprecated in Simics 7. In Simics 6, a warning will be printed when module calculation is required to fit into the type. The CLI argument types int8_t, int16_t, int32_t, int64_t integer_t, sint8_t, sint16_t, sint32_t sint64_t, uint8_t, uint16_t, uint32_t uint64_t will warn once if module calculation is required when calling a command. Use only values that fit in the argument type. If required, use the unsigned* commands:
  • unsigned
  • unsigned8
  • unsigned16
  • unsigned32
  • unsigned64

7.3.2 CLI

Removed Replacement
run-command-file run-script
run-python-file run-script
script_branch.sb_wait_for_hap conf.bp.hap.cli_cmds.wait_for
script_branch.sb_wait_for_notifier conf.bp.notifier.cli_cmds.wait_for
script_branch.sb_wait_for_log conf.bp.log.cli_cmds.wait_for
script_branch.sb_wait_for_breakpoint Use conf.bp.memory.cli_cmds.wait_for to wait for a memory access, or use conf.bp.cli_cmds.wait_for_breakpoint to wait for any breakpoint created by the breakpoint manager.
script_branch.sb_wait_for_step conf.bp.step.cli_cmds.wait_for
script_branch.sb_wait_for_cycle conf.bp.cycle.cli_cmds.wait_for
script_branch.sb_wait_for_time conf.bp.time.cli_cmds.wait_for
script_branch.sb_wait_for_global_sync cli.global_cmds.wait_for_global_sync
script_branch.sb_wait_for_global_time conf.bp.time.cli_cmds.wait_for cli.global_cmds.wait_for_global_time
script_branch.sb_wait_for_register_read conf.bp.control_register.cli_cmds.wait_for with _r set to true
script_branch.sb_wait_for_register_write conf.bp.control_register.cli_cmds.wait_for with _w set to true
script_branch.sb_wait_for_simulation_started cli.global_cmds.wait_for_simulation_started
script_branch.sb_wait_for_simulation_stopped cli.global_cmds.wait_for_simulation_started
script_branch.sb_wait_for_exception conf.bp.exception.cli_cmds.wait_for
The object-name argument to the devs command The object argument
cpu-switch-time alias set-time-quantum
<cell>.cpu-switch-time alias <cell>.set-time-quantum

7.3.3 Classes and Attributes

Removed Replacement
component
component_slot
sim->gui_mode
context The interfaces virtual_data_breakpoint and virtual_instruction_breakpoint
i2c_link_v1, i2c_link i2c_link_v2
sim->fail_on_warnings sim->stop_on_error
sim->fatal_error_messages
<sim>→workspace <sim>→project
pcie-bus pcie-downstream-port

7.3.4 Interfaces

Removed Replacement
translate translator
multi_level_signal uint64_state
ieee_802_3_phy ieee_802_3_phy_v2
ieee_802_3_mac ieee_802_3_mac_v2
pci_express New code should use the new PCIe library
pci_express_hotplug New code should use the new PCIe library
pcie_adapter_compat New code should use the new PCIe library
i2c_bus i2c_slave_v2 and i2c_master_v2
i2c_bridge i2c_slave_v2 and i2c_master_v2
i2c_master i2c_slave_v2 and i2c_master_v2
i2c_slave i2c_slave_v2 and i2c_master_v2
i2c_link i2c_slave_v2 and i2c_master_v2
i2c_device i2c_slave_v2 and i2c_master_v2
temporal_state Global notifiers Sim_Global_Notify_Before_Snapshot_Restore, Sim_Global_Notify_After_Snapshot_Restore and use attributes for state.

7.3.5 API

Removed Replacement
SIM_get_all_objects SIM_object_iterator
SIM_init_environment
SIM_init_simulator2
SIM_get_init_arg_string
SIM_get_init_arg_boolean
SIM_is_loading_micro_checkpoint
Python import of component and base_component Methods in comp and component_utils modules
Sim_Class_Kind_Session Sim_Class_Kind_Pseudo
SIM_log_info in C SIM_LOG_INFO
SIM_log_error in C SIM_LOG_ERROR
SIM_log_unimplemented in C SIM_LOG_UNIMPLEMENTED
SIM_log_spec_violation in C SIM_LOG_SPEC_VIOLATION
SIM_log_critical in C SIM_LOG_CRITICAL
six Python module
HOST_64_BIT define
HOST_LITTLE_ENDIAN define
HOST_BIG_ENDIAN define
reg.FIELDNAME syntax in dev_util.AbstractRegister reg.field.FIELDNAME.read()
inquiry argument to dev_util.bank_regs .val accessor
value_to_tuple_be, value_to_tuple_le, tuple_to_value_be, tuple_to_value_le function in dev_util Standard Python functions to_bytes and from_bytes
dev_util.Memory sparse-memory
dev_util.Dev, dev_util.Iface, dev_util.iface

7.4 To Be Removed in Simics 9

Functionality deprecated in Simics 8.

7.4.1 Product Features

Removed Replacement
critical log type error log type

7.4.2 CLI

Removed Replacement
cpu-switch-time alias set-time-quantum
sync-info alias print-sync-info
cycles, picoseconds and seconds arguments to set-time-quantum count and unit arguments
min-latency argument to set-min-latency count and unit arguments

7.4.3 Classes and Attributes

Removed Replacement
accel-vga accel_vga_v2
pci_accel_vga_comp pci_accel_vga_v2_comp

7.4.4 Interfaces

Removed Replacement

7.4.5 API

Removed Replacement