idlc 0.1.1 → 0.1.5

data/lib/idlc/ast.rb

@@ -65,11 +65,15 @@ module Idl
 
     # @return [String] Source input file
     sig { returns(T.nilable(Pathname)) }
-    attr_reader :input_file
+    def input_file
+      @input_file || @parent&.input_file
+    end
 
     # @return [Integer] Starting line in the source input file (i.e., position 0 of {#input} in the file)
     sig { returns(Integer) }
-    attr_reader :starting_line
+    def starting_line
+      @starting_line || @parent&.starting_line || 0
+    end
 
     # @return [String] Source string
     sig { returns(T.nilable(String)) }
@@ -212,6 +216,14 @@ module Idl
     sig { abstract.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab); end
 
+    # @return [Boolean] whether this node includes the Executable interface
+    sig { overridable.returns(T::Boolean).checked(:never) }
+    def executable? = false
+
+    # @return [Boolean] whether this node includes the Declaration interface
+    sig { overridable.returns(T::Boolean).checked(:never) }
+    def declaration? = false
+
     # @param input [String] The source being compiled
     # @param interval [Range] The range in the source corresponding to this AstNode
     # @param children [Array<AstNode>] Children of this node
@@ -247,7 +259,7 @@ module Idl
     # @param [Integer] starting_line The starting line number in the input file.
     # @param [Integer] starting_offset The byte offset in the file where the IDL content starts.
     # @param [Array<Integer>, nil] line_file_offsets Per-IDL-line file byte offsets (nil = use starting_offset).
-    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void }
+    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void.checked(:never) }
     def set_input_file_unless_already_set(filename, starting_line = 0, starting_offset = 0, line_file_offsets = nil)
       return unless @input_file.nil?
 
@@ -255,10 +267,6 @@ module Idl
       @starting_line = starting_line
       @starting_offset = starting_offset
       @line_file_offsets = line_file_offsets
-      children.each do |child|
-        child.set_input_file_unless_already_set(filename, starting_line, starting_offset, line_file_offsets)
-      end
-      raise "?" if @starting_line.nil?
     end
 
     # remember where the code comes from
@@ -267,22 +275,18 @@ module Idl
     # @param starting_line [Integer] Starting line in the file
     # @param starting_offset [Integer] Byte offset in the file where the IDL content starts
     # @param line_file_offsets [Array<Integer>, nil] Per-IDL-line file byte offsets (nil = use starting_offset).
-    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void }
+    sig { params(filename: T.any(Pathname, String), starting_line: Integer, starting_offset: Integer, line_file_offsets: T.nilable(T::Array[Integer])).void.checked(:never) }
     def set_input_file(filename, starting_line = 0, starting_offset = 0, line_file_offsets = nil)
       @input_file = Pathname.new(filename)
       @starting_line = starting_line
       @starting_offset = starting_offset
       @line_file_offsets = line_file_offsets
-      children.each do |child|
-        child.set_input_file(filename, starting_line, starting_offset, line_file_offsets)
-      end
-      raise "?" if @starting_line.nil?
     end
 
     # @return [Integer] the current line number
     sig { returns(Integer) }
     def lineno
-      T.must(T.must(input)[0..T.must(interval).first]).count("\n") + 1 + (@starting_line.nil? ? 0 : @starting_line)
+      T.must(T.must(input)[0..T.must(interval).first]).count("\n") + 1 + starting_line
     end
 
     # @return [AstNode] the first ancestor that is_a?(+klass+)
@@ -378,7 +382,7 @@ module Idl
       starting_lineno = T.must(T.must(input)[0..lines_interval.min]).count("\n")
       lines = lines.lines.map do |line|
         starting_lineno += 1
-        "#{@starting_line + starting_lineno - 1}: #{line}"
+        "#{starting_line + starting_lineno - 1}: #{line}"
       end.join("")
 
       msg = <<~WHAT
@@ -415,6 +419,57 @@ module Idl
       attr_accessor :value_error_reason, :value_error_ast
     end
 
+    # Extract the base variable name from a potentially nested access chain
+    # @param node [RvalueAst] The node to extract from
+    # @return [String, nil] The base variable name, or nil if not extractable
+    sig { params(node: RvalueAst).returns(T.nilable(String)) }
+    def self.extract_base_var_name(node)
+      case node
+      when IdAst
+        node.name
+      when AryElementAccessAst, AryRangeAccessAst
+        extract_base_var_name(node.var)
+      else
+        nil
+      end
+    end
+
+    # Perform write-back for nested array access assignments
+    # Handles arbitrary nesting depth: v[a][b][c] = val recursively writes back through the chain
+    # @param target [RvalueAst] The target expression (possibly nested)
+    # @param new_value [Integer] The new value to write
+    # @param symtab [SymbolTable] The symbol table
+    # @return [void]
+    sig { params(target: RvalueAst, new_value: ValueRbType, symtab: SymbolTable).void }
+    def self.write_back_nested(target, new_value, symtab)
+      case target
+      when IdAst
+        # Base case: simple variable
+        existing_var = symtab.get(target.name)
+        raise InternalError, "write_back_nested: '#{target.name}' not found in symbol table" if existing_var.nil?
+        existing_var.value = new_value
+      when AryElementAccessAst
+        # Recursive case: v[idx] = val
+        # Read parent, modify element, write back parent
+        parent_value = target.var.value(symtab)
+        idx_val = target.index.value(symtab)
+        parent_value[idx_val] = new_value
+        # Recursively write back the parent (which may itself be nested)
+        write_back_nested(target.var, parent_value, symtab)
+      when AryRangeAccessAst
+        # Recursive case: v[msb:lsb] = new_value
+        # Read parent, splice new_value into [msb:lsb], write parent back
+        parent_value = T.cast(target.var.value(symtab), Integer)
+        msb_val = T.cast(target.msb.value(symtab), Integer)
+        lsb_val = T.cast(target.lsb.value(symtab), Integer)
+        mask = ((1 << (msb_val - lsb_val + 1)) - 1) << lsb_val
+        updated_parent = (parent_value & ~mask) | ((T.cast(new_value, Integer) << lsb_val) & mask)
+        write_back_nested(target.var, updated_parent, symtab)
+      else
+        raise InternalError, "Unknown target type for write-back: #{target.class.name}"
+      end
+    end
+
     # raise a value error, indicating that the value is not known at compile time
     #
     # @param reason [String] Error message
@@ -461,9 +516,6 @@ module Idl
     #   This is also an opportunity to pre-calculate anything that only needs global symbols
     #
     #   @param global_symtab [SymbolTable] Symbol table with global scope populated
-
-
-    # @!macro freeze_tree
     sig { params(global_symtab: SymbolTable).returns(AstNode) }
     def freeze_tree(global_symtab)
       return self if frozen?
@@ -508,9 +560,6 @@ module Idl
     sig { abstract.returns(String) }
     def to_idl; end
 
-    sig { overridable.returns(String) }
-    def to_idl_verbose = to_idl
-
     # return yaml to indicate where the node comes from
     # the retrun value will be:
     #  file: <path to input file (or nil if input was given as a string)>
@@ -518,11 +567,11 @@ module Idl
     #  end: <0-indexed position of the ending character in the input>
     sig { returns(T::Hash[String, T.untyped]) }
     def source_yaml
-      base_offset = @starting_offset || 0
+      base_offset = source_starting_offset
       interval_begin = T.must(interval).begin
       interval_end = T.must(interval).size == 0 ? T.must(interval).begin + 1 : T.must(interval).end
 
-      lfo = @line_file_offsets
+      lfo = source_line_file_offsets
       if lfo
         # Map an IDL-string position to a file byte offset using the per-line table.
         # Each entry lfo[i] is the file offset of the first character of IDL line i.
@@ -545,12 +594,23 @@ module Idl
       end
 
       {
-        "file" => @input_file.to_s,
+        "file" => T.must(input_file).to_s,
         "begin" => file_begin,
         "end"   => file_end
       }
     end
 
+    sig { returns(Integer) }
+    def source_starting_offset
+      @starting_offset || @parent&.source_starting_offset || 0
+    end
+
+    sig { returns(T.nilable(T::Array[Integer])) }
+    def source_line_file_offsets
+      return @line_file_offsets unless @line_file_offsets.nil?
+      @parent&.source_line_file_offsets
+    end
+
     private
 
     # Given an IDL-string position +pos+ and the per-line file-offset table +lfo+,
@@ -679,7 +739,10 @@ module Idl
   module Executable
     extend T::Sig
     extend T::Helpers
-    interface!
+    abstract!
+
+    sig { returns(T::Boolean).checked(:never) }
+    def executable? = true
 
     # @!macro [new] execute
     #   "execute" the statement by updating the variables in the symbol table
@@ -866,7 +929,10 @@ module Idl
   module Declaration
     extend T::Sig
     extend T::Helpers
-    interface!
+    abstract!
+
+    sig { returns(T::Boolean).checked(:never) }
+    def declaration? = true
 
     # @!macro [new] add_symbol
     #  Add symbol(s) at the outermost scope of the symbol table
@@ -1345,9 +1411,13 @@ module Idl
 
       enums.each { |g| g.add_symbol(symtab); }
       bitfields.each { |g| g.add_symbol(symtab) }
+      # Functions must be registered before globals so that global variable
+      # initializers can call functions (e.g. FLEN = implemented?(...) ? 64 : 32).
+      # FunctionDefAst#add_symbol only stores the FunctionType; it does not
+      # evaluate the body, so adding functions before globals is safe.
+      functions.each { |g| g.add_symbol(symtab) }
       globals.each { |g| g.add_symbol(symtab) }
       structs.each { |g| g.add_symbol(symtab) }
-      functions.each { |g| g.add_symbol(symtab) }
     end
 
     # replaces an include statement with the ast in that file, making
@@ -1424,7 +1494,9 @@ module Idl
         end
       end
 
-      IsaAst.new(input, interval, kids)
+      node = IsaAst.new(input, interval, kids)
+      node.set_input_file(yaml.fetch("source").fetch("file"))
+      node
     end
   end
 
@@ -1499,12 +1571,6 @@ module Idl
     end
   end
 
-  class ArraySizeSyntaxNode < SyntaxNode
-    def to_ast
-      ArraySizeAst.new(input, interval, send(:expression).to_ast)
-    end
-  end
-
   class ArraySizeAst < AstNode
     include Rvalue
 
@@ -1566,25 +1632,21 @@ module Idl
   end
 
 
-  class EnumSizeSyntaxNode < SyntaxNode
-    def to_ast
-      EnumSizeAst.new(input, interval, send(:type_name).to_ast)
-    end
-  end
-
   # represents the builtin that returns the nymber of elements in an enum class
   #
   #  $enum_size(XRegWidth) #=> 2
   class EnumSizeAst < AstNode
     include Rvalue
 
-    def enum_class = children[0]
+    def enum_class = children.fetch(0)
 
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: T.any(IdAst, UserTypeNameAst)).void }
     def initialize(input, interval, enum_class_name)
-      super(input, interval, [enum_class_name])
+      user_type_name = enum_class_name.is_a?(UserTypeNameAst) ? enum_class_name : UserTypeNameAst.new(enum_class_name.input, enum_class_name.interval, enum_class_name.name)
+      super(input, interval, [user_type_name])
     end
 
     def type_check(symtab, strict:)
@@ -1621,17 +1683,11 @@ module Idl
       interval = interval_from_source_yaml(yaml.fetch("source"))
       EnumSizeAst.new(
         input, interval,
-        T.cast(AstNode.from_h(yaml.fetch("enum_class_name"), source_mapper), T.all(Rvalue, AstNode))
+        T.cast(AstNode.from_h(yaml.fetch("enum_class_name"), source_mapper), UserTypeNameAst)
       )
     end
   end
 
-  class EnumElementSizeSyntaxNode < SyntaxNode
-    def to_ast
-      EnumElementSizeAst.new(input, interval, send(:type_name).to_ast)
-    end
-  end
-
   # represents the builtin that returns the bitwidth of an element in an enum class
   #
   #  $enum_element_size(PrivilegeMode) #=> 3
@@ -1643,9 +1699,10 @@ module Idl
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
-    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: UserTypeNameAst).void }
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: T.any(IdAst, UserTypeNameAst)).void }
     def initialize(input, interval, enum_class_name)
-      super(input, interval, [enum_class_name])
+      user_type_name = enum_class_name.is_a?(UserTypeNameAst) ? enum_class_name : UserTypeNameAst.new(enum_class_name.input, enum_class_name.interval, enum_class_name.name)
+      super(input, interval, [user_type_name])
     end
 
     def type_check(symtab, strict:)
@@ -1683,12 +1740,6 @@ module Idl
     end
   end
 
-  class EnumCastSyntaxNode < SyntaxNode
-    def to_ast
-      EnumCastAst.new(input, interval, send(:type_name).to_ast, send(:expression).to_ast)
-    end
-  end
-
   class EnumCastAst < AstNode
     include Rvalue
 
@@ -1696,22 +1747,23 @@ module Idl
     def const_eval?(symtab) = true
 
     # @return [UserTypeAst] Enum name
-    def enum_name = @children[0]
+    def enum_name = @children.fetch(0)
 
     # @return [Rvalue] Value expression
-    def expression = @children[1]
+    def expression = @children.fetch(1)
 
     sig {
       params(
         input: T.nilable(String),
         interval: T.nilable(T::Range[Integer]),
-        type_name: UserTypeNameAst,
+        type_name: T.any(IdAst, UserTypeNameAst),
         expression: RvalueAst
       )
       .void
     }
     def initialize(input, interval, type_name, expression)
-      super(input, interval, [type_name, expression])
+      user_type_name = type_name.is_a?(UserTypeNameAst) ? type_name : UserTypeNameAst.new(type_name.input, type_name.interval, type_name.name)
+      super(input, interval, [user_type_name, expression])
     end
 
     def type_check(symtab, strict:)
@@ -1764,26 +1816,21 @@ module Idl
     end
   end
 
-  class EnumArrayCastSyntaxNode < SyntaxNode
-    def to_ast
-      EnumArrayCastAst.new(input, interval, send(:type_name).to_ast)
-    end
-  end
-
   # represents the builtin that returns an array with all elements of an Enum type
   #
   #  $enum_to_a(PrivilegeMode) #=> [3, 1, 1, 0, 5, 4]
   class EnumArrayCastAst < AstNode
     include Rvalue
 
-    def enum_class = children[0]
+    def enum_class = children.fetch(0)
 
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
-    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: UserTypeNameAst).void }
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), enum_class_name: T.any(IdAst, UserTypeNameAst)).void }
     def initialize(input, interval, enum_class_name)
-      super(input, interval, [enum_class_name])
+      user_type_name = enum_class_name.is_a?(UserTypeNameAst) ? enum_class_name : UserTypeNameAst.new(enum_class_name.input, enum_class_name.interval, enum_class_name.name)
+      super(input, interval, [user_type_name])
     end
 
     def type_check(symtab, strict:)
@@ -2184,49 +2231,50 @@ module Idl
   class BitfieldDefinitionAst < AstNode
     include Declaration
 
+    class Memo < T::Struct
+      prop :type, T.nilable(Type)
+      prop :element_names, T.nilable(T::Array[String])
+      prop :element_ranges, T.nilable(T::Hash[SymbolTable, T::Array[T::Range[Integer]]]), default: {}
+    end
+
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
+    sig { params(input: T.nilable(String), interval: T.nilable(T::Range[Integer]), name: T.any(BuiltinTypeNameAst, UserTypeNameAst), size: IntLiteralAst, fields: T::Array[BitfieldFieldDefinitionAst]).void }
     def initialize(input, interval, name, size, fields)
       super(input, interval, [name, size] + fields)
 
       @name = name
       @size = size
       @fields = fields
+      @memo = Memo.new
     end
 
-    # @!macro freeze_tree
-    def freeze_tree(global_symtab)
-      return if frozen?
-
-      type(global_symtab)
-
-      @children.each { |child| child.freeze_tree(global_symtab) }
-
-      freeze
-    end
-
-    # @return [Integer] The number of bits in the Bitfield
+    # @return The number of bits in the Bitfield
+    sig { params(symtab: SymbolTable).returns(Integer) }
     def size(symtab)
       @size.value(symtab)
     end
 
-    # @return [Array<String>] Array of all element names, in the same order as those from {#element_ranges}
+    # @return Array of all element names, in the same order as those from {#element_ranges}
+    sig { returns(T::Array[String]) }
     def element_names
-      return @element_names unless @element_names.nil?
+      return @memo.element_names unless @memo.element_names.nil?
 
-      @element_names = @fields.map(&:name)
+      @memo.element_names = @fields.map(&:name)
     end
 
     # @return [Array<Range>]
     #    Array of all element ranges, in the same order as those from {#element_names}.
+    sig { params(symtab: SymbolTable).returns(T::Array[T::Range[Integer]]) }
     def element_ranges(symtab)
-      return @element_ranges unless @element_ranges.nil?
+      return @memo.element_ranges[symtab] unless @memo.element_ranges[symtab].nil?
 
-      @element_ranges = @fields.map { |f| f.range(symtab) }
+      @memo.element_ranges[symtab] = @fields.map { |f| f.range(symtab) }
     end
 
     # @!macro type_check
+    sig { override.params(symtab: SymbolTable, strict: T::Boolean).void }
     def type_check(symtab, strict:)
       type_error "Cannot use reserved word '#{name}' as user-defined type name" if ReservedWords::RESERVED.include?(name)
 
@@ -2242,20 +2290,21 @@ module Idl
     end
 
     # @!macro add_symbol
+    sig { override.params(symtab: SymbolTable).void }
     def add_symbol(symtab)
       internal_error "All Bitfields should be declared at global scope" unless symtab.levels == 1
 
       t = type(symtab)
-      internal_error "Type is nil" if t.nil?
 
       symtab.add!(name, t)
     end
 
     # @!macro type_no_args
+    sig { params(symtab: SymbolTable).returns(Type) }
     def type(symtab)
-      return @type unless @type.nil?
+      return @memo.type unless @memo.type.nil?
 
-      @type = BitfieldType.new(
+      @memo.type = BitfieldType.new(
         name,
         @size.value(symtab),
         element_names,
@@ -2264,9 +2313,11 @@ module Idl
     end
 
     # @return [String] bitfield name
+    sig { returns(String) }
     def name = @name.text_value
 
     # @!macro value_no_args
+    sig { params(_symtab: SymbolTable).returns(ValueRbType) }
     def value(_symtab) = raise AstNode::InternalError, "Bitfield definitions have no value"
 
     # @!macro to_idl
@@ -2289,7 +2340,7 @@ module Idl
       "source" => source_yaml
     }
 
-    sig { params(yaml: T::Hash[String, T.untyped], source_mapper: T::Hash[String, String]).returns(AstNode) }
+    sig { override.params(yaml: T::Hash[String, T.untyped], source_mapper: T::Hash[String, String]).returns(AstNode) }
     def self.from_h(yaml, source_mapper)
       raise "Bad YAML" unless yaml.key?("kind") && yaml.fetch("kind") == "bitfield_decl"
 
@@ -2297,8 +2348,8 @@ module Idl
       interval = interval_from_source_yaml(yaml.fetch("source"))
       BitfieldDefinitionAst.new(
         input, interval,
-        AstNode.from_h(yaml.fetch("name"), source_mapper),
-        AstNode.from_h(yaml.fetch("size"), source_mapper),
+        T.cast(AstNode.from_h(yaml.fetch("name"), source_mapper), T.any(BuiltinTypeNameAst, UserTypeNameAst)),
+        T.cast(AstNode.from_h(yaml.fetch("size"), source_mapper), IntLiteralAst),
         yaml.fetch("fields").map { |f| AstNode.from_h(f, source_mapper) }
       )
     end
@@ -2481,7 +2532,12 @@ module Idl
 
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab)
-      if var.name == "X"
+      var_type = begin
+        var.type(symtab)
+      rescue AstNode::TypeError, AstNode::InternalError
+        nil
+      end
+      if var_type.is_a?(Type) && var_type.kind == :array && var_type.sub_type.is_a?(RegFileElementType) && var_type.qualifiers.include?(:global)
         false
       else
         var.const_eval?(symtab) && index.const_eval?(symtab)
@@ -2546,7 +2602,12 @@ module Idl
       if var.type(symtab).integral?
         (var_val >> index.value(symtab)) & 1
       else
-        value_error "X registers are not compile-time-known" if var.text_value == "X"
+        var_type = begin
+          var.type(symtab)
+        rescue AstNode::TypeError, AstNode::InternalError
+          nil
+        end
+        value_error "Register file registers are not compile-time-known" if var_type.is_a?(Type) && var_type.kind == :array && var_type.sub_type.is_a?(RegFileElementType) && var_type.qualifiers.include?(:global)
 
         # internal_error "Not an array" unless ary.type.kind == :array
 
@@ -2591,7 +2652,12 @@ module Idl
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab)
       v = var
-      if v.is_a?(IdAst) && v.name == "X"
+      var_type = begin
+        v.type(symtab)
+      rescue AstNode::TypeError, AstNode::InternalError
+        nil
+      end
+      if var_type.is_a?(Type) && var_type.kind == :array && var_type.sub_type.is_a?(RegFileElementType) && var_type.qualifiers.include?(:global)
         false
       else
         v.const_eval?(symtab) && msb.const_eval?(symtab).const_eval? && lsb.const_eval?(symtab)
@@ -2855,12 +2921,6 @@ module Idl
     end
   end
 
-  class AryElementAssignmentSyntaxNode < SyntaxNode
-    def to_ast
-      AryElementAssignmentAst.new(input, interval, send(:var).to_ast, send(:idx).to_ast, send(:rval).to_ast)
-    end
-  end
-
   # represents an array element assignment
   #
   # for example:
@@ -2875,8 +2935,10 @@ module Idl
       if idx.const_eval?(symtab) && rhs.const_eval?(symtab)
         true
       else
-        lhs_var = symtab.get(lhs.name)
-        type_error "array #{lhs.name} has not been declared" if lhs_var.nil?
+        base_name = AstNode.extract_base_var_name(lhs)
+        type_error "Cannot determine base variable for #{lhs.text_value}" if base_name.nil?
+        lhs_var = symtab.get(base_name)
+        type_error "array #{base_name} has not been declared" if lhs_var.nil?
 
         lhs_var.const_incompatible!
         false
@@ -2942,13 +3004,15 @@ module Idl
           value_error "right-hand side of array element assignment is unknown"
         end
       when :bits
-        var = symtab.get(lhs.text_value)
         value_result = value_try do
-          v = rhs.value(symtab)
-          var.value = (lhs.value(symtab) & ~0) | ((v & 1) << idx.value(symtab))
+          new_element = (lhs.value(symtab) & ~0) | ((rhs.value(symtab) & 1) << idx.value(symtab))
+          AstNode.write_back_nested(lhs, new_element, symtab)
         end
         value_else(value_result) do
-          var.value = nil
+          base_name = T.must(AstNode.extract_base_var_name(lhs))
+          v = symtab.get(base_name)
+          internal_error "did not find array base '#{base_name}'" if v.nil?
+          v.value = nil
         end
       else
         internal_error "unexpected type for array element assignment"
@@ -2985,7 +3049,27 @@ module Idl
 
   class AryRangeAssignmentSyntaxNode < SyntaxNode
     def to_ast
-      AryRangeAssignmentAst.new(input, interval, send(:var).to_ast, send(:msb).to_ast, send(:lsb).to_ast, send(:rval).to_ast)
+      var = send(:var).to_ast
+      brackets = send(:brackets).elements
+
+      # Build access chain for all but the last bracket
+      brackets[0..-2].each do |bracket|
+        var =
+          if bracket.msb.empty?
+            AryElementAccessAst.new(input, interval, var, bracket.lsb.to_ast)
+          else
+            AryRangeAccessAst.new(input, interval, var,
+                                  bracket.msb.expression.to_ast, bracket.lsb.to_ast)
+          end
+      end
+
+      # Use accumulated `var` for the assignment target
+      last_bracket = brackets[-1]
+      if last_bracket.msb.empty?
+        AryElementAssignmentAst.new(input, interval, var, last_bracket.lsb.to_ast, send(:rval).to_ast)
+      else
+        AryRangeAssignmentAst.new(input, interval, var, last_bracket.msb.expression.to_ast, last_bracket.lsb.to_ast, send(:rval).to_ast)
+      end
     end
   end
 
@@ -3003,8 +3087,10 @@ module Idl
       if lsb.const_eval?(symtab) && msb.const_eval?(symtab) && write_value.const_eval?(symtab)
         true
       else
-        lhs_var = symtab.get(variable.name)
-        type_error "array #{variable.name} has not be declared" if lhs_var.nil?
+        base_name = AstNode.extract_base_var_name(variable)
+        type_error "Cannot determine base variable for #{variable.text_value}" if base_name.nil?
+        lhs_var = symtab.get(base_name)
+        type_error "array #{base_name} has not be declared" if lhs_var.nil?
 
         lhs_var.const_incompatible!
         false
@@ -3062,26 +3148,29 @@ module Idl
     def execute(symtab)
       return if variable.type(symtab).global?
 
-      var = symtab.get(variable.name)
-      internal_error "Variable #{variable.name} not found" if var.nil?
-
       value_result = value_try do
-        var_val = variable.value(symtab)
-
         msb_val = msb.value(symtab)
         lsb_val = lsb.value(symtab)
 
         type_error "MSB (#{msb_val}) is <= LSB (#{lsb_val})" if msb_val <= lsb_val
 
         rval_val = write_value.value(symtab)
-
         mask = ((1 << (msb_val - lsb_val + 1)) - 1) << lsb_val
 
-        var.value = (var_val & ~mask) | ((rval_val << lsb_val) & mask)
+        # Read current value, modify bits
+        var_val = variable.value(symtab)
+        var_val &= ~mask
+        new_val = var_val | ((rval_val << lsb_val) & mask)
+
+        # Write back through the access chain
+        AstNode.write_back_nested(variable, new_val, symtab)
         :ok
       end
       value_else(value_result) do
-        var.value = nil
+        base_name = T.must(AstNode.extract_base_var_name(variable))
+        v = symtab.get(base_name)
+        internal_error "did not find array base" if v.nil?
+        v.value = nil
         value_error "Either the range or right-hand side of an array range assignment is unknown"
       end
     end
@@ -3219,7 +3308,13 @@ module Idl
         var.value = bitfield_val
       elsif var.type.kind == :struct
         struct_val = id.value(symtab)
-        struct_val[@field_name] = rhs.value(symtab)
+        value_result = value_try do
+          struct_val[@field_name] = rhs.value(symtab)
+        end
+        value_else(value_result) do
+          struct_val[@field_name] = nil
+          value_error ""
+        end
       else
         value_error "TODO: Field assignment execution"
       end
@@ -5275,6 +5370,10 @@ module Idl
     # @!macro value
     def value(symtab) = expression.value(symtab)
 
+    def max_value(symtab) = expression.max_value(symtab)
+
+    def min_value(symtab) = expression.min_value(symtab)
+
     # @!macro to_idl
     sig { override.returns(String) }
     def to_idl = "(#{expression.to_idl})"
@@ -5704,6 +5803,120 @@ module Idl
     end
   end
 
+  # Generic syntax node for $name(arg, ...) — dispatches to the correct typed AstNode in to_ast.
+  class DollarFunctionCallSyntaxNode < SyntaxNode
+    def to_ast
+      dollar_name = "$#{send(:name).text_value}"
+      arg_nodes = dollar_arg_list_elements
+      enum_type_name_validation = {
+        0 => {
+          classes: [IdAst, UserTypeNameAst],
+          description: "an identifier or user type name"
+        }
+      }
+
+      case dollar_name
+      when "$width"             then builtin_call_ast(dollar_name, arg_nodes, 1, WidthRevealAst)
+      when "$signed"            then builtin_call_ast(dollar_name, arg_nodes, 1, SignCastAst)
+      when "$bits"              then builtin_call_ast(dollar_name, arg_nodes, 1, BitsCastAst)
+      when "$enum_size"         then builtin_call_ast(dollar_name, arg_nodes, 1, EnumSizeAst, enum_type_name_validation)
+      when "$enum_element_size" then builtin_call_ast(dollar_name, arg_nodes, 1, EnumElementSizeAst, enum_type_name_validation)
+      when "$enum_to_a"         then builtin_call_ast(dollar_name, arg_nodes, 1, EnumArrayCastAst, enum_type_name_validation)
+      when "$enum"              then builtin_call_ast(dollar_name, arg_nodes, 2, EnumCastAst, enum_type_name_validation)
+      when "$array_size"        then builtin_call_ast(dollar_name, arg_nodes, 1, ArraySizeAst)
+      when "$array_includes?"   then builtin_call_ast(dollar_name, arg_nodes, 2, ArrayIncludesAst)
+      else
+        ParseTimeDetectedTypeError.new(input, interval, "#{dollar_name} is not a builtin function")
+      end
+    end
+
+    private
+
+    def builtin_call_ast(dollar_name, arg_nodes, expected_arg_count, ast_class, arg_type_validations = {})
+      if arg_nodes.size != expected_arg_count
+        ParseTimeDetectedTypeError.new(input, interval, "#{dollar_name} expects #{expected_arg_count} argument#{expected_arg_count == 1 ? "" : "s"}; #{arg_nodes.size} given")
+      else
+        arg_asts = arg_nodes.first(expected_arg_count).map(&:to_ast)
+
+        arg_type_validations.each do |arg_index, validation|
+          next if validation[:classes].any? { |klass| arg_asts[arg_index].is_a?(klass) }
+
+          return ParseTimeDetectedTypeError.new(
+            input,
+            interval,
+            "#{dollar_name} expects argument #{arg_index + 1} to be #{validation[:description]}; #{builtin_arg_type_name(arg_asts[arg_index])} given"
+          )
+        end
+
+        ast_class.new(input, interval, *arg_asts)
+      end
+    end
+
+    def builtin_arg_type_name(arg_ast)
+      arg_ast.class.name.split("::").last
+    end
+
+    private
+
+    def dollar_arg_list_elements
+      arg_list = send(:args)
+      first = arg_list.first
+      rest = arg_list.rest.elements.map { |e| e.expression }
+      first.empty? ? rest : [first] + rest
+    end
+
+  end
+
+  # Generic syntax node for $name (no parens) — creates a BuiltinVariableAst.
+  class DollarVariableSyntaxNode < SyntaxNode
+    def to_ast
+      BuiltinVariableAst.new(input, interval, "$#{send(:name).text_value}")
+    end
+  end
+
+  # Syntax node for $name = expr — dispatches to PcAssignmentAst for $pc,
+  class DollarVariableAssignmentSyntaxNode < SyntaxNode
+    def to_ast
+      dollar_name = "$#{send(:dollar_variable).send(:name).text_value}"
+      rhs = send(:rval).to_ast
+      case dollar_name
+      when "$pc"
+        PcAssignmentAst.new(input, interval, rhs)
+      else
+        ParseTimeDetectedTypeError.new(input, interval, "#{dollar_name} is not assignable")
+      end
+    end
+  end
+
+  # AstNode for an error detected during to_ast. Always causes a type error
+  class ParseTimeDetectedTypeError < AstNode
+
+    sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
+    def const_eval?(symtab) = true
+
+    def initialize(input, interval, reason)
+      super(input, interval, EMPTY_ARRAY)
+      @reason = reason
+    end
+
+    sig { override.params(symtab: SymbolTable, strict: T::Boolean).void }
+    def type_check(symtab, strict:)
+      type_error @reason
+    end
+
+    sig { params(symtab: SymbolTable).returns(Type) }
+    def type(symtab) = type_error(@reason)
+
+    sig { params(symtab: SymbolTable).returns(T.untyped) }
+    def value(symtab) = value_error "Can't take value of a type error"
+
+    sig { override.returns(String) }
+    def to_idl = text_value
+
+    sig { override.returns(T::Hash[String, T.untyped]) }
+    def to_h = { "kind" => "ParseTimeDetectedTypeError", "reason" => @reason, "source" => source_yaml }
+  end
+
   class PostIncrementExpressionSyntaxNode < SyntaxNode
     def to_ast
       PostIncrementExpressionAst.new(input, interval, send(:rval).to_ast)
@@ -5848,7 +6061,9 @@ module Idl
         range = T.cast(obj.type(symtab), BitfieldType).range(@field_name)
         (T.cast(obj.value(symtab), Integer) >> range.first) & ((1 << range.size) - 1)
       elsif kind(symtab) == :struct
-        T.cast(obj.value(symtab), T::Hash[String, BasicValueRbType])[@field_name]
+        field_val = T.cast(obj.value(symtab), T::Hash[String, BasicValueRbType])[@field_name]
+        value_error "#{@field_name} is not known at compile-time" if field_val.nil?
+        field_val
       else
         type_error "#{obj.text_value} is Not a bitfield."
       end
@@ -6263,6 +6478,34 @@ module Idl
       end
     end
 
+    # @!macro max_value
+    def max_value(symtab)
+      value_result = value_try do
+        cond = condition.value(symtab)
+        return cond ? true_expression.max_value(symtab) : false_expression.max_value(symtab)
+      end
+      value_else(value_result) do
+        t = true_expression.max_value(symtab)
+        f = false_expression.max_value(symtab)
+        return :unknown if t == :unknown || f == :unknown
+        [t, f].max
+      end
+    end
+
+    # @!macro min_value
+    def min_value(symtab)
+      value_result = value_try do
+        cond = condition.value(symtab)
+        return cond ? true_expression.min_value(symtab) : false_expression.min_value(symtab)
+      end
+      value_else(value_result) do
+        t = true_expression.min_value(symtab)
+        f = false_expression.min_value(symtab)
+        return :unknown if t == :unknown || f == :unknown
+        [t, f].min
+      end
+    end
+
     # @!macro to_idl
     sig { override.returns(String) }
     def to_idl = "#{condition.to_idl} ? #{true_expression.to_idl} : #{false_expression.to_idl}"
@@ -6354,10 +6597,10 @@ module Idl
 
     # @!macro execute
     def execute(symtab)
-      if action.is_a?(Declaration)
+      if action.declaration?
         action.add_symbol(symtab)
       end
-      if action.is_a?(Executable)
+      if action.executable?
         action.execute(symtab)
       end
     end
@@ -6410,7 +6653,7 @@ module Idl
     # @!macro type_check
     def type_check(symtab, strict:)
       action.type_check(symtab, strict:)
-      type_error "Cannot declare from a conditional statement" if action.is_a?(Declaration)
+      type_error "Cannot declare from a conditional statement" if action.declaration?
 
       condition.type_check(symtab, strict:)
       type_error "condition is not boolean" unless condition.type(symtab).convertable_to?(:boolean)
@@ -6938,6 +7181,10 @@ module Idl
   #  * U64 (Bits<64>)
   class BuiltinTypeNameAst < AstNode
 
+    class Memo < T::Struct
+      prop :bits_type, T::Hash[SymbolTable, T.nilable(Type)], default: {}
+    end
+
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = (@type_name == "bits") ? bits_expression.const_eval?(symtab) : true
 
@@ -6950,6 +7197,7 @@ module Idl
         super(input, interval, [bits_expression])
       end
       @type_name = type_name
+      @memo = Memo.new
     end
 
     # @!macro type_check
@@ -6970,21 +7218,19 @@ module Idl
       end
     end
 
-    def freeze_tree(symtab)
-      return if frozen?
-
-      if @type_name == "Bits"
-        # precalculate size if possible
+    sig { params(symtab: SymbolTable).returns(Type) }
+    def bits_type(symtab)
+      @memo.bits_type[symtab] ||=
         begin
-          value_try do
-            @bits_type = Type.new(:bits, width: bits_expression.value(symtab))
+          t = T.let(nil, T.nilable(Type))
+          value_result = value_try do
+            t = Type.new(:bits, width: bits_expression.value(symtab))
           end
-        rescue TypeError
-          # ok, probably using a parameter
+          value_else(value_result) do
+            t = Type.new(:bits, width: :unknown, width_ast: bits_expression)
+          end
+          T.must(t)
         end
-        bits_expression&.freeze_tree(symtab)
-      end
-      freeze
     end
 
     # @!macro type
@@ -7008,14 +7254,7 @@ module Idl
       when "String"
         StringType
       when "Bits"
-        return @bits_type unless @bits_type.nil?
-
-        value_result = value_try do
-          return Type.new(:bits, width: bits_expression.value(symtab))
-        end
-        value_else(value_result) do
-          return Type.new(:bits, width: :unknown, width_ast: bits_expression)
-        end
+        bits_type(symtab)
       else
         internal_error "TODO: #{text_value}"
       end
@@ -7241,6 +7480,13 @@ module Idl
   class IntLiteralAst < AstNode
     include Rvalue
 
+    class Memo < T::Struct
+      prop :type, T.nilable(Type)
+      prop :width, T.nilable(T.any(Integer, Symbol))
+      prop :value, T.nilable(T.any(Integer, UnknownLiteral))
+      prop :unsigned_value, T.nilable(T.any(Integer, UnknownLiteral))
+    end
+
     sig { override.params(symtab: SymbolTable).returns(T::Boolean) }
     def const_eval?(symtab) = true
 
@@ -7248,19 +7494,11 @@ module Idl
     def initialize(input, interval, text)
       @text = text
       super(input, interval, EMPTY_ARRAY)
+      @memo = Memo.new
     end
 
     def text_value = @text
 
-    def freeze_tree(global_symtab)
-      return if frozen?
-
-      # initialize the cached objects
-      type(global_symtab)
-      value(global_symtab)
-      freeze
-    end
-
     # @!macro type_check
     def type_check(symtab, strict:)
       if text_value.delete("_") =~ /^((MXLEN)|([0-9]+))?'(s?)([bodh]?)(.*)$/
@@ -7279,7 +7517,7 @@ module Idl
 
     # @!macro type
     def type(symtab)
-      return @type unless @type.nil?
+      return @memo.type unless @memo.type.nil?
 
       case text_value.delete("_")
       when /^((MXLEN)|([0-9]+))?'(s?)([bodh]?)(.*)$/
@@ -7295,7 +7533,7 @@ module Idl
 
         qualifiers = signed == "s" ? [:signed, :const] : [:const]
         qualifiers << :known unless T.must(value).include?("x")
-        @type =
+        @memo.type =
           if width == :unknown
             Type.new(:bits, width:, max_width: 64, qualifiers:)
           else
@@ -7306,20 +7544,20 @@ module Idl
         signed = ::Regexp.last_match(3)
 
         qualifiers = signed == "s" ? [:signed, :const, :known] : [:const, :known]
-        @type = Type.new(:bits, width: width(symtab), qualifiers:)
+        @memo.type = Type.new(:bits, width: width(symtab), qualifiers:)
       when /^([0-9]*)(s?)$/
         # basic decimal
         signed = ::Regexp.last_match(2)
 
         qualifiers = signed == "s" ? [:signed, :const, :known] : [:const, :known]
-        @type = Type.new(:bits, width: width(symtab), qualifiers:)
+        @memo.type = Type.new(:bits, width: width(symtab), qualifiers:)
       else
         internal_error "Unhandled int value '#{text_value}'"
       end
     end
 
     def width(symtab)
-      return @width unless @width.nil?
+      return @memo.width unless @memo.width.nil?
 
       text_value_no_underscores = text_value.delete("_")
 
@@ -7336,21 +7574,21 @@ module Idl
         else
           width = width.to_i
         end
-        @width = width
+        @memo.width = width
       when /^0([bdx]?)([0-9a-fA-F]*)(s?)$/
         signed = ::Regexp.last_match(3)
 
         width = signed == "s" ? value(symtab).bit_length + 1 : value(symtab).bit_length
         width = 1 if width.zero? # happens when the literal is '0'
 
-        @width = width
+        @memo.width = width
       when /^([0-9]*)(s?)$/
         signed = ::Regexp.last_match(3)
 
         width = signed == "s" ? value(symtab).bit_length + 1 : value(symtab).bit_length
         width = 1 if width.zero? # happens when the literal is '0'
 
-        @width = width
+        @memo.width = width
       else
         internal_error "No match on int literal"
       end
@@ -7358,7 +7596,7 @@ module Idl
 
     # @!macro value
     def value(symtab)
-      return @value unless @value.nil?
+      return @memo.value unless @memo.value.nil?
 
       if text_value.delete("_") =~ /^((MXLEN)|([0-9]+))?'(s?)([bodh]?)(.*)$/
         # verilog-style literal
@@ -7396,18 +7634,18 @@ module Idl
             end
           end
 
-        @value = v
+        @memo.value = v
       else
-        @value = unsigned_value
+        @memo.value = unsigned_value
       end
     end
 
 
     # @return [Integer] the unsigned value of this literal (i.e., treating it as unsigned even if the signed specifier is present)
     def unsigned_value
-      return @unsigned_value unless @unsigned_value.nil?
+      return @memo.unsigned_value unless @memo.unsigned_value.nil?
 
-      @unsigned_value =
+      @memo.unsigned_value =
         case text_value.delete("_")
         when /^((MXLEN)|([0-9]+))?'(s?)([bodh]?)(.*)$/
           # verilog-style literal
@@ -7487,15 +7725,6 @@ module Idl
     sig { override.returns(String) }
     def to_idl = text_value
 
-    sig { override.returns(String) }
-    def to_idl_verbose
-      if @width == :unknown
-        "MXLEN'#{@type.signed? ? 's' : ''}d#{unsigned_value}"
-      else
-        "#{@width}'#{@type.signed? ? 's' : ''}d#{unsigned_value}"
-      end
-    end
-
     sig { returns(T::Boolean) }
     def signed?
       case text_value.delete("_")
@@ -7900,7 +8129,7 @@ module Idl
       stmts.each do |s|
         if s.is_a?(Returns)
           return s.return_type(symtab)
-        elsif s.action.is_a?(Declaration)
+        elsif s.action.declaration?
           s.action.add_symbol(symtab)
         end
       end
@@ -9284,15 +9513,6 @@ module Idl
       @memo = Memo.new
     end
 
-    def freeze_tree(symtab)
-      return if frozen?
-
-      type_error "CSR '#{@csr_name}' is not defined" unless symtab.csr?(@csr_name)
-
-      @children.each { |child| child.freeze_tree(symtab) }
-      freeze
-    end
-
     # @!macro type
     def type(symtab) = @memo.type ||= CsrType.new(csr_def(symtab))