Merge pull request #115 from riscv-software-src/manual_appendices

Add profile info to instructions in manual

Author: dhower-qc

arch/csr/mstatus.yaml

@@ -61,11 +61,11 @@ mstatus:
         Since the CPU does not support big endian, this is hardwired to 0.
 
         [when,"M_MODE_ENDIANESS == big"]
-        Since the CPU does not support litte endian, this is hardwired to 1.
+        Since the CPU does not support little endian, this is hardwired to 1.
       type(): |
         return (M_MODE_ENDIANESS == "dynamic") ? CsrFieldType::RW : CsrFieldType::RO;
 
-      # if endianess is mutable, MBE comes out of reset in little-endian mode
+      # if endianness is mutable, MBE comes out of reset in little-endian mode
       reset_value(): |
         return (M_MODE_ENDIANESS == "big") ? 1 : 0;
 

backends/manual/tasks.rake

@@ -189,14 +189,19 @@ end
 rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/csrs/pages/.*.adoc} => [
   __FILE__,
   "#{$root}/.stamps/arch-gen-_64.stamp",
+  "#{$root}/.stamps/arch-gen-_32.stamp",
   ($root / "backends" / "manual" / "templates" / "csr.adoc.erb").to_s
 ] do |t|
   csr_name = File.basename(t.name, ".adoc")
 
   arch_def = arch_def_for("_64")
+  arch_def_32 = arch_def_for("_32")
+
   csr = arch_def.csr(csr_name)
   raise "Can't find csr '#{csr_name}'" if csr.nil?
 
+  csr_32 = arch_def_32.csr(csr_name)
+
   csr_template_path = $root / "backends" / "manual" / "templates" / "csr.adoc.erb"
   erb = ERB.new(csr_template_path.read, trim_mode: "-")
   erb.filename = csr_template_path.to_s

backends/manual/templates/csr.adoc.erb

@@ -15,13 +15,13 @@ h| CSR Address    | <%= "0x#{csr.address.to_s(16)}" %>
 <%- if csr.priv_mode == 'VS' -%>
 h| Virtual CSR Address    | <%= "0x#{csr.virtual_address.to_s(16)}" %>
 <%- end -%>
-<%- if csr.dynamic_length?(arch_def) -%>
+<%- if csr.dynamic_length?(arch_def) ||  csr.data["length"] == "MXLEN" -%>
 h| Length
 a|
 
 [when,"<%= csr.length_cond32 %>"]
 --
-<%= csr.length_pretty(arch_def, 32) %>
+<%= csr_32.length_pretty(arch_def_32, 32) %>
 --
 
 [when,"<%= csr.length_cond64 %>"]
@@ -36,7 +36,7 @@ h| Privilege Mode | <%= csr.priv_mode %>
 |===
 
 == Format
-<%- unless csr.dynamic_length?(arch_def) || csr.fields.any? { |f| f.dynamic_location?(arch_def) } -%>
+<%- unless csr.dynamic_length?(arch_def) || csr.fields.any? { |f| f.dynamic_location?(arch_def) } || csr.data["length"] == "MXLEN" -%>
 <%# CSR has a known static length, so there is only one format to display -%>
 .<%= csr.name %> format
 [wavedrom, ,svg,subs='attributes',width="100%"]
@@ -52,7 +52,7 @@ This CSR format changes dynamically.
 --
 [wavedrom, ,svg,subs='attributes',width="100%"]
 ....
-<%= JSON.dump csr.wavedrom_desc(arch_def, 32) %>
+<%= JSON.dump csr_32.wavedrom_desc(arch_def_32, 32) %>
 ....
 --
 

backends/manual/templates/func.adoc.erb

@@ -10,14 +10,30 @@
 
 <%= f.description %>
 
+[cols="1,2"]
 |===
-h| Return Type l| <%= f.return_type_list_str.join(', ') %>
-h| Arguments   l| <%= f.arguments_list_str.join (', ') %>
+h| Return Type
+a|
+[source,idl]
+----
+<%= f.return_type_list_str.join(', ') %>
+----
+
+h| Arguments
+a|
+<%- if f.arguments_list_str.empty? -%>
+None
+<%- else -%>
+[source,idl]
+----
+<%= f.arguments_list_str.join (', ') %>
+----
+<%- end -%>
 |===
 
 <%- unless f.builtin? -%>
 <%- body_ast = f.body -%>
-[subs="specialchars,macros"]
+[source,idl,subs="specialchars,macros"]
 ----
 <%= body_ast.gen_adoc %>
 ----

backends/manual/templates/instruction.adoc.erb

@@ -9,6 +9,26 @@ This instruction is defined by:
 
 <%= inst.defined_by.to_asciidoc %>
 
+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|
+    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|
+    ext_versions = ext_req.satisfying_versions(arch_def)
+    ext_versions.any? { |ext_ver| inst.defined_by?(ext_ver) }
+  end
+  if in_profile_mandatory
+-%>
+* <%= profile.marketing_name %> (Mandatory)
+<%- elsif in_profile_optional -%>
+* <%= profile.marketing_name %> (Optional)
+<%- end -%>
+<%- end -%>
+
 == Encoding
 
 <%- if inst.multi_encoding? -%>
@@ -74,7 +94,7 @@ This instruction must have data-independent timing when extension `Zkt` is enabl
 ====
 RV32::
 +
-[source.idl]
+[source,idl]
 ----
 <%- inst.decode_variables(32).each do |d| -%>
 <%= d.sext? ? 'signed ' : '' %>Bits<<%= d.size %>> <%= d.name %> = <%= d.extract %>;

lib/arch_obj_models/extension.rb

@@ -364,6 +364,16 @@ def initialize(name, *requirements, note: nil, req_id: nil, presence: nil)
     @presence = presence
   end
 
+  # @return [Array<ExtensionVersion>] The list of extension versions that satisfy this requirement
+  def satisfying_versions(archdef)
+    ext = archdef.extension(@name)
+    return [] if ext.nil?
+
+    ext.versions.select { |v| @requirement.satisfied_by?(Gem::Version.new(v["version"])) }.map do |v|
+      ExtensionVersion.new(@name, v["version"])
+    end
+  end
+
   # @overload
   #   @param extension_version [ExtensionVersion] A specific extension version
   #   @return [Boolean] whether or not the extension_version meets this requirement

lib/arch_obj_models/manual.rb

@@ -170,7 +170,7 @@ def instructions
         @instructions << inst
       end
     end
-    @instructions
+    @instructions = @instructions.uniq(&:name)
   end
 
   # @return [Array<Csr>] All csrs defined in this version
@@ -184,6 +184,6 @@ def csrs
         @csrs << csr
       end
     end
-    @csrs
+    @csrs = @csrs.uniq(&:name)
   end
 end