Add list of extension parameters to manual

Author: Derek Hower

arch/ext/Sm.yaml

@@ -415,9 +415,8 @@ Sm:
         TODO: GitHub issue 53
       schema:
         type: integer
-      # GitHub issue 53
-      # when:
-      #  version: ">= 1.12.0"
+      when:
+        version: ">= 1.12.0"
     PMA_GRANULARITY:
       description: |
         log2 of the smallest supported PMA region.

backends/manual/tasks.rake

@@ -241,6 +241,24 @@ rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/funcs/pages/funcs.adoc} => [
   File.write t.name, AntoraUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
 end
 
+# rule to create IDL function appendix page
+rule %r{#{MANUAL_GEN_DIR}/.*/.*/antora/modules/params/pages/param_list.adoc} => [
+  __FILE__,
+  "#{$root}/.stamps/arch-gen-_64.stamp",
+  ($root / "backends" / "manual" / "templates" / "param_list.adoc.erb").to_s
+] do |t|
+  arch_def = arch_def_for("_64")
+  parts = t.name.sub("#{MANUAL_GEN_DIR}/", "").split("/")
+  manual_version = arch_def.manual(parts[0])&.version(parts[1])
+
+  param_list_template_path = $root / "backends" / "manual" / "templates" / "param_list.adoc.erb"
+  erb = ERB.new(param_list_template_path.read, trim_mode: "-")
+  erb.filename = param_list_template_path.to_s
+
+  FileUtils.mkdir_p File.dirname(t.name)
+  File.write t.name, AntoraUtils.resolve_links(arch_def.find_replace_links(erb.result(binding)))
+end
+
 rule %r{#{MANUAL_GEN_DIR}/.*/top/.*/antora/landing/antora.yml} => [
   __FILE__
 ] do |t|
@@ -394,6 +412,7 @@ namespace :gen do
       version.extensions.each do |ext|
         Rake::Task[antora_path / "modules" / "exts" / "pages" / "#{ext.name}.adoc"].invoke
       end
+      Rake::Task[antora_path / "modules" / "params" / "pages" / "param_list.adoc"].invoke
     end
 
     landing_page_path = MANUAL_GEN_DIR / ENV["MANUAL_NAME"] / "top" / output_hash / "antora" / "landing" / "modules" / "ROOT" / "pages" / "index.adoc"

backends/manual/templates/isa_nav.adoc.erb

@@ -1,25 +1,26 @@
 <%- manual_version.volumes.each do |volume| -%>
-.<%= volume.title %>
+* <%= volume.title %>
 <%- volume.chapters.each do |chapter| -%>
-* xref:chapters:<%= File.basename(chapter.path) %>[<%= chapter.title %>]
+** xref:chapters:<%= File.basename(chapter.path) %>[<%= chapter.title %>]
 <%- end -%>
 
 <%- end -%>
 
-.Alphabetical list of instrutions
+* Alphabetical list of instrutions
 <%- manual_version.instructions.sort { |a, b| a.name <=> b.name }.each do |inst| -%>
-* xref:insts:<%= inst.name %>.adoc[<%= inst.name %>]
+** xref:insts:<%= inst.name %>.adoc[<%= inst.name %>]
 <%- end -%>
 
-.Alphabetical list of CSRs
+* Alphabetical list of CSRs
 <%- manual_version.csrs.sort { |a, b| a.name <=> b.name }.each do |csr| -%>
-* xref:csrs:<%= csr.name %>.adoc[<%= csr.name %>]
+** xref:csrs:<%= csr.name %>.adoc[<%= csr.name %>]
 <%- end -%>
 
-.Alphabetical list of extensions
+* Alphabetical list of extensions
 <%- manual_version.extensions.sort { |a, b| a.name <=> b.name }.each do |ext| -%>
-* xref:exts:<%= ext.name %>.adoc[<%= ext.name %>]
+** xref:exts:<%= ext.name %>.adoc[<%= ext.name %>]
 <%- end -%>
 
-.Execution functions (IDL)
-* xref:funcs:funcs.adoc[Functions]
+* xref:params:param_list.adoc[Alphabetical list of parameters]
+
+* xref:funcs:funcs.adoc[Execution functions (IDL)]

backends/manual/templates/param_list.adoc.erb

@@ -0,0 +1,18 @@
+= Architectural Parameters
+
+<%-
+  params = manual_version.extensions.map{ |e| e.params(arch_def) }.flatten.uniq(&:name).sort_by!(&:name)
+-%>
+
+The following <%= params.size %> parameters are defined in this manual:
+
+|===
+| Name | Type | Extension(s) | Description
+
+<%- params.each do |param| -%>
+| <%= param.name %>
+| <%= param.schema.to_pretty_s %>
+| <%= param.exts.map { |ext| "`#{ext.name}`"}.join(", ") %>
+a| <%= param.desc %>
+<%- end -%>
+|===

lib/arch_def.rb

@@ -432,15 +432,11 @@ def conflicting_ext?(ext_name)
     prohibited_extensions.include? { |ext_req| ext_req.name == ext_name }
   end
 
-  # @return [Array<ExtensionParameter>] List of all parameters defined in the architecture
+  # @return [Array<ExtensionParameter>] Alphabetical list of all parameters defined in the architecture
   def params
     return @params unless @params.nil?
 
-    @params = []
-    extensions.each do |ext|
-      @params += ext.params
-    end
-    @params
+    @params = extensions.map(&:params).flatten.uniq(&:name).sort_by!(&:name)
   end
 
   # @return [Hash<String, ExtensionParameter>] Hash of all extension parameters defined in the architecture

lib/arch_obj_models/crd.rb

@@ -234,7 +234,7 @@ def allowed_values
       end
 
       # Create a Schema object just using information in the parameter database.
-      schema_obj = Schema.new(@param_db.schema)
+      schema_obj = @param_db.schema
 
       # Merge in constraints imposed by the CRD on the parameter.
       schema_obj.merge!(@schema_crd)

lib/arch_obj_models/extension.rb

@@ -5,13 +5,16 @@
 
 # A parameter (AKA option, AKA implementation-defined value) supported by an extension
 class ExtensionParameter
+  # @return [ArchDef] The defining Arch def
+  attr_reader :archdef
+
   # @return [String] Parameter name
   attr_reader :name
 
   # @return [String] Asciidoc description
   attr_reader :desc
 
-  # @return [Hash] JSON Schema for the parameter value
+  # @return [Schema] JSON Schema for this param
   attr_reader :schema
 
   # @return [String] Ruby code to perform validation above and beyond JSON schema
@@ -25,25 +28,46 @@ class ExtensionParameter
   attr_reader :exts
 
   # @returns [Idl::Type] Type of the parameter
-  attr_reader :type
+  attr_reader :idl_type
 
   # Pretty convert extension schema to a string.
   def schema_type
-    Schema.new(@schema).to_pretty_s
+    @schema.to_pretty_s
   end
 
-  def initialize(name, desc, schema, extra_validation, exts)
+  def initialize(ext, name, data)
+    @archdef = ext.arch_def
+    @data = data
     @name = name
-    @desc = desc
-    @schema = schema
-    @extra_validation = extra_validation
-    @exts = exts
-    begin
-      @type = Idl::Type.from_json_schema(@schema).make_const.freeze
-    rescue
-      warn "While parsing scheme for ExtensionParameter #{ext.name}.#{name}"
-      raise
+    @desc = data["description"]
+    @schema = Schema.new(data["schema"])
+    @extra_validation = data["extra_validation"]
+    also_defined_in = []
+    unless data["also_defined_in"].nil?
+      if data["also_defined_in"].is_a?(String)
+        other_ext = @archdef.extension(data["also_defined_in"])
+        raise "Definition error in #{ext.name}.#{name}: #{data['also_defined_in']} is not a known extension" if other_ext.nil?
+        also_defined_in << other_ext
+      else
+        unless data["also_defined_in"].is_a?(Array) && data["also_defined_in"].all? { |e| e.is_a?(String) }
+          raise "schema error: also_defined_in should be a string or array of strings"
+        end
+
+        data["also_defined_in"].each do |other_ext_name|
+          other_ext = @archdef.extension(other_ext_name)
+          raise "Definition error in #{ext.name}.#{name}: #{data['also_defined_in']} is not a known extension" if other_ext.nil?
+          also_defined_in << other_ext
+        end
+      end
     end
+    @exts = [ext] + also_defined_in
+    @idl_type = @schema.to_idl_type.make_const.freeze
+  end
+
+  def defined_in_extension_version?(version)
+    return true if @data.dig("when", "version").nil?
+
+    Gem::Requirement.new(@data["when"]["version"]).satisfied_by?(version)
   end
 
   # sorts by name
@@ -135,31 +159,7 @@ def params
     @params = []
     if @data.key?("params")
       @data["params"].each do |param_name, param_data|
-        also_defined_in = []
-        unless param_data["also_defined_in"].nil?
-          if param_data["also_defined_in"].is_a?(String)
-            other_ext = arch_def.extension(param_data["also_defined_in"])
-            raise "Definition error in #{name}.#{param_name}: #{param_data['also_defined_in']} is not a known extension" if other_ext.nil?
-            also_defined_in << other_ext
-          else
-            unless param_data["also_defined_in"].is_a?(Array) && param_data["also_defined_in"].all? { |e| e.is_a?(String) }
-              raise "schema error: also_defined_in should be a string or array of strings"
-            end
-
-            param_data["also_defined_in"].each do |other_ext_name|
-              other_ext = arch_def.extension(other_ext_name)
-              raise "Definition error in #{name}.#{param_name}: #{param_data['also_defined_in']} is not a known extension" if other_ext.nil?
-              also_defined_in << other_ext
-            end
-          end
-        end
-        @params << ExtensionParameter.new(
-          param_name,
-          param_data["description"],
-          param_data["schema"],
-          param_data["extra_validation"],
-          [self] + also_defined_in
-        )
+        @params << ExtensionParameter.new(self, param_name, param_data)
       end
     end
     @params
@@ -277,6 +277,11 @@ def ext(arch_def)
     arch_def.extension(name)
   end
 
+  # @return [Array<ExtensionParameter>] The list of parameters for this extension version
+  def params(arch_def)
+    ext(arch_def).params.select { |p| p.defined_in_extension_version?(@version) }
+  end
+
   # @overload ==(other)
   #   @param other [String] An extension name
   #   @return [Boolean] whether or not this ExtensionVersion is named 'other'

lib/arch_obj_models/manual.rb

@@ -152,6 +152,7 @@ def volumes
 
   def state = @data["state"]
 
+  # @return [Array<ExtensionVersion>] Array of extension versions in this manual version
   def extensions
     return @extensions unless @extensions.nil?
 

lib/arch_obj_models/schema.rb

@@ -1,12 +1,22 @@
 #frozen_string_literal: true
 
+require_relative "../idl/type"
+
+# represents a JSON Schema
+#
+# Used when an object in the database specifies a constraint using JSON schema
+# For example, extension parameters
 class Schema 
     def initialize(schema_hash)
         raise ArgumentError, "Expecting hash" unless schema_hash.is_a?(Hash)
 
         @schema_hash = schema_hash
     end
 
+    # @return [Hash] Hash representation of the JSON Schema
+    def to_h = @schema_hash
+
+    # @return [String] A human-readable description of the schema
     def to_pretty_s(schema_hash = @schema_hash)
       raise ArgumentError, "Expecting hash" unless schema_hash.is_a?(Hash)
       raise ArgumentError, "Expecting non-empty hash" if schema_hash.empty?
@@ -138,5 +148,10 @@ def num_bits(min, max)
         return 0 unless min == 0
         is_power_of_two?(max+1) ? max.bit_length : 0
     end
+
+    # @return [Idl::Type] THe IDL-equivalent type for this schema object
+    def to_idl_type
+      Idl::Type.from_json_schema(@schema_hash)
+    end
 end
 

lib/idl/symbol_table.rb

@@ -138,17 +138,17 @@ def initialize(arch_def, effective_xlen = nil)
         if param.exts.size == 1
           if param.name == "XLEN"
             # special case: we actually do know XLEN
-            add!(param.name, Var.new(param.name, param.type.clone.make_const, @mxlen))
+            add!(param.name, Var.new(param.name, param.idl_type.clone.make_const, @mxlen))
           else
-            add!(param.name, Var.new(param.name, param.type.clone.make_const))
+            add!(param.name, Var.new(param.name, param.idl_type.clone.make_const))
           end
         else
           # could already be present...
           existing_sym = get(param.name)
           if existing_sym.nil?
-            add!(param.name, Var.new(param.name, param.type.clone.make_const))
+            add!(param.name, Var.new(param.name, param.idl_type.clone.make_const))
           else
-            unless existing_sym.type.equal_to?(param.type)
+            unless existing_sym.type.equal_to?(param.idl_type)
               raise "Definition error: Param #{param.name} is defined by multiple extensions and is not the same definition in each"
             end
           end