Device Modeling Language

The Device Modeling Language (DML) is a domain-specific language for writing fast functional or transaction-level device models for virtual platforms. DML provides high-level abstractions suitable for functional device models, including constructs like register banks, registers, bit fields, event posting, interfaces between models, and logging. DML code is compiled by the DML Compiler (DMLC), producing C code with API calls tailored for a particular simulator.

Currently, the compiler supports building models for the Intel® Simics® simulator, but other back-ends may be added in the future.

Building and testing DMLC

To build DMLC, you need to have a Simics simulator installation and a Simics project set up.

Using the Public Release of the Intel Simics Simulator

If you do not already have a Simics simulator installation or access to the Simics simulator via commercial channels, install the Public Release of the Intel Simics simulator and create a Simics project (automatic in the default installation flow).

Building DMLC from a Simics project

In your Simics project, check out the DML repository into the modules/dmlc directory. At the top-level of the project, do make dmlc (or bin\make dmlc on Windows).

Testing DMLC from a Simics project

To run the unit tests provided with DMLC, run make test-dmlc or bin/test-runner --suite modules/dmlc/test from the top-level of the project.

Environment variables

The following environment variables are handy when developing DMLC. If you work regularly with a locally built DMLC, then consider setting the variables DMLC_DIR T126_JOBS, DMLC_PATHSUBST and PY_SYMLINKS in your .bashrc. Remaining variables are better to only enable when needed.

DMLC_DIR

After building DMLC, you need to set DMLC_DIR to <your-project>/<hosttype>/bin in subsequent invocations of make in order to build devices with the locally build compiler. <hosttype> is either linux64 or win64 depending on your host type.

T126_JOBS

When set, the given number of tests are run in parallel.

DMLC_PATHSUBST

The DMLC build copies a few DML library files, e.g. dml-builtins.dml, into <hosttype>/bin. When a compile error happens, error messages will normally point to this copy rather than the source. By setting DMLC_PATHSUBST to <hosttype>/bin/dml=modules/dmlc/lib, error messages will be rewritten to point to the source file instead. <hosttype> is either linux64 or win64 depending on your host type.

PY_SYMLINKS

When set to 1, make dmlc will symlink Python files instead of copying them. This has two effects: Python tracebacks will bring you to the source file in the repository, and you don't need to re-run make after editing Python files.

DMLC_DEBUG

When set to 1, unexpected exceptions in the compiler are echoed to stderr. The default is to hide tracebacks in a file dmlc-error.log.

DMLC_CC

Override the default compiler in unit tests.

DMLC_PROFILE

When set, DMLC does self-profiling and writes the profile to a .prof file.

DMLC_DUMP_INPUT_FILES

When set, DMLC emits a .tar.xz archive containing all DML source files, packaged on a form that can be compiled standalone. This is useful when a DML problem appears within a complex build environment, and you want to reproduce the problem in isolation. In the created archive, all DML files are located in the same directory (either top level or under a series of subdirectories called _), and relative imports are handled by also including symlinks in the archive. On Windows, DMLC is sometimes unable to resolve these symlinks correctly; for this reason, it is recommended that the archive is only extracted and compiled on Linux.

DMLC_GATHER_SIZE_STATISTICS

When set, DMLC outputs a file ending with -size-stats.json, which shows code generation statistics useful to reduce generated code size and increase compile speed. The file lists how much C code is generated for each DML method. The output is a list of triples [tot_size, location, num], where tot_size is the total number of bytes of C code generated from one method declaration, num is how many times C code was generated from this declaration (because it was expanded by a template), and location is the source location of the declaration.

An entry with a large tot_size and a large num can be reduced by declaring the method as shared; this should roughly divide the size by num. An entry with large tot_size with num equals 1 usually means the method is dominated by a construct like #foreach or #select, and can be reduced by breaking out the loop body into a separate method, or by otherwise reworking the loop into some other construct like foreach.

Note that the statistics only includes code directly generated from method declarations; the total code size includes much more. One megabyte of code size from method declarations usually contributes with a few seconds of compile time.

access-order of fields is not documented correctly -- SIMICS-19021

The documentation for read_register states that fields are read lsb first.
The documentation for write_register states that fields are written msb first.
The actual implementation is:

For read:

fields without read-template are retrieved all at once
fields with read-template are read lsb first

For write:

fields with write-template are written lsb first
fields without write-template are written all at once

Either documentation or implementation needs to be updated.

ecarsten added a comment - 10/Mar/22 2:01 PM:
Doc should be updated so read and write use the same direction. Implementation should be updated accordingly (looks easy).

ecarsten added a comment - 11/Mar/22 7:54 PM:
The documentation for read_register states that fields are read lsb first.

I would interpret the documentation for read as "msb first":

The implementation invokes the `read_field` method of
all sub-fields at least partially covered by `enabled_bytes`, in order
from most to least significant bit.

In any case, this is inconsistent with the implementation, which accesses LSB first. Test of current behaviour:

--- a/test/1.4/lib/T_field.dml
+++ b/test/1.4/lib/T_field.dml
@@ -37,4 +37,14 @@ bank b {
     register r4 size 4 @ 12 {
         field f @ [31:0] is use_get_val;
     }
+
+    register r5 size 4 @ 16 {
+        saved uint64 written;
+        field a[i < 4] @ [i * 8 + 7 : i * 8] is write {
+            method write(uint64 val) {
+                written <<= 8;
+                written[7:0] = val;
+            }
+        }
+    }
 }
diff --git a/test/1.4/lib/T_field.py b/test/1.4/lib/T_field.py
index 9496f1d9..3233107e 100644
--- a/test/1.4/lib/T_field.py
+++ b/test/1.4/lib/T_field.py
@@ -7,3 +7,7 @@ for name in ['r1', 'r2', 'r3', 'r4']:
     setattr(obj, 'b_' + name, 4)
     # set adds 1, get adds 2
     stest.expect_equal(getattr(obj, 'b_' + name), 7)
+
+dev_util.Register_LE(obj.bank.b, 16).write(0xaabbccdd)
+# lsb written first
+stest.expect_equal(obj.bank.b.r5_written, 0xddccbbaa)

The 1.2 behaviour is to access MSB first, as documented, so either we have to switch existing 1.4 devs from LSB-first to MSB-first, or we have to migrate every remaining 1.2 dev from MSB-first to LSB-first while migrating to 1.4 (possibly with extra pain from supporting both orders in parallel during a migration window). Both seem like similar amounts of work. Any opinions on which one is preferable?

I recall from ancient times that the 1.2 order (MSB first) happened to be practical more often than it was impractical. OTOH, most regs use little-endian byte order which makes "LSB first" feel more natural (it means that the field with lowest address is written first, if different fields cover different bytes).

intel / device-modeling-language Goto Github PK