Create provisional and compat features around the vect type

Makefile

@@ -205,6 +205,10 @@ generated-md-1.2/grammar.md generated-md-1.4/grammar.md: generated-md-1.%/gramma
 	$(PYTHON) $(SRC_BASE)/$(TARGET)/grammar_to_md.py $(PYTHONPATH) $< $@
 generated-md-1.2/messages.md generated-md-1.4/messages.md: generated-md-%/messages.md: $(SRC_BASE)/$(TARGET)/messages_to_md.py $(DMLC_BIN)
 	$(PYTHON) $< $(PYTHONPATH) $* $@
+generated-md-1.2/deprecations-auto.md: $(SRC_BASE)/$(TARGET)/deprecations_to_md.py $(SRC_BASE)/$(TARGET)/doc/1.2/deprecations-header.md $(DMLC_BIN) | generated-md-1.2
+	$(PYTHON) $< $(PYTHONPATH) $(word 2,$^) $@
+generated-md-1.2/provisional-auto.md: $(SRC_BASE)/$(TARGET)/provisional_to_md.py $(SRC_BASE)/$(TARGET)/doc/1.2/provisional-header.md $(DMLC_BIN) | generated-md-1.2
+	$(PYTHON) $< $(PYTHONPATH) $(word 2,$^) $@ 1.2
 
 DOC_SRC_DIR_14 := $(SRC_BASE)/$(TARGET)/doc/1.4
 DOC_FILES_14 := $(wildcard $(DOC_SRC_DIR_14)/*.md) $(DOC_SRC_DIR_14)/toc.json
@@ -218,7 +222,7 @@ generated-md-1.4/changes-auto.md: $(SRC_BASE)/$(TARGET)/porting_to_md.py $(DMLC_
 generated-md-1.4/deprecations-auto.md: $(SRC_BASE)/$(TARGET)/deprecations_to_md.py $(SRC_BASE)/$(TARGET)/doc/1.4/deprecations-header.md $(DMLC_BIN) | generated-md-1.4
 	$(PYTHON) $< $(PYTHONPATH) $(word 2,$^) $@
 generated-md-1.4/provisional-auto.md: $(SRC_BASE)/$(TARGET)/provisional_to_md.py $(SRC_BASE)/$(TARGET)/doc/1.4/provisional-header.md $(DMLC_BIN) | generated-md-1.4
-	$(PYTHON) $< $(PYTHONPATH) $(word 2,$^) $@
+	$(PYTHON) $< $(PYTHONPATH) $(word 2,$^) $@ 1.4
 
 generated-md-1.4/dml-builtins.md generated-md-1.4/utility.md: generated-md-1.4/%.md: $(DMLC_DIR)/lib/1.4/%.dml
 	$(PYTHON) $(DMLC_DIR)/dmlcomments_to_md.py $< $@
@@ -236,7 +240,7 @@ DOC_FILES_12 := $(wildcard $(DOC_SRC_DIR_12)/*.md) $(DOC_SRC_DIR_12)/toc.json
 DOC_DEST_12 := $(SIMICS_PROJECT)/$(HOST_TYPE)/doc/html/dml-1.2-reference-manual
 DOC_MARKER_12 := $(DOC_DEST_12)/filelist.json
 
-GENERATED_MD_FILES_12 = $(addprefix generated-md-1.2/,grammar.md messages.md)
+GENERATED_MD_FILES_12 = $(addprefix generated-md-1.2/,grammar.md messages.md deprecations-auto.md provisional-auto.md)
 DOC_FILES_12 += $(GENERATED_MD_FILES_12)
 $(GENERATED_MD_FILES_12): | generated-md-1.2
 $(DOC_MARKER_12): $(DOC_FILES_12)

RELEASENOTES.md

@@ -232,3 +232,14 @@
   non-constant expressions (fixes SIMICS-13113).
 - `release 6 6363`
 - `release 7 7064`
+- `note 6` A new provisional feature `simics_util_vect` has been added. When
+  `provisional simics_util_vect;` appears in the top of a DML file, DMLC will
+  no longer print warnings when the `vect` syntax is used in that file.
+- `note 6` A new compatibility feature `simics_util_vect_without_provisional` has been
+  created. In files without a `provisional simics_util_vect;` declaration, the `vect`
+  syntax is only permitted when this feature is enabled. This feature will be
+  disabled in Simics API versions \> 7, where all uses of `vect` instead require
+  explicit `provisional` declarations.
+- `note 6` The rarely used `_warning` statement has been deprecated, through
+  the introduction of a new compatibility feature `warning_statement`.
+  Warning statements will be illegal when Simics API 8 or newer is used.

T_experimental_vect_disabled.dml

@@ -0,0 +1,13 @@
+/*
+  © 2024 Intel Corporation
+  SPDX-License-Identifier: MPL-2.0
+*/
+
+dml 1.4;
+
+device test;
+
+/// DMLC-FLAG --simics-api=7
+/// DMLC-FLAG --no-compat=experimental_vect
+/// ERROR EOLDVECT
+typedef int vect x;

test/1.4/errors/T_WEXPERIMENTAL.dml → T_experimental_vect_enabled.dml

@@ -1,12 +1,13 @@
 /*
-  © 2021 Intel Corporation
+  © 2024 Intel Corporation
   SPDX-License-Identifier: MPL-2.0
 */
-dml 1.4;
 
-/// COMPILE-ONLY
+dml 1.4;
 
 device test;
 
+/// COMPILE-ONLY
+/// DMLC-FLAG --simics-api=7
 /// WARNING WEXPERIMENTAL
-session int vect x;
+typedef int vect x;

dmlast.py

@@ -8,8 +8,11 @@ def create_dmlasts(dmlc_path, dmlast_path, dml_path, depfile):
     sys.path.append(str(dmlc_path))
     from dml.toplevel import produce_dmlast
     from dml.logging import ignore_warning
+    import dml.globals
+    from dml import compat
 
     ignore_warning('WEXPERIMENTAL')
+    dml.globals.enabled_compat.add(compat.warning_statement)
     dml_files_abs = list(dml_path.rglob('*.dml'))
     dml_files = [p.relative_to(dml_path) for p in dml_files_abs]
     assert dml_files

doc/1.2/deprecations-header.md

@@ -0,0 +1,72 @@
+<!--
+  © 2024 Intel Corporation
+  SPDX-License-Identifier: MPL-2.0
+-->
+
+# Managing deprecated language features
+
+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.
+
+## Deprecation mechanisms
+
+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:
+* First, while still using version N, make sure all Simics modules are updated
+  to use API version N. Modules can be migrated one by one.
+* Second, update the Simics version to N+1. This should normally have no
+  effect on DML, but may come with other challenges.
+* Third, update modules to API N+1, one by one. Simics version N+1 will always
+  offers full support for API N, so there is no rush to update, but changing
+  the API version early makes sure deprecated features are not introduced in
+  new code.
+
+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:
+* During migration to a new API version, disabling one deprecated feature at a
+  time can allow a smoother, more gradual, migration.
+* If a legacy feature is still fully supported in the latest API version, then
+  it cannot be disabled by selecting an API version, so selectively disabling
+  it is the only way to turn it off. There are reasons to do this, e.g.:
+  * Disabling a feature before it is deprecated guarantees that it is not
+    relied upon in new code, which eases later migration.
+  * Avoiding a feature that has a newer replacement makes the code base
+    cleaner and more consistent.
+  * Some legacy features can also bloat models, by exposing features in a
+    redundant manner. This can also have a negative impact on performance.
+
+## Controlling deprecation on the DML command-line
+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 <code>--no-compat=_tag_</code> 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_`.
+
+## List of deprecated features

doc/1.2/provisional-header.md

@@ -0,0 +1,29 @@
+<!--
+  © 2024 Intel Corporation
+  SPDX-License-Identifier: MPL-2.0
+-->
+
+# Provisional language features
+
+Sometimes, we may choose to extend the DML compiler with a feature before it is
+ready to be fully incorporated into the language. This can happen for different
+reasons, e.g. if the design is not fully evaluated or if the feature is
+backward incompatible. Currently, all provisional features are enabled on a
+per-file basis, by adding <code>provisional <em>feature_name</em>,
+<em>other_feature_name</em>;</code> just after the `dml 1.2;` statement.
+
+Provisional features can come in two flavours:
+
+* _Stable_ provisional features have a proven design and are
+  expected to remain pretty stable over time. Details in semantics may
+  still change between versions, but if we decide to make a
+  significant incompatible change to a supported provisional, then we
+  will create a second version of the provisional, under a new name,
+  and keep both versions in parallel for some time. It can make sense
+  to use supported provisional features in production code.
+
+* _Unstable_ provisional features are expected to undergo significant
+  incompatible changes over time, and are generally exposed to allow a
+  dedicated team of modelers to evaluate an early design. It can be used
+  to play around with, but should not be used in production code without
+  first communicating with the DML team.

doc/1.2/toc.json

@@ -19,6 +19,12 @@
         {"file": "messages.md",
          "numbering": true,
          "appendix": true},
+        {"file": "provisional-auto.md",
+         "numbering": true,
+         "appendix": true},
+        {"file": "deprecations-auto.md",
+         "numbering": true,
+         "appendix": true},
         {"file": "grammar.md",
          "numbering": true,
          "appendix": true}

lib/1.2/dml-builtins.dml

@@ -5,6 +5,7 @@
 
 dml 1.2;
 
+provisional simics_util_vect;
 bitorder le;
 
 loggroup Register_Read;
@@ -227,6 +228,8 @@ template device {
     parameter _compat_dml12_goto auto;
     parameter _compat_dml12_misc auto;
     parameter _compat_dml12_int auto;
+    parameter _compat_experimental_vect auto;
+    parameter _compat_warning_statement auto;
 
     // automatic parameters
     parameter obj                       auto;

lib/1.2/utility.dml

@@ -4,6 +4,7 @@
 */
 
 dml 1.2;
+provisional simics_util_vect;
 
 template _reg_or_field {
     parameter is_register  = ($objtype == "register");
@@ -169,9 +170,16 @@ template write_only {
             log spec_viol, log_level, Register_Read:
                 "Read from write-only register %s (returning 0).", $qname;
             log_level = 2;
-        } else {
+        } else if ($dev._compat_warning_statement) {
+            // note: this can be parsed because the .dmlast is generated with
+            // warning_statement compatibility enabled. We'll want to remove
+            // this compatibility support When API 7 goes EOL, but luckily we'll
+            // also be able to remove this statement at that time.
             _warning "The write_only template only makes sense on registers."
                 + " For fields, use read_zero instead.";
+        } else {
+            error "The write_only template only makes sense on registers."
+                + " For fields, use read_zero instead.";
         }
         value = 0;
     }
@@ -541,8 +549,18 @@ template _unimpl_base_write_warn {
             }
             $this = value;
             if (defined ($reg.limitations)
-                && $reg.limitations == "Not implemented.")
-                _warning "unimplemented template used in both field and register";
+                && $reg.limitations == "Not implemented.") {
+                if ($dev._compat_warning_statement) {
+                    // note: this can be parsed because the .dmlast is
+                    // generated with warning_statement compatibility
+                    // enabled. We'll want to remove this compatibility support
+                    // When API 7 goes EOL, but luckily we'll also be able to
+                    // remove this statement at that time.
+                    _warning "unimplemented template used in both field and register";
+                } else {
+                    error "unimplemented template used in both field and register";
+                }
+            }
         }
     }
 }

lib/1.4/dml-builtins.dml

@@ -5,6 +5,7 @@
 
 dml 1.4;
 
+provisional simics_util_vect;
 bitorder le;
 
 loggroup Register_Read;
@@ -643,6 +644,8 @@ template device {
     param _compat_dml12_goto auto;
     param _compat_dml12_misc auto;
     param _compat_dml12_int auto;
+    param _compat_experimental_vect auto;
+    param _compat_warning_statement auto;
 
     // automatic parameters
     param obj                       auto;

provisional_to_md.py

@@ -3,17 +3,20 @@
 
 import sys
 from pathlib import Path
-[path_to_dml, header, outfile] = sys.argv[1:]
+[path_to_dml, header, outfile, dml_version] = sys.argv[1:]
 sys.path.append(path_to_dml)
+dml12_only = {'1.2': True, '1.4': False}[dml_version]
 
 from dml import provisional
 from dml.env import api_versions, default_api_version
 
 with open(outfile, 'w') as f:
     f.write(Path(header).read_text())
-    stable = [feature for feature in provisional.features.values()
+    features = [feature for feature in provisional.features.values()
+                if not dml12_only or feature.dml12]
+    stable = [feature for feature in features
               if feature.stable]
-    unstable = [feature for feature in provisional.features.values()
+    unstable = [feature for feature in features
                 if not feature.stable]
     for (heading, features) in [
             ('List of stable provisional features', stable),

py/dead_dml_methods.py

@@ -113,6 +113,10 @@ def traverse_ast(ast):
 def method_locations(path):
     from dml.toplevel import parse_file, determine_version
     from dml import logging, messages
+    import dml.globals
+    from dml import compat
+    # needed to parse 1.2/utility.dml
+    dml.globals.enabled_compat.add(compat.warning_statement)
     for warning in messages.warnings:
         logging.ignore_warning(warning)
 

py/dml/compat.py

@@ -402,3 +402,30 @@ class dml12_int(CompatFeature):
     '''
     short = "Use legacy integer semantics in DML 1.2"
     last_api_version = api_6
+
+
+@feature
+class experimental_vect(CompatFeature):
+    '''<a id="experimental_vect"/> This compat feature
+    controls how DMLC reacts to uses of the `vect` syntax in files
+    where the [`simics_util_vect` provisional feature](provisional-auto.html#simics_util_vect)
+    is not enabled.
+
+    When the `experimental_vect` compatibility feature is
+    enabled, such uses are permitted, and give a `WEXPERIMENTAL`
+    warning in DML 1.4 (but no warning in DML 1.2). When
+    `experimental_vect` is disabled, DMLC forbids the `vect`
+    syntax.
+
+    '''
+    short = "Permit vect syntax without 'provisional simics_util_vect'"
+    last_api_version = api_7
+
+
+@feature
+class warning_statement(CompatFeature):
+    '''This compatibility feature enables the `_warning` statement.
+    This turned out to not be very useful, so in Simics API 8 and
+    newer the feature is no longer allowed.'''
+    short = "Allow the `_warning` statement"
+    last_api_version = api_7