diff --git a/README.md b/README.md index 7d7d0f18..49174ad1 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,7 @@ code with API calls tailored for a particular simulator. Currently, the compiler supports building models for the Intel® [Simics®](https://www.intel.com/content/www/us/en/developer/articles/tool/simics-simulator.html) -simulator, but other back-ends may be added in the -future. +simulator, but other back-ends may be added in the future. ## Building and testing DMLC @@ -50,21 +49,21 @@ regularly with a locally built DMLC, then consider setting the variables `.bashrc`. Remaining variables are better to only enable when needed. ### DMLC_DIR -After building DMLC, you need to set `DMLC_DIR` to `//bin` -in subsequent invocations of `make` in order to build devices with the locally -build compiler. `` is either `linux64` or `win64` depending on your -host type. +After building DMLC, you need to set `DMLC_DIR` to +`//bin` in subsequent invocations of `make` in order to +build devices with the locally build compiler. `` 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 -`/bin`. When a compile error happens, error messages will normally point -to this copy rather than the source. By setting `DMLC_PATHSUBST` to +`/bin`. When a compile error happens, error messages will normally +point to this copy rather than the source. By setting `DMLC_PATHSUBST` to `/bin/dml=modules/dmlc/lib`, error messages will be rewritten to point -to the source file instead. `` is either `linux64` or `win64` -depending on your host type. +to the source file instead. `` 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 diff --git a/SECURITY.md b/SECURITY.md index 713bc649..135bbbfd 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,11 @@ --> # Security Policy -We (the Device Modeling Language development team) are committed to rapidly addressing security vulnerabilities affecting our customers and providing clear guidance on the solution, impact, severity and mitigation. +We (the Device Modeling Language development team) are committed to rapidly +addressing security vulnerabilities affecting our customers and providing clear +guidance on the solution, impact, severity and mitigation. ## Reporting a Vulnerability -Please report any security vulnerabilities in this project utilizing the guidelines [here](https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html). +Please report any security vulnerabilities in this project utilizing the +guidelines +[here](https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html). diff --git a/doc/1.2/language.md b/doc/1.2/language.md index 44936652..8a3c3afd 100644 --- a/doc/1.2/language.md +++ b/doc/1.2/language.md @@ -93,7 +93,9 @@ identifiers are always prefixed by a `$` character. Constant Literals
-DML has literals for strings, characters, integers, booleans, and floating-point numbers. The integer literals can be written in decimal (`01234`), hexadecimal (`0x12af`), or binary (`0b110110`) form. +DML has literals for strings, characters, integers, booleans, and floating-point +numbers. The integer literals can be written in decimal (`01234`), hexadecimal +(`0x12af`), or binary (`0b110110`) form. Underscores (`_`) can be used between digits, or immediately following the `0b`, `0x` prefixes, in integer literals @@ -805,14 +807,14 @@ Most object types (`bank`, `register`, in *arrays*. The general form of an object array declaration is 
-type name [variable in 0..max]... extras { ... }
+type name [variable in 0..max]...
+extras { ... }
Here, each *variable* defines the name of one index in the array and -0..max defines the size of the corresponding dimension of the -array. Each *variable* defines a parameter in the object scope, and thus must -be unique. -*max* must be a compile time constant. For instance, +0..max defines the size of the corresponding dimension of +the array. Each *variable* defines a parameter in the object scope, and thus +must be unique. *max* must be a compile time constant. For instance, ``` register regs[i in 0..15] size 2 { @@ -856,12 +858,13 @@ object; multiple "`bank { ... }`" declarations are concatenated. The general form of a `register` declaration is 
-register name size n @ d is (templates) { ... }
+register name size n @ d is (templates) {
+... }
-Each of the "size n", "@ d", and "is -(templates)" sections is optional, but if present, they must -be specified in the above order. +Each of the "size n", "@ d", and +"is (templates)" sections is optional, but if present, +they must be specified in the above order. * A declaration @@ -906,7 +909,8 @@ Templates are further described in Section [x](#template-declarations). The general form of a `field` declaration is 
-field name [highbit:lowbit] is (templates) { ... }
+field name [highbit:lowbit] is (templates) {
+... }
or simply @@ -916,22 +920,24 @@ field name [bit] ... { ... } specifying a range of bits of the containing register, where the syntax -[bit] is short for [bit:bit]. -Both the "`[...]`" and the is (templates) -sections are optional; in fact, the "`[...]`" syntax is merely a -much more convenient way of defining the (required) field parameters +[bit] is short for +[bit:bit]. Both the "`[...]`" and the is +(templates) sections are optional; in fact, the "`[...]`" syntax +is merely a much more convenient way of defining the (required) field parameters `lsb` and `msb` (cf. Section [x](libraries.html#field-parameters)). * A declaration 
-  field name [high:low] is (t1,...,tN) { ... }
+field name [high:low] is
+(t1,...,tN) { ... }
is equivalent to 
-  field name [high:low] { is t1; ... is tN; ... }
+field name [high:low] { is t1; ... is
+tN; ... }
For a range of two or more bits, the first (leftmost) number always @@ -1320,12 +1326,11 @@ later version of DML. } ``` - (only one variable can be introduced per declaration). Static - variables have a similar meaning as in C, they retain value over function calls. - But note that a `static` variable in DML is per device object, it is not - globally shared between device instances. - For symmetry with C, the keyword - `auto` may be used as a synonym for `local`. +(only one variable can be introduced per declaration). Static variables have a +similar meaning as in C, they retain value over function calls. But note that a +`static` variable in DML is per device object, it is not globally shared between +device instances. For symmetry with C, the keyword `auto` may be used as a +synonym for `local`. * Plain C functions (i.e., not DML methods) can be called using normal function call syntax, as in `f(x)`. @@ -1334,7 +1339,8 @@ later version of DML. sections of the DML file, or in one or more C source code files that are compiled or linked to separately. - See sections [x](#header-declarations) and [x](#footer-declarations) for more detail on `header` and `footer`. +See sections [x](#header-declarations) and [x](#footer-declarations) for more +detail on `header` and `footer`. In either case, the functions must also be declared as `extern` in the DML source code. For example: @@ -1479,7 +1485,8 @@ not possible to specify a value to be thrown. Furthermore, in DML, ### Call Statements 
-call method(e1, ... eN) -> (d1, ... dM);
+call method(e1, ... eN) -> (d1, ...
+dM);
Calls a DML method with input arguments *`e1`*, ... @@ -1516,7 +1523,8 @@ call me; ### Inline Statements 
-inline method(e1, ... eN) -> (d1, ... dM);
+inline method(e1, ... eN) -> (d1, ...
+dM);
This is equivalent to call method(e1, ... eN) @@ -1570,7 +1578,8 @@ that e.g. have pointer parameters. ### Log Statements 
-log log-type, level, groups: format-string, e1, ..., eN;
+log log-type, level, groups: format-string,
+e1, ..., eN;
Outputs a formatted string to the Simics logging facility. The string @@ -1714,16 +1723,15 @@ The `break` statement can be used within a `foreach` loop to exit it. ### Select Statements 
-select identifier in (expr) where (cond-expr) statement else default-statement
+select identifier in (expr) where (cond-expr)
+statement else default-statement
-The `select` statement -resembles a C `switch` statement and it -is very similar to the `foreach` -statement, but executes the *`statement`* exactly once for -the first matching element in the *list* given by *`expr`*, i.e., for the first element such that -*`cond-expr`* is `true`; or if no element matches, it -executes the *`default-statement`*. +The `select` statement resembles a C `switch` statement and it is very similar +to the `foreach` statement, but executes the *`statement`* exactly once for the +first matching element in the *list* given by *`expr`*, i.e., for the first +element such that *`cond-expr`* is `true`; or if no element matches, it executes +the *`default-statement`*. If *`expr`* is a list, *and* the *`cond-expr`* only depends on compile-time constants, apart diff --git a/doc/1.2/libraries.md b/doc/1.2/libraries.md index 542365e6..a4966e2d 100644 --- a/doc/1.2/libraries.md +++ b/doc/1.2/libraries.md @@ -961,7 +961,8 @@ to `true`, otherwise to `false`. Affected by the `miss_pattern` parameter.
-read(generic\_transaction\_t \*memop, uint64 offset, uint64 size) -> (uint64 value) +read(generic\_transaction\_t \*memop, uint64 offset, uint64 size) -> (uint64 +value)
Utility method; equivalent to calling `read_access`, but does diff --git a/doc/1.2/object-model.md b/doc/1.2/object-model.md index f62f29e3..5046606f 100644 --- a/doc/1.2/object-model.md +++ b/doc/1.2/object-model.md @@ -17,11 +17,11 @@ Every object (including the device itself) can also have object, and *parameters*, which are constant-valued members that exist only during compilation. -Each object is an instance of a *class*, often simply called the -"object type"; the built-in object types are described in Section [x](#object-types). There is no way of adding user-defined classes -in DML; however, each object is in general locally modified by -adding (or overriding) members, methods and parameters - this can be -viewed as creating a local one-shot subclass for each instance. +Each object is an instance of a *class*, often simply called the "object type"; +the built-in object types are described in Section [x](#object-types). There is +no way of adding user-defined classes in DML; however, each object is in general +locally modified by adding (or overriding) members, methods and parameters - +this can be viewed as creating a local one-shot subclass for each instance. Many parts of the DML object model are automatically mapped onto the Simics *configuration object* model; most diff --git a/doc/1.4/deprecations-header.md b/doc/1.4/deprecations-header.md index b6504ae7..ebea2cad 100644 --- a/doc/1.4/deprecations-header.md +++ b/doc/1.4/deprecations-header.md @@ -50,8 +50,8 @@ each individual change in a new API version can be enabled individually, without enabling the full API version. This has the following uses: * During migration to a new API version, enabling one breaking change at a time - across the whole system makes it easier to analyze errors, because you only know that - all errors come from the same change. + across the whole system makes it easier to analyze errors, because you only + know that all errors come from the same change. * When a breaking change is first introduced, it will be disabled by default in the latest API version, and only be enabled by default when the next API version is introduced. Thus, until the next Simics major release, the @@ -83,6 +83,6 @@ title `foo-bar` corresponds to the DMLC flag `--breaking-change=foo-bar`, and when that flag is passed, the global parameter `_breaking_change_foo_bar` to `true`. -Each breaking change is also implicitly enabled when compiling with a Simics -API version above a certain threshold. The breaking changes under the section for API -_n_ are useful when migrating to API _n+1_. +Each breaking change is also implicitly enabled when compiling with a Simics API +version above a certain threshold. The breaking changes under the section for +API _n_ are useful when migrating to API _n+1_. diff --git a/doc/1.4/introduction.md b/doc/1.4/introduction.md index 691b4f30..ec8de521 100644 --- a/doc/1.4/introduction.md +++ b/doc/1.4/introduction.md @@ -208,13 +208,13 @@ register. The hierarchy is composed of the following object types: device, which can contain its own ports, banks, and attributes. ## Methods and Mutable Variables -[Methods](language.html#methods-detailed) are the DML representation of subroutines. -They may be declared as members of any object or template. Any method may have -multiple input parameters, specified similarly as C functions. Unlike C, DML -methods may have multiple return values, and the lack of a return value is -indicated through an empty list of return values rather than `void`. The -following demonstrates a method declaration with no input parameters or return -values: +[Methods](language.html#methods-detailed) are the DML representation of +subroutines. They may be declared as members of any object or template. Any +method may have multiple input parameters, specified similarly as C functions. +Unlike C, DML methods may have multiple return values, and the lack of a return +value is indicated through an empty list of return values rather than `void`. +The following demonstrates a method declaration with no input parameters or +return values: ``` method noop() -> () { @@ -285,9 +285,9 @@ done as follows: 
 template name { body }
-where *name* is the name of the template, and *body* is a set of object statements. -A template may be instantiated through the `is` object statement, which -can be used within either objects, or within templates. For example: +where *name* is the name of the template, and *body* is a set of object +statements. A template may be instantiated through the `is` object statement, +which can be used within either objects, or within templates. For example: ``` bank regs { // Instantiate a single template: templateA diff --git a/doc/1.4/language.md b/doc/1.4/language.md index 31039c43..a7437334 100644 --- a/doc/1.4/language.md +++ b/doc/1.4/language.md @@ -830,8 +830,9 @@ This requires that `ethernet_common_interface_t` is defined as a struct type with a field `frame` with the function pointer type `void (*)(conf_object_t *, const frags_t *, eth_frame_crc_status_t)`. -Definitions of all standard Simics interface types are available as DML files named like the corresponding C header files; -for instance, the `ethernet_common` interface can be imported as follows: +Definitions of all standard Simics interface types are available as DML files +named like the corresponding C header files; for instance, the `ethernet_common` +interface can be imported as follows: ``` import "simics/devs/ethernet.dml" ``` @@ -943,7 +944,8 @@ template instantiated by groups. #### Finite State Machines using groups -The following demonstrates a simple example of how a finite state machine may be implemented using templates and group objects: +The following demonstrates a simple example of how a finite state machine may be +implemented using templates and group objects: ``` // Template for finite state machines @@ -1244,21 +1246,24 @@ param name; param name: type ``` -and assigned using the `=` operator. Parameters may also be given default values using the form `param name default expr`. -For example: +and assigned using the `=` operator. Parameters may also be given default values +using the form `param name default expr`. For example: ``` param offset = 8; param byte_order default "little-endian"; ``` -A default value is overridden by an assignment (`=`). -There can be at most one assignment for each parameter. -Typically, a default value for a parameter is specified in a template, and the programmer may then choose to override it where the template is used. -See [Resolution of overrides](#resolution-of-overrides) for the resolution order when there are multiple definitions of the same parameter. +A default value is overridden by an assignment (`=`). There can be at most one +assignment for each parameter. Typically, a default value for a parameter is +specified in a template, and the programmer may then choose to override it where +the template is used. See [Resolution of overrides](#resolution-of-overrides) +for the resolution order when there are multiple definitions of the same +parameter. -A parameter that is declared without an assignment or a default value must eventually be assigned elsewhere, or the model will not compile. -This pattern is sometimes useful in templates, as in: +A parameter that is declared without an assignment or a default value must +eventually be assigned elsewhere, or the model will not compile. This pattern is +sometimes useful in templates, as in: ``` template constant is register { @@ -1291,7 +1296,9 @@ register r0 size 2 @ 0x0000 is (constant) { ### `explicit_param_decls` provisional feature -There is a shorthand syntax for combined declaration and definition of a parameter, currently enabled by the [`explicit_param_decls` provisional feature](provisional-auto.html#explicit_param_decls): +There is a shorthand syntax for combined declaration and definition of a +parameter, currently enabled by the [`explicit_param_decls` provisional +feature](provisional-auto.html#explicit_param_decls): ``` param NAME: TYPE = value; @@ -1300,12 +1307,15 @@ param NAME := value; param :default value; ``` -`explicit_param_decls` enforces that parameters are declared before they are assigned, or that the combined syntax is used. -This distinguishes between the intent to declare a new parameter, and the intent to override an existing parameter. -This distinction allows DML to capture misspelled parameter overrides as compile errors. +`explicit_param_decls` enforces that parameters are declared before they are +assigned, or that the combined syntax is used. This distinguishes between the +intent to declare a new parameter, and the intent to override an existing +parameter. This distinction allows DML to capture misspelled parameter overrides +as compile errors. -DMLC signals an error if the combined declaration and definition syntax is used to override an existing parameter. -This guards against unintentional reuse of a parameter name. An example: +DMLC signals an error if the combined declaration and definition syntax is used +to override an existing parameter. This guards against unintentional reuse of a +parameter name. An example: ``` // Included file not using explicit_param_decls @@ -1338,7 +1348,9 @@ bank foo_config { } ``` -It is recommended to enable `explicit_param_decls` in new DML source files and to use the new combined syntax when applicable to reduce the risk of bugs caused by misspelled parameters. +It is recommended to enable `explicit_param_decls` in new DML source files and +to use the new combined syntax when applicable to reduce the risk of bugs caused +by misspelled parameters. In some rare cases, you may need to declare a parameter without knowing if it's an override or a new parameter. In this case, one @@ -2148,21 +2160,16 @@ Two hook references of the same hook reference type can be compared for equality, and are considered equal when they both reference the same hook. > [!NOTE] -> Hooks have a notable shortcoming in their lack of configurability; -> for example, there is no way to configure a hook to log an error when a message -> is sent through the hook and there is no computation suspended on the hook to -> act upon the message. Proper hook configurability is planned to be added by the +> Hooks have a notable shortcoming in their lack of configurability; for +> example, there is no way to configure a hook to log an error when a message is +> sent through the hook and there is no computation suspended on the hook to act +> upon the message. Proper hook configurability is planned to be added by the > time or together with coroutines being introduced to DML. Until then, the > suggested approach is to create wrappers around usages of send_now(). > Hook reference types can be leveraged to cut down on the needed number of such -> wrappers, for example: -> 
-> method send_now_checked_no_data(hook() h) {
->     local uint64 resumed = h.send_now();
->     if (resumed == 0) {
->         log error: "Unhandled message to hook";
->     }
-> }
+> wrappers, for example: 
 method send_now_checked_no_data(hook() h) { local
+> uint64 resumed = h.send_now(); if (resumed == 0) { log error: "Unhandled
+> message to hook"; } }
 >
 > method send_now_checked_int(hook(int) h, int x) {
 >     local uint64 resumed = h.send_now(x);
@@ -2272,7 +2279,8 @@ Most object types (`bank`, `register`,
 in *arrays*. The general form of an object array declaration is
 
 
-type name[var < size]... extras { ... }
+type name[var < size]... extras
+{ ... }
 

 
 Here each [var < size] declaration defines
@@ -2317,12 +2325,13 @@ types that have special conventions.
 The general form of a `register` declaration is
 
 
-register name size n @ d is (templates) { ... }
+register name size n @ d is (templates) {
+... }
 

 
-Each of the "size n", "@ d", and "is
-(templates)" sections is optional, but if present, they must
-be specified in the above order.
+Each of the "size n", "@ d", and
+"is (templates)" sections is optional, but if present,
+they must be specified in the above order.
 
 * A declaration
 
@@ -2354,7 +2363,8 @@ The general form of a [`field` object](dml-builtins.html#field-objects)
 declaration is
 
 
-field name @ [highbit:lowbit] is (templates) { ... }
+field name @ [highbit:lowbit] is (templates)
+{ ... }
 

 
 or simply
@@ -2364,10 +2374,10 @@ field name @ [bit] ... { ... }
 

 
 specifying a range of bits of the containing register, where the syntax
-[bit] is short for [bit:bit].
-Both the "`@ [...]`" and the is (templates)
-sections are optional; in fact, the "`[...]`" syntax is merely a
-much more convenient way of defining the (required) field parameters
+[bit] is short for
+[bit:bit]. Both the "`@ [...]`" and the is
+(templates) sections are optional; in fact, the "`[...]`" syntax
+is merely a much more convenient way of defining the (required) field parameters
 `lsb` and `msb`.
 
 For a range of two or more bits, the first (leftmost) number always
@@ -3118,7 +3128,10 @@ DML deviates from the C language in a number of ways:
   ```
   However, such assignments are not allowed to be chained.
 
-* If a method can throw exceptions, or if it has more than one return argument, then the call must be a separate statement. If it has one or more return values, these must be assigned. If a method has multiple return arguments, these are enclosed in a parenthesis, as in:
+* If a method can throw exceptions, or if it has more than one return argument,
+  then the call must be a separate statement. If it has one or more return
+  values, these must be assigned. If a method has multiple return arguments,
+  these are enclosed in a parenthesis, as in:
   ```
   method divmod(int x, int y) -> (int, int) {
       return (x / y, x % y);
@@ -3223,8 +3236,9 @@ contents of variables through the following:
 
 ### Local Statements
 
-local type identifier [= initializer];
-local (type1 identifier1, type2 identifier2, ...) [= initializer];
+local type identifier [= initializer]; local
+(type1 identifier1, type2 identifier2,
+...) [= initializer];
 

 
 Declares one or multiple local variables in the current scope. The right-hand
@@ -3275,8 +3289,9 @@ but may result in more lines of code.
 
 ### Session Statements
 
-session type identifier [= initializer];
-session (type1 identifier1, type2 identifier2, ...) [= (initializer1, initializer2, ...)];
+session type identifier [= initializer]; session
+(type1 identifier1, type2 identifier2,
+...) [= (initializer1, initializer2, ...)];
 

 
 Declares one or multiple [session variables](#session-variables) in the current
@@ -3286,8 +3301,9 @@ initializing the device, and thus must be a compile-time constant.
 
 ### Saved Statements
 
-saved type identifier [= initializer];
-sabed (type1 identifier1, type2 identifier2, ...) [= (initializer1, initializer2, ...)];
+saved type identifier [= initializer]; sabed
+(type1 identifier1, type2 identifier2,
+...) [= (initializer1, initializer2, ...)];
 

 
 Declares one or multiple [saved variables](#saved-variables) in the current
@@ -3624,7 +3640,8 @@ template](dml-builtins.html#object).
 
 #### After Delay Statements
 
-after scalar unit: method(e1, ... eN);
+after scalar unit: method(e1, ...
+eN);
 

 
 In this form, the specified point in the future is given through a time delay
@@ -3655,7 +3672,8 @@ provided arguments.
 
 #### Hook-Bound After Statements
 
-after hookref[-> (msg1, ... msgN)]: method(e1, ... eM);
+after hookref[-> (msg1, ... msgN)]:
+method(e1, ... eM);
 

 
 In this form, the suspended method call is bound to the
@@ -3837,7 +3855,8 @@ response of manager, even if the manager responds synchronously.
 ### Log Statements
 
 
-log log-type[, level [ then subsequent-level ] [, groups] ]: format-string, e1, ..., eN;
+log log-type[, level [ then subsequent-level ] [,
+groups] ]: format-string, e1, ..., eN;
 

 
 Outputs a formatted string to the Simics logging facility. The string
@@ -4000,7 +4019,8 @@ The `break` statement can be used within a `#foreach` loop to exit it.
 ### Select Statements
 
 
-select identifier in (expr) where (cond-expr) statement else default-statement
+select identifier in (expr) where (cond-expr)
+statement else default-statement
 

 
 The `select` statement resembles a C `switch` statement and is very similar
@@ -4010,7 +4030,8 @@ such that *`cond-expr`* is `true`; or if no element matches, it executes the
 *`default-statement`*.
 
 
-#select identifier in (expr) where (cond-expr) statement #else default-statement
+#select identifier in (expr) where (cond-expr)
+statement #else default-statement
 

 
 In this alternative form the *`expr`* is required to be a DML
diff --git a/doc/1.4/port-dml.md b/doc/1.4/port-dml.md
index 403ebedc..4040ae91 100644
--- a/doc/1.4/port-dml.md
+++ b/doc/1.4/port-dml.md
@@ -35,7 +35,8 @@ changed. You can run the `port-dml` script to interpret and apply the
 changes:
 
 
-bin/port-dml --src file.dml --dest file-1.4.dml --tags tagfile
+bin/port-dml --src file.dml --dest file-1.4.dml --tags
+tagfile
 

 
 This will create a new DML 1.4 file