Merge pull request #242 from riscv-software-src/238-missing-recommendations-in-profiles-and-add-extra_notes-to-replace-excluded-extensions

238 missing recommendations in profiles and add extra notes to replace excluded extensions

Author: james-ball-qualcomm

arch/crd/MockCRD-1.yaml

@@ -198,4 +198,18 @@ MockCRD-1:
         A bunch of additional requirements only that should show up for XLEN=64
       requirements:
       - name: REQ-XLEN64-001
-        description: Can avoid adding extra CSRs with `h` suffix
+        description: Can avoid adding extra CSRs with `h` suffix
+  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.
+  recommendations:
+  - text: |
+      Implementations are strongly recommended to raise illegal-instruction
+      exceptions on attempts to execute unimplemented opcodes.
+  - text: Micky should give Pluto an extra treat

arch/profile/MockProfile-1.yaml

@@ -5,9 +5,9 @@ MockProfile-1:
   mode: S
   version: "1.0"
   contributors:
-  - name: Krste Asanovic
-    email: krste@sifive.com
-    company: SiFive
+  - name: Micky Mouse
+    email: micky@disney.com
+    company: Disneyk
   extensions:
   - name: S
     presence: mandatory
@@ -25,4 +25,18 @@ MockProfile-1:
     version: "= 2.0"
   - name: Sv48
     presence: optional
-    version: "= 1.11"
+    version: "= 1.11"
+  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.
+  recommendations:
+  - text: |
+      Implementations are strongly recommended to raise illegal-instruction
+      exceptions on attempts to execute unimplemented opcodes.
+  - text: Micky should give Pluto an extra treat

arch/profile/rva20u64.yaml

@@ -103,15 +103,15 @@ rva20u64:
     note: |
       The number of counters is platform-specific.
   extra_notes:
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       The rationale to not make Q an optional extension is that
       quad-precision floating-point is unlikely to be implemented in
       hardware, and so we do not require or expect A-profile software to
       expend effort optimizing use of Q instructions in case they are
       present.
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       Zifencei is not classed as a supported option in the user-mode
       profile because it is not sufficient by itself to produce the desired
       effect in a multiprogrammed multiprocessor environment without OS
@@ -122,13 +122,14 @@ rva20u64:
       instruction-cache coherence mechanisms can be used behind the OS
       abstraction.  A separate extension is being developed for more general
       and efficient instruction cache coherence.
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       The execution environment must provide a means to synchronize writes to
       instruction memory with instruction fetches, the implementation of which
       likely relies on the Zifencei extension.
       For example, RISC-V Linux supplies the `__riscv_flush_icache` system call and
       a corresponding vDSO call.
   recommendations:
-  - Implementations are strongly recommended to raise illegal-instruction
-    exceptions on attempts to execute unimplemented opcodes.
+  - text: |
+      Implementations are strongly recommended to raise illegal-instruction
+      exceptions on attempts to execute unimplemented opcodes.

arch/profile/rva22u64.yaml

@@ -103,26 +103,26 @@ rva22u64:
     presence: optional
     version: "~> 1.0"
   extra_notes:
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       The scalar crypto extensions are expected to be superseded by
       vector crypto standards in future profiles, and the scalar extensions
       may be removed as supported options once vector crypto is present.
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       The smaller component scalar crypto extensions (Zbc, Zbkb, Zbkc,
       Zbkx, Zknd, Zkne, Zknh, Zksed, Zksh) are not provided as separate
       options in the profile.  Profile implementers should provide all of
       the instructions in a given algorithm suite as part of the Zkn or Zks
       supported options.
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       Access to the entropy source (Zkr) in a system is usually
       carefully controlled.  While the design supports unprivileged access
       to the entropy source, this is unlikely to be commonly used in an
       application processor, and so Zkr was not added as a profile option.
       This also means the roll-up Zk was not added as a profile option.
-  - location: optional
-    note: |
+  - presence: optional
+    text: |
       The Zfinx, Zdinx, Zhinx, Zhinxmin extensions are incompatible
       with the profile mandates to support the F and D extensions.

backends/crd_doc/templates/crd.adoc.erb

@@ -125,10 +125,26 @@ None
 | <%= ext_req.version_requirement %>
 | <%= ext_db.nil? ? "" : ext_db.long_name %>
 | <%= ext_req.note.nil? ? "" : ext_req.note %>
-<% end -%>
+<% end # each ext_req -%>
 |===
-<% end # if table -%>
-<% end # do ext_reqs -%>
+<% end # if empty ext_reqs -%>
+
+<% crd.extra_notes_for_presence(presence)&.each do |extra_note| -%>
+NOTE: <%= extra_note.text %>
+
+<% end # each extra_note -%>
+
+<% end # each presence -%>
+
+<% unless crd.recommendations.empty? -%>
+=== Recommendations
+
+Recommendations are not strictly mandated but are included to guide implementers making design choices.
+
+<% crd.recommendations.each do |recommendation| -%>
+<%= recommendation.text %>
+<% end # each recommendation -%>
+<% end # unless recommendations empty -%>
 
 <<<
 == Implementation-dependencies

backends/manual/templates/instruction.adoc.erb

@@ -13,11 +13,11 @@ This instruction is included in the following profiles:
 
 <%- arch_def.profiles.each do |profile| -%>
 <%-
-  in_profile_mandatory = profile.mandatory_extension_requirements.any? do |ext_req|
+  in_profile_mandatory = profile.in_scope_ext_reqs("mandatory").any? do |ext_req|
     ext_versions = ext_req.satisfying_versions(arch_def)
     ext_versions.any? { |ext_ver| inst.defined_by?(ext_ver) }
   end
-  in_profile_optional = profile.optional_extension_requirements.any? do |ext_req|
+  in_profile_optional = profile.in_scope_ext_reqs("optional").any? do |ext_req|
     ext_versions = ext_req.satisfying_versions(arch_def)
     ext_versions.any? { |ext_ver| inst.defined_by?(ext_ver) }
   end