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