Adding comments, debug messages, fixing spelling

Author: james-ball-qualcomm

cert_flow.txt

@@ -20,7 +20,7 @@ bootstrap_cert_model = bootstrap_cfg_arch.cert_model(cert_model_name = "MC100-32
 						@cfg_arch = arch 				# rv32 (nil if Architecture object provided)
 						@specification = arch 	# rv32
 cfg_arch = bootstrap_cert_model.to_cfg_arch		# In Portfolio class
-	Creates hash with mandatory extensions (with version requirement) and params
+	Creates hash with mandatory extensions (with version requirement) and fully-constrained params (single_value?)
 		Uses in_scope_ext_reqs() and all_in_scope_ext_params() in Portfolio
 	Writes hash to yaml file in /tmp/.../MC100-32/cfg.yaml
 	Passes yaml file to ConfiguredArchitecture.new()
@@ -47,7 +47,7 @@ mandatory_extensions:
   - name: "Sm"
     version: ">= 0"
 ===============================================================================================
-Example of /tmp/.../MC100-32/cfg.yaml
+Bootstrap /tmp/.../MC100-32/cfg.yaml
 ---
 "$schema": config_schema.json
 type: partially configured

lib/architecture.rb

@@ -2,7 +2,7 @@
 
 # Contains the "database" of RISC-V standards including extensions, instructions,
 # CSRs, Profiles, and Certificates.  Could be either the standard spec (defined by RISC-V International)
-# of a custom spec (defined as an arch_overlay in cfgs/).
+# of a custom spec (defined as an arch_overlay in /cfgs dir).
 #
 # Creates Ruby functions at runtime (see generate_obj_methods() and OBJS array).
 #   1) Function to return Array<klass>              (every klass in database)
@@ -22,7 +22,7 @@
 #   Manual          manuals()           manual_hash()           manual(name)
 #   ManualVersion   manual_versions()   manual_version_hash()   manual_version(name)
 #
-# Statically created Ruby functions:
+# Normal Ruby functions:
 #
 #   klass               Array<klass>        Hash<String name,klass> Klass func(String name)
 #   ==================  ==================  ======================= =========================

lib/config.rb

@@ -63,8 +63,10 @@ def configured? = @data["type"] != "unconfigured"
   def type = @data["type"]
 end
 
-# this class represents a configuration file (e.g., cfgs/*/cfg.yaml) that is "unconfigured"
-# (i.e., we don't know any implemented/mandatory extensions or parameter values)
+#################################################################
+# This class represents a configuration that is "unconfigured". #
+# It doesn't know anything about extensions or parameters.      #
+#################################################################
 class Unconfig < Config
   attr_reader :param_values
 
@@ -76,15 +78,15 @@ def initialize(cfg_file_path, data)
 
   def mxlen = nil
 
-  def implemented_extensions = raise "implemented_extensions is only availabe for a FullConfig"
-  def mandatory_extensions = raise "mandatory_extensions is only availabe for a PartialConfig"
-  def prohibited_extensions = raise "prohibited_extensions is only availabe for a PartialConfig"
+  def implemented_extensions = raise "implemented_extensions is only available for a FullConfig"
+  def mandatory_extensions = raise "mandatory_extensions is only available for a PartialConfig"
+  def prohibited_extensions = raise "prohibited_extensions is only available for a PartialConfig"
 end
 
-# this class represents a configuration file (e.g., cfgs/*/cfg.yaml) that is "partially configured"
-# (i.e., we have a list of mandatory/prohibited extensions and a paritial list of parameter values)
-#
-# This would, for example, represent a Profile or configurable IP
+##############################################################################################################
+# This class represents a configuration that is "partially-configured" (e.g., portfolio or configurable IP). #
+# It only lists mandatory & prohibited extensions and fully-constrained parameters (single value).
+##############################################################################################################
 class PartialConfig < Config
   attr_reader :param_values, :mxlen
 
@@ -99,15 +101,16 @@ def initialize(cfg_file_path, data)
     @mxlen.freeze
   end
 
-  def implemented_extensions = raise "implemented_extensions is only availabe for a FullConfig"
+  def implemented_extensions = raise "implemented_extensions is only available for a FullConfig"
 
   # @return [Array<Hash{String => String,Array<String}>]
   #    List of all extensions that must be implemented, as specified in the config file
   #    The first entry in the nested array is an Extension name.
   #    The second entry in the nested array is an Extension version requirement
   #
   # @example
-  #   partial_config.mandatory_extensions #=> [{ "name" => "A", "version" => ["~> 2.0"] }, { "name" => "B", "version" => ["~> 1.0"] }, ...]
+  #   partial_config.mandatory_extensions =>
+  #     [{ "name" => "A", "version" => ["~> 2.0"] }, { "name" => "B", "version" => ["~> 1.0"] }, ...]
   def mandatory_extensions
     @mandatory_extensions ||=
       if @data["mandatory_extensions"].nil?
@@ -126,7 +129,8 @@ def mandatory_extensions
   #   The second entry in the nested array is an Extension version requirement.
   #
   # @example
-  #   partial_config.prohibited_extensions #=> [{ "name" => "F", "version" => [">= 2.0"] }, { "name" => "Zfa", "version" => ["> = 1.0"] }, ...]
+  #   partial_config.prohibited_extensions =>
+  #     [{ "name" => "F", "version" => [">= 2.0"] }, { "name" => "Zfa", "version" => ["> = 1.0"] }, ...]
   def prohibited_extensions
     @prohibited_extensions ||=
       if @data["prohibited_extensions"].nil?
@@ -144,10 +148,10 @@ def prohibited_extensions
   # def ext?(ext_name, cfg_arch) = mandatory_extensions(cfg_arch).any? { |e| e.name == ext_name.to_s }
 end
 
-# this class represents a configuration file (e.g., cfgs/*/cfg.yaml) that is "fully configured"
-# (i.e., we have a complete list of implemented extensions and a complete list of parameter values)
-#
-# This would, for example, represent a specific silicon tapeout/SKU
+################################################################################################################
+# This class represents a configuration that is "fully-configured" (e.g., SoC tapeout or fully-configured IP). #
+# It has a complete list of extensions and parameters (all are a single value at this point).                  #
+################################################################################################################
 class FullConfig < Config
   attr_reader :param_values, :mxlen
 
@@ -176,8 +180,8 @@ def implemented_extensions
       end
   end
 
-  def mandatory_extensions = raise "mandatory_extensions is only availabe for a PartialConfig"
-  def prohibited_extensions = raise "prohibited_extensions is only availabe for a PartialConfig"
+  def mandatory_extensions = raise "mandatory_extensions is only available for a PartialConfig"
+  def prohibited_extensions = raise "prohibited_extensions is only available for a PartialConfig"
 
   # def prohibited_ext?(ext_name, cfg_arch) = !ext?(ext_name, cfg_arch)
   # def ext?(ext_name, cfg_arch) = implemented_extensions(cfg_arch).any? { |e| e.name == ext_name.to_s }