Add type annotations to csr_field.rb

Author: dhower-qc

lib/arch_obj_models/csr_field.rb

@@ -12,6 +12,7 @@ class CsrField < DatabaseObject
   extend T::Sig;
 
   # @return [Csr] The Csr that defines this field
+  sig { returns(Csr) }
   attr_reader :parent
 
   # @!attribute field
@@ -22,12 +23,14 @@ class CsrField < DatabaseObject
 
   # @return [Integer] The base XLEN required for this CsrField to exist. One of [32, 64]
   # @return [nil] if the CsrField exists in any XLEN
+  sig { returns(T.nilable(Integer)) }
   def base
     @data["base"]
   end
 
   # @param parent_csr [Csr] The Csr that defined this field
   # @param field_data [Hash<String,Object>] Field data from the arch spec
+  sig { params(parent_csr: Csr, field_name: String, field_data: T::Hash[String, T.untyped]).void }
   def initialize(parent_csr, field_name, field_data)
     super(field_data, parent_csr.data_path, arch: parent_csr.arch)
     @name = field_name
@@ -38,6 +41,7 @@ def initialize(parent_csr, field_name, field_data)
   # For a partial config, whether or the it is possible for the field to be implemented
   #
   # @return [Boolean] True if this field might exist in a config
+  sig { params(cfg_arch: ConfiguredArchitecture).returns(T::Boolean) }
   def exists_in_cfg?(cfg_arch)
     if cfg_arch.fully_configured?
       parent.exists_in_cfg?(cfg_arch) &&
@@ -53,6 +57,7 @@ def exists_in_cfg?(cfg_arch)
   end
 
   # @return [Boolean] For a partially configured cfg_arch, whether or not the field is optional (not mandatory or prohibited)
+  sig { params(cfg_arch: ConfiguredArchitecture).returns(T::Boolean) }
   def optional_in_cfg?(cfg_arch)
     raise "optional_in_cfg? should only be called on a partially configured cfg_arch" unless cfg_arch.partially_configured?
 
@@ -71,18 +76,22 @@ def optional_in_cfg?(cfg_arch)
   # @return [Boolean] Whether or not the presence of ext_ver affects this CSR Field definition
   #                   This does not take the parent CSR into account, i.e., a field can be unaffected
   #                   by ext_ver even if the parent CSR is affected
+  sig { params(ext_ver: ExtensionVersion).returns(T::Boolean) }
   def affected_by?(ext_ver)
     @data["definedBy"].nil? ? false : defined_by_condition.possibly_satisfied_by?(ext_ver)
   end
 
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the type() function
   # @return [nil] if the type property is not a function
+  sig { returns(T.nilable(Idl::FunctionBodyAst)) }
   def type_ast
     return @type_ast unless @type_ast.nil?
     return nil if @data["type()"].nil?
 
+    idl_code = T.must(@data["type()"])
+
     @type_ast = @cfg_arch.idl_compiler.compile_func_body(
-      @data["type()"],
+      idl_code,
       name: "CSR[#{csr.name}].#{name}.type()",
       input_file: csr.__source,
       input_line: csr.source_line("fields", name, "type()"),
@@ -100,6 +109,7 @@ def type_ast
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the type() function, after it has been type checked
   # @return [nil] if the type property is not a function
   # @param effective_xlen [32, 64] The effective xlen to evaluate for
+  sig { params(effective_xlen: T.nilable(Integer)).returns(T.nilable(Idl::FunctionBodyAst)) }
   def type_checked_type_ast(effective_xlen)
     @type_checked_type_ast ||= { 32 => nil, 64 => nil }
     return @type_checked_type_ast[effective_xlen] unless @type_checked_type_ast[effective_xlen].nil?
@@ -128,6 +138,7 @@ def type_checked_type_ast(effective_xlen)
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the type() function, after it has been type checked and pruned
   # @return [nil] if the type property is not a function
   # @param effective_xlen [32, 64] The effective xlen to evaluate for
+  sig { params(effective_xlen: T.nilable(Integer)).returns(T.nilable(Idl::FunctionBodyAst)) }
   def pruned_type_ast(effective_xlen)
     @pruned_type_ast ||= { 32 => nil, 64 => nil }
     return @pruned_type_ast[effective_xlen] unless @pruned_type_ast[effective_xlen].nil?
@@ -169,6 +180,7 @@ def pruned_type_ast(effective_xlen)
   #      'RW-R'  => Read-write, with a restricted set of legal values
   #      'RW-H'  => Read-write, with a hardware update
   #      'RW-RH' => Read-write, with a hardware update and a restricted set of legal values
+  sig { params(effective_xlen: T.nilable(Integer)).returns(String) }
   def type(effective_xlen = nil)
     @type ||= { 32 => nil, 64 => nil }
     return @type[effective_xlen] unless @type[effective_xlen].nil?
@@ -179,11 +191,8 @@ def type(effective_xlen = nil)
         @data["type"]
       else
         # the type is config-specific...
-        idl = @data["type()"]
-        raise "type() is nil for #{csr.name}.#{name} #{@data}?" if idl.nil?
 
-        # value_result = Idl::AstNode.value_try do
-        ast = type_checked_type_ast(effective_xlen)
+        ast = T.must(type_checked_type_ast(effective_xlen))
         begin
           symtab = fill_symtab_for_type(effective_xlen, ast)
 
@@ -209,8 +218,8 @@ def type(effective_xlen = nil)
             type = nil
           end
         ensure
-          symtab.pop
-          symtab.release
+          symtab.pop unless symtab.nil?
+          symtab.release unless symtab.nil?
         end
         type
         # end
@@ -226,21 +235,21 @@ def type(effective_xlen = nil)
 
   # @return [String] A pretty-printed type string
   # @param effective_xlen [32, 64] The effective xlen to evaluate for
+  sig { params(effective_xlen: T.nilable(Integer)).returns(String) }
   def type_pretty(effective_xlen = nil)
-    raise ArgumentError, "Expecting Integer" unless effective_xlen.nil? || effective_xlen.is_a?(Integer)
-
     str = T.let(nil, T.nilable(String))
     value_result = Idl::AstNode.value_try do
       str = type(effective_xlen)
     end
     Idl::AstNode.value_else(value_result) do
-      ast = type_ast
+      ast = T.must(type_ast)
       str = ast.gen_option_adoc
     end
-    str
+    T.must(str)
   end
 
   # @return [Alias,nil] The aliased field, or nil if there is no alias
+  sig { returns(T.nilable(Alias)) }
   def alias
     return @alias unless @alias.nil?
 
@@ -270,6 +279,7 @@ def alias
   # @return [Array<Idl::FunctionDefAst>] List of functions called through this field
   # @param cfg_arch [ConfiguredArchitecture] a configuration
   # @Param effective_xlen [Integer] 32 or 64; needed because fields can change in different XLENs
+  sig { params(effective_xlen: T.nilable(Integer)).returns(T::Array[Idl::FunctionDefAst]) }
   def reachable_functions(effective_xlen)
     return @reachable_functions unless @reachable_functions.nil?
 
@@ -307,6 +317,7 @@ def reachable_functions(effective_xlen)
 
   # @return [Boolean] Whether or not the location of the field changes dynamically
   #                   (e.g., based on mstatus.SXL) in the configuration
+  sig { returns(T::Boolean) }
   def dynamic_location?
     # if there is no location_rv32, the the field never changes
     return false unless @data["location"].nil?
@@ -317,6 +328,7 @@ def dynamic_location?
 
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the reset_value function
   # @return [nil] If the reset_value is not a function
+  sig { returns(T.nilable(Idl::FunctionBodyAst)) }
   def reset_value_ast
     return @reset_value_ast unless @reset_value_ast.nil?
     return nil unless @data.key?("reset_value()")
@@ -332,9 +344,9 @@ def reset_value_ast
     )
   end
 
-  # @param symtab [Idl::SymbolTable] A symbol table with globals
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the reset_value function, after being type checked
   # @return [nil] If the reset_value is not a function
+  sig { returns(T.nilable(Idl::FunctionBodyAst)) }
   def type_checked_reset_value_ast
     return @type_checked_reset_value_ast unless @type_checked_reset_value_ast.nil?
 
@@ -355,12 +367,13 @@ def type_checked_reset_value_ast
 
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the reset_value function, type checked and pruned
   # @return [nil] If the reset_value is not a function
+  sig { returns(T.nilable(Idl::FunctionBodyAst)) }
   def pruned_reset_value_ast
     return @pruned_reset_value_ast unless @pruned_reset_value_ast.nil?
 
     return nil unless @data.key?("reset_value()")
 
-    ast = type_checked_reset_value_ast
+    ast = T.must(type_checked_reset_value_ast)
 
     symtab = fill_symtab_for_reset(ast)
     ast = ast.prune(symtab)
@@ -378,7 +391,7 @@ def reset_value
       if @data.key?("reset_value")
         @data["reset_value"]
       else
-        ast = pruned_reset_value_ast
+        ast = T.must(pruned_reset_value_ast)
         symtab = fill_symtab_for_reset(ast)
         val = T.let(nil, T.untyped)
         value_result = Idl::AstNode.value_try do
@@ -394,6 +407,7 @@ def reset_value
     end
   end
 
+  sig { returns(T::Boolean) }
   def dynamic_reset_value?
     return false unless @data["reset_value"].nil?
 
@@ -403,32 +417,29 @@ def dynamic_reset_value?
     end || true
   end
 
+  sig { returns(String) }
   def reset_value_pretty
     str = T.let(nil, T.nilable(String))
     value_result = Idl::AstNode.value_try do
       str = reset_value
     end
     Idl::AstNode.value_else(value_result) do
-      ast = reset_value_ast
+      ast = T.must(reset_value_ast)
       str = ast.gen_option_adoc
     end
-    str
-  end
-
-  # @return [Boolean] true if the field could have an undefined value at any point
-  def could_be_undefined?
-    (reset_value == "UNDEFINED_LEGAL") || \
-      (has_custom_sw_write? && sw_write_ast(cfg_arch.symtab).could_return_undefined?(cfg_arch.symtab))
+    T.must(str)
   end
 
   # @return [Boolean] true if the CSR field has a custom sw_write function
+  sig { returns(T::Boolean) }
   def has_custom_sw_write?
     @data.key?("sw_write(csr_value)") && !@data["sw_write(csr_value)"].empty?
   end
 
   # @return [FunctionBodyAst] The abstract syntax tree of the sw_write() function, after being type checked
   # @param effective_xlen [Integer] 32 or 64; the effective XLEN to evaluate this field in (relevant when fields move in different XLENs)
   # @param symtab [Idl::SymbolTable] Symbol table with globals
+  sig { params(symtab: Idl::SymbolTable, effective_xlen: T.nilable(Integer)).returns(T.nilable(Idl::FunctionBodyAst)) }
   def type_checked_sw_write_ast(symtab, effective_xlen)
     @type_checked_sw_write_asts ||= {}
     ast = @type_checked_sw_write_asts[symtab.hash]
@@ -453,7 +464,7 @@ def type_checked_sw_write_ast(symtab, effective_xlen)
       Idl::Var.new("csr_value", csr.bitfield_type(symtab.cfg_arch, effective_xlen))
     )
 
-    ast = sw_write_ast(symtab)
+    ast = T.must(sw_write_ast(symtab))
     symtab.cfg_arch.idl_compiler.type_check(
       ast,
       symtab,
@@ -466,10 +477,9 @@ def type_checked_sw_write_ast(symtab, effective_xlen)
 
   # @return [Idl::FunctionBodyAst] The abstract syntax tree of the sw_write() function
   # @return [nil] If there is no sw_write() function
-  # @param cfg_arch [ConfiguredArchitecture] An architecture definition
+  # @param symtab [Idl::SymbolTable] Symbols
+  sig { params(symtab: Idl::SymbolTable).returns(T.nilable(Idl::FunctionBodyAst)) }
   def sw_write_ast(symtab)
-    raise ArgumentError, "Argument should be a symtab" unless symtab.is_a?(Idl::SymbolTable)
-
     return @sw_write_ast unless @sw_write_ast.nil?
     return nil if @data["sw_write(csr_value)"].nil?
 
@@ -489,6 +499,7 @@ def sw_write_ast(symtab)
     @sw_write_ast
   end
 
+  sig { params(effective_xlen: T.nilable(Integer), ast: Idl::AstNode).returns(Idl::SymbolTable) }
   def fill_symtab_for_sw_write(effective_xlen, ast)
     symtab = cfg_arch.symtab.global_clone
     symtab.push(ast)
@@ -520,6 +531,7 @@ def fill_symtab_for_sw_write(effective_xlen, ast)
     symtab
   end
 
+  sig { params(effective_xlen: T.nilable(Integer), ast: Idl::AstNode).returns(Idl::SymbolTable) }
   def fill_symtab_for_type(effective_xlen, ast)
     symtab = cfg_arch.symtab.global_clone
     symtab.push(ast)
@@ -571,7 +583,7 @@ def pruned_sw_write_ast(effective_xlen)
 
     return nil unless @data.key?("sw_write(csr_value)")
 
-    ast = type_checked_sw_write_ast(cfg_arch.symtab, effective_xlen)
+    ast = T.must(type_checked_sw_write_ast(cfg_arch.symtab, effective_xlen))
 
     return ast if cfg_arch.unconfigured?
 
@@ -644,24 +656,34 @@ def location(effective_xlen = nil)
   end
 
   # @return [Boolean] Whether or not this field only exists when XLEN == 64
+  sig { returns(T::Boolean) }
   def base64_only? = @data.key?("base") && @data["base"] == 64
 
   # @return [Boolean] Whether or not this field only exists when XLEN == 32
+  sig { returns(T::Boolean) }
   def base32_only? = @data.key?("base") && @data["base"] == 32
 
+  sig { returns(T::Boolean) }
   def defined_in_base32? = @data["base"].nil? || @data["base"] == 32
+
+  sig { returns(T::Boolean) }
   def defined_in_base64? = @data["base"].nil? || @data["base"] == 64
+
+  sig { params(xlen: Integer).returns(T::Boolean) }
   def defined_in_base?(xlen) = @data["base"].nil? || @data["base"] == xlen
 
   # @return [Boolean] Whether or not this field exists for any XLEN
+  sig { returns(T::Boolean) }
   def defined_in_all_bases? = @data["base"].nil?
 
   # @param effective_xlen [Integer] The effective xlen, needed since some fields change location with XLEN. If the field location is not determined by XLEN, then this parameter can be nil
   # @return [Integer] Number of bits in the field
+  sig { params(effective_xlen: T.nilable(Integer)).returns(Integer) }
   def width(effective_xlen)
-    location(effective_xlen).size
+    T.must(location(effective_xlen).size)
   end
 
+  sig { returns(Integer) }
   def max_width
     @max_width ||=
       if base64_only?
@@ -675,6 +697,7 @@ def max_width
       end
   end
 
+  sig { returns(String) }
   def location_cond32
     case csr.priv_mode
     when "M"
@@ -688,6 +711,7 @@ def location_cond32
     end
   end
 
+  sig { returns(String) }
   def location_cond64
     case csr.priv_mode
     when "M"
@@ -702,6 +726,7 @@ def location_cond64
   end
 
   # @return [String] Pretty-printed location string
+  sig { params(effective_xlen: T.nilable(Integer)).returns(String) }
   def location_pretty(effective_xlen = nil)
     derangeify = proc { |loc|
       next loc.min.to_s if loc.size == 1
@@ -785,6 +810,7 @@ def location_pretty(effective_xlen = nil)
   }.freeze
 
   # @return [String] Long description of the field type
+  sig { params(effective_xlen: T.nilable(Integer)).returns(String) }
   def type_desc(effective_xlen=nil)
     TYPE_DESC_MAP[type(effective_xlen)]
   end