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 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.
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 in the Python API section 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.
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 does 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.
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:
latest76In 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.
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 cannot 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.
The compile-time and run-time checks do 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.
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.
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.