As the DML language evolves, we sometimes need to change the language in incompatible ways, which requires DML users to migrate their code. This appendix describes the mechanisms we provide to make this migration process smooth for users with large DML code bases.
In DML, deprecations can come in many forms. Deprecations in the form of removed or renamed symbols in libraries are rather easy to manage, since they give clear compile errors that often are straightforward to fix. A slightly harder type of deprecation is when some language construct or API function adjusts its semantics; this can make the model behave differently without signalling error messages. A third kind of deprecation is when DML changes how compiled models appear in Simics, typically to adjust changes in the Simics API. Such changes add another dimension because they typically affect the end-users of the DML models, rather than the authors of the models. Thus, as an author of a model you may need to synchronize your migration of such features with your end-users, to ease their transition to a new major version.
The simplest deprecation mechanism is Simics API versions: Each deprecated DML feature is associated with a Simics API version, and each Simics version supports a number of such API versions. Features reach end-of-life when moving to a new Simics major version, the features belonging to a previous Simics API version are dropped. Since Simics is currently the primary distribution channel for DML, this deprecation scheme is used for DML features as well.
This scheme allows users with a large code base to smoothly migrate from one Simics major version, N, to the next, N+1:
In addition to the API version, DML offers some compiler flags for selectively disabling deprecated features that are normally part of the used API. This has some uses, in particular:
DMLC provides a command-line flag --api-version to specify the API version to
be used for a model. When building with the standard Simics build system, this
is controlled by the SIMICS_API_VERSION variable in make, or the
SIMICS_API/MODULE_SIMICS_API variable in CMake.
DMLC also provides the --no-compat=tag flag, which disables the
feature represented by tag. The available tags are listed in the next
section. The tag also controls the name of a global boolean parameter that the
DML program may use to check whether the feature is available. The parameter's
name is the tag name preceded by _compat_.
DML 1.2-specific: the operand of the ! operator is not
type-checked; in particular, negation expressions on the form
!$reg, where reg is a register, are permitted
This compatibility feature changes the value of the obj
parameter in bank and port objects: Before Simics 6 there were
no dedicated port objects, so this parameter did not exist and if
you wrote obj inside a bank, this would resolve to
dev.obj. This feature preserves this legacy behaviour by making
the obj parameter of banks and ports resolves to dev.obj
rather than the port object.
The goto statement is deprecated; this compatibility feature
preserves it. Most goto based control structures can be reworked by
changing the goto into a throw, and its label into a catch
block; since this is sometimes nontrivial, it can be useful to disable
the goto statement separately.
When using inline to inline a method in a DML 1.2 device,
constant arguments passed in typed parameters are inlined as
constants when this feature is enabled. This can improve
compilation time in some cases, but has some unintuitive semantic
implications.
This compatibility feature affects many semantic details of
integer arithmetic. When this feature is enabled, DMLC translates
most integer operations directly into C, without compensating for
DML-specifics, like the support for odd-sized
uintNN types; this can sometimes have unexpected
consequences. The most immediate effect of disabling this feature
is that DMLC will report errors on statements like assert 0; and
while (1) { ... }, which need to change into assert false; and
while (true) { ... }, respectively. Other effects include:
Integers of non-standard sizes are represented as a native C
type, e.g. uint5 is represented as uint8, allowing it to
store numbers too large to fit in 5 bits. With modern DML
semantics, arithmetic is done on 64-bit integers and bits are
truncated if casting or storing in a smaller type.
Old code sometimes relies on this feature by comparing variables
of type int1 to the value 1. In DML 1.4, the only values of
type int1 are 0 and -1, so such code should be rewritten
to use the uint1 type. It can be a good idea to grep for
[^a-z_]int1[^0-9] and review if uint1 is a better choice.
Some operations have undefined behaviour in C, which is inherited by traditional DML 1.2. In modern DML this is well-defined, e.g., an unconditional critical error on negative shift or division by zero, and truncation on too large shift operands or signed shift overflow.
Comparison operators <, <=, ==, >=, > inherit C
semantics in traditional DML, whereas in modern DML they are
compared as integers. This sometimes makes a difference when
comparing signed and unsigned numbers; in particular, -1 != 0xffffffffffffffff consistently in modern DML, whereas with
compatibility semantics, they are consiered different only if
both are constant.
The dml12_int feature only applies to DML 1.2 files; if a DML
1.4 file is imported from a DML 1.2 file, then modern DML
semantics is still used for operations in that file.
This compatibility feature preserves a number of minor language quirks that were originally in DML 1.2, but were cleaned up in DML 1.4. When this feature is enabled, DML 1.2 will permit the following:
sizeof(typename) (see WSIZEOFTYPE)
the typeof operator on an expression that isn't an lvalue
select statements over vect types
Passing a string literal in a (non-const) char * method argument
Using the character - in the c_name parameter of interface objects
Using the c_name parameter to override interface type in
implement objects
loggroup identifiers are accessible under the same name in
generated C code
Applying the & operator on something that isn't an lvalue
(typically gives broken C code)
extern statements that do not specify a type (extern foo;)
Anonymous banks (bank { ... })
Unused templates may instantiate non-existing templates
The same symbol may be used both for a top-level object ($
scope) and a top-level symbol (non-$ scope, e.g. extern,
constant or loggroup)
The transaction interface was introduced in 6, and will
eventually replace the io_memory interface. When this feature is
enabled, the top-level parameter use_io_memory defaults to
true, causing bank objects to implement io_memory instead of
transaction by default.
This compatibility feature changes the semantics of log statements inside shared methods so that they always log on the device object, instead of the nearest enclosing configuration object like with non-shared methods. This behaviour was a bug present since the very introduction of shared methods, which has lead to plenty of script code having become reliant on it, especially in regards to how banks log. This feature preserves the bugged behaviour.
This compatibility feature makes it so the warning WLOGMIXUP is
suppressed by default. WLOGMIXUP warns about usages of a common faulty
pattern which results in broken log statements — for more
information, see the documentation of WLOGMIXUP in the
Messages section.
WLOGMIXUP is suppressed by default below Simics API version 7 in order
to avoid overwhelming users with warnings, as the faulty pattern that
WLOGMIXUP reports is very prevalent within existing code. Addressing
applications of the faulty pattern should be done before or as part of
migration to Simics API version 7.
Passing --no-compat=suppress_WLOGMIXUP to DMLC has almost the same effect
as passing --warn=WLOGMIXUP; either will cause DMLC to report the warning
even when the Simics API version in use is below 7. The only difference
between these two options is that if --no-compat=suppress_WLOGMIXUP is
used (and --warn=WLOGMIXUP is not), then WLOGMIXUP may still be
explicitly suppressed via --no-warn=WLOGMIXUP. In contrast,
--warn=WLOGMIXUP doesn't allow for WLOGMIXUP to be suppressed at
all.
In Simics 5, configuration attributes for connect,
attribute and register objects inside banks and ports were
registered on the device object, named like
bankname_attrname. Such proxy
attributes are only created When this feature is enabled.
Proxy attributes are not created for all banks and ports, in the
same manner as documented in the port_proxy_ifaces feature.
Version 5 and earlier of Simics relied on interface ports (as
registered by the SIM_register_port_interface API function) for
exposing the interfaces of ports and banks. In newer versions of
Simics, interfaces are instead exposed on separate configuration
objects. When this feature is enabled, old-style interface ports
are created as proxies to the interfaces on the respective port
objects. Such proxies are not created for all banks and ports;
e.g., banks inside groups were not allowed in Simics 5, so such
banks do not need proxies for backward compatibility.