Merge pull request #261 from riscv-software-src/Different-kinds-of-op…

…tional

Different kinds of optional

arch/certificate_model/MockCertificateModel.yaml

@@ -135,7 +135,7 @@ MockCertificateModel:
           M_MODE_ENDIANESS:
             schema:
               const: little
-            # XXX Uncomment when GitHub issue #XXX is fixed.
+            #  Uncomment when GitHub issue # is fixed.
             #schema:
             #- when:
             #    version: "=1.0.0"

arch/ext/MockExt.yaml

@@ -5,8 +5,11 @@ MockExt:
   long_name: Mock Extension (for testing database)
   description: This is just for testing
   versions:
-  - version: "1.0.0"
+  - version: "0.9.9"
     state: development
+  - version: "1.0.0"
+    state: ratified
+    ratification_date: 2024-04
   params:
     MOCK_ENUM_2_INTS:
       description: foo

arch/profile_class/RVA.yaml

@@ -4,9 +4,126 @@ RVA:
     The RVA profile class targets application processors for markets
     requiring a high-degree of binary compatibility between compliant implementations.
   description: |
-    The RVA profile class is intended to be used for 64-bit application
-    processors running rich OS stacks.  Only user-mode and
-    supervisor-mode profiles are specified in this class.
+    RISC-V was designed to provide a highly modular and extensible
+    instruction set and includes a large and growing set of standard
+    extensions, where each standard extension is a bundle of
+    instruction-set features.  This is no different than other industry
+    ISAs that continue to add new ISA features.  Unlike other ISAs,
+    however, RISC-V has a broad set of contributors and implementers, and
+    also allows users to add their own custom extensions.  For some deep
+    embedded markets, highly customized processor configurations are
+    desirable for efficiency, and all software is compiled, ported, and/or
+    developed in-house by the same organization for that specific
+    processor configuration.  However, for other markets that expect a
+    substantial fraction of software to be delivered to end-customers in
+    binary form, compatibility across multiple implementations from
+    different RISC-V vendors is required.
+    
+    The RVIA ISA extension ratification process ensures that all processor
+    vendors have agreed to the specification of a standard extension if
+    present.  However, by themselves, the ISA extension specifications do
+    not guarantee that a certain set of standard extensions will be
+    present in all implementations.
+    
+    *The primary goal of the RVA profiles is to align processor vendors
+    targeting binary software markets, so software can rely on the
+    existence of a certain set of ISA features in a particular generation
+    of RISC-V implementations.*
+    
+    Alignment is not only for compatibility, but also to ensure RISC-V is
+    competitive in these markets.  The binary app markets are also
+    generally those with the most competitive performance requirements
+    (e.g., mobile, client, server).  RVIA cannot mandate the ISA features
+    that a RISC-V binary software ecosystem should use, as each ecosystem
+    will typically select the lowest-common denominator they empirically
+    observe in the deployed devices in their target markets.  But RVIA can
+    align hardware vendors to support a common set of features in each
+    generation through the RVA profiles.  Without proactive alignment
+    through RVA profiles, RISC-V will be uncompetitive, as even if a
+    particular vendor implements a certain feature, if other vendors do
+    not, then binary distributions will not generally use that feature and
+    all implementations will suffer.  While certain features may be
+    discoverable, and alternate code provided in case of presence/absence
+    of a feature, the added cost to support such options is only justified
+    for certain limited cases, and binary app markets will not support a
+    wide range of optional features, particularly for the nascent RISC-V
+    binary app ecosystems.
+    
+    To maintain alignment and increase RISC-V competitiveness over time,
+    the mandatory set of extensions must increase over time in successive
+    generations of RVA profile.  (RVA profiles may eventually have to
+    deprecate previously mandatory instructions, but that is unlikely in
+    the near future.)  Note that the RISC-V ISA will continue to evolve,
+    regardless of whether a given software ecosystem settles on a certain
+    generation of profile as the baseline for their ecosystem for many
+    years or even decades.  There are many existing binary software
+    ecosystems, which will migrate to RISC-V and evolve at different rates,
+    and more new ones will doubtless be created over the hopefully long
+    lifetime of RISC-V.  High-performance application processors require
+    considerable investment, and no single binary app ecosystem can
+    justify the development costs of these processors, especially for
+    RISC-V in its early stage of adoption.
+    
+    While the heart of the profile is the set of mandatory extensions,
+    there are several kinds of optional extension that serve important
+    roles in the profile.
+    
+    The first kind are _localized_ _options_, whose presence or use
+    necessarily differs along geo-political and/or jurisdictional
+    boundaries, with crypto being the obvious example.  These will always
+    be optional.  At least for crypto, discovery has been found to be
+    perfectly acceptable to handle this optionality on other
+    architectures, as the use of the extensions is well contained in
+    certain libraries.
+    
+    The second kind of optional extension is a _development_ _option_,
+    which represents a new ISA extension in an early part of its lifecycle
+    but which is intended to become mandatory in a later generation of the
+    RVA profile.  Processor vendors and software toolchain providers will
+    have varying development schedules, and providing an optional phase in
+    a new extension's lifecycle provides some flexibility while
+    maintaining overall alignment, and is particularly appropriate when
+    hardware or software development for the extension is complex.
+    Denoting an extension as a _development_ _option_ signals to the
+    community that development should be prioritized for such extensions
+    as they will become mandatory.
+    
+    The third kind of optional extension are _expansion_ _options_, which
+    are those that may have a large implementation cost but are not always
+    needed in a particular platform, and which can be readily handled by
+    discovery. These are also intended to remain available as expansion
+    options in future versions of the profile.  Several supervisor-mode
+    extensions fall into this category, e.g., Sv57, which has a notable
+    PPA impact over Sv48 and is not needed on smaller platforms.  Some
+    unprivileged extensions that may fall into this category are possible
+    future matrix extensions.  These have large implementation costs, and
+    use of matrix instructions can be readily supported with discovery and
+    alternate math libraries.
+    
+    The fourth kind of optional extensions are _transitory_ _options_,
+    where it is not clear if the extension will change to a mandatory,
+    localized, or expansion option, or be possibly dropped over time.
+    Cryptography provides some examples where earlier cyphers have been
+    broken and are now deprecated.  RVIA used this mechanism to enable
+    scalar crypto until vector crypto was ready.  Software security
+    features may also be in this category, with examples of deprecated
+    security features occuring in other architectures.  As another
+    example, the recent avalanche of new numeric datatypes for AI/ML may
+    eventually subside with a few survivors actually being used longer
+    term.  Denoting an option as transitory signals to the community that
+    this extension may be removed in a future profile, though the time
+    scale may span many years.
+    
+    Except for the localized options, it could be argued that other three
+    kinds of option could be left out of profiles.  Binary distributions
+    of applications willing to invest in discovery can use an optional
+    extension, and customers compiling their own applications can take
+    advantage of the feature on a particular implementation, even when
+    that system is mostly running binary distributions that ignore the new
+    extension.  However, there is value in providing guidance to align
+    hardware vendors and software developers around what extensions are
+    worth implementing and worth discovering, by designating only a few
+    important features as profile options and limiting their granularity.
   naming_scheme: |
     The profile class name is RVA (RISC-V Apps processor).
     A profile release name is an integer (currently 2 digits, could grow in the future).

arch/profile_release/MockProfileRelease.yaml

@@ -31,6 +31,9 @@ MockProfileRelease:
         I:
           presence: mandatory
           version: "~> 2.1"
+        Svade:
+          presence: mandatory
+          note: Adding this to get coverage when extension "conflicts" with another (Svadu in this case).
     MP-S-64:
       marketing_name: MockProfile 64-bit S-mode
       description: This is the Mock Profile Supervisor Mode description.
@@ -45,32 +48,51 @@ MockProfileRelease:
         $inherits: "#/MockProfileRelease/profiles/MP-U-64/extensions"
         A:
           presence: mandatory
+          note: This should be listed as mandatory in MP-S-64 and optional in MP-U-64.
         S:
-          presence: mandatory
-          version: "= 1.11"
+          presence: 
+            optional: localized
+          version: "= 1.12"
         Zifencei:
-          presence: mandatory
+          presence: 
+            optional: development
           version: "= 2.0"
-          note: |
-            Zifencei is mandated as it is the only standard way to support
-            instruction-cache coherence in RVA20 application processors.  A new
-            instruction-cache coherence mechanism is under development which might
-            be added as an option in the future.
+          note: 
         Zihpm:
-          presence: optional
+          presence: 
+            optional: expansion
           version: "= 2.0"
+          note: Made this a expansion option
         Sv48:
-          presence: optional
+          presence: 
+            optional: transitory
           version: "= 1.11"
+          note: Made this a transitory option
       extra_notes:
-      - presence: optional
-        text: Here's the first extra note for the optional extensions section.
       - presence: mandatory
         text: |
           Here's the first extra note for the mandatory extensions section.
           This note is multiple lines.
       - presence: optional
-        text: Here's the second extra note for the optional extensions section.
+        text: |
+          Here's the first extra note for the optional extensions section.
+          In this case, we don't differentiate between optional types.
+          This note is multiple lines.
+      - presence: 
+          optional: localized
+        text: Here's the first extra note for the localized optional extensions section.
+      - presence: 
+          optional: localized
+        text: Here's the second extra note for the localized optional extensions section.
+      - presence: 
+          optional: development
+        text: Here's the first extra note for the development optional extensions section.
+      - presence: 
+          optional: expansion
+        text: Here's the first extra note for the expansion optional extensions section.
+      - presence: 
+          optional: transitory
+        text: Here's the first extra note for the transitory optional extensions section.
       recommendations:
       - text: |
           Implementations are strongly recommended to raise illegal-instruction

backends/certificate_doc/tasks.rake

@@ -29,7 +29,8 @@ Dir.glob("#{$root}/arch/certificate_model/*.yaml") do |f|
     cert_model = arch_def.cert_model(cert_model_name)
     raise "No certificate model defined for #{cert_model_name}" if cert_model.nil?
 
-    # switch to the generated certificate arch def
+    # Switch to the generated certificate arch def
+    # XXX - Add this to profile releases
     arch_def = cert_model.to_arch_def
     cert_model = arch_def.cert_model(cert_model_name)
     cert_class = cert_model.cert_class