systemrdl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef8e253b49ef4971248d9e4ad7b1938ff69952613de40fb985e993653ebd37f2
+  data.tar.gz: f7c11c7334b79e9c93e81a5b2ccc211d15c3e7991ca514385f3525deb9316bd8
+SHA512:
+  metadata.gz: 60382cdccb4df5c4d9df37a988e0d62d0986c7d2bb7de98add2f706f93349f57e4b0783f2f1660ccb039c7f463c3cfb03b439c2d5429a535063f8344743a152f
+  data.tar.gz: 766461e671109a8813e5a39a4f5a4cdd640ebdc2c32de76a31969404317a709aa7a52fbc580ec42229317ecae4fe98f1c7c9ac326c686df70eb4cf42e6146acc

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Taichi Ishitani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+[![Gem Version](https://badge.fury.io/rb/systemrdl.svg)](https://badge.fury.io/rb/systemrdl)
+[![Regression](https://github.com/taichi-ishitani/systemrdl/actions/workflows/regression.yml/badge.svg?branch=master)](https://github.com/taichi-ishitani/systemrdl/actions/workflows/regression.yml)
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/A0A231E3I)
+
+# SystemRDL
+
+A SystemRDL 2.0 front-end for Ruby.
+It parses SystemRDL source, elaborates the described register model, and exposes it as plain Ruby objects so that back-end tools can generate RTL, documentation, software headers, and so on.
+
+SystemRDL is a register description language standardized by [Accellera](https://www.accellera.org/activities/working-groups/systemrdl).
+This gem targets the [SystemRDL 2.0 specification](https://www.accellera.org/images/downloads/standards/systemrdl/SystemRDL_2.0_Jan2018.pdf).
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add systemrdl
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install systemrdl
+```
+
+## Usage
+
+### Compiling SystemRDL
+
+Use the methods below to compile SystemRDL into an elaborated model.
+Each method returns a list of the top-level address maps.
+
+* Compile SystemRDL read from the given file path(s)
+    * `SystemRDL.compile`
+* Compile SystemRDL read from the given input stream(s)
+    * `SystemRDL.compile_streams`
+* Compile the given SystemRDL source string
+    * `SystemRDL.compile_source`
+
+`SystemRDL.compile` and `SystemRDL.compile_streams` accept multiple inputs.
+The inputs are compiled in the given order and share their component definitions, so a component defined in an earlier input can be instantiated in a later one.
+Note that this sharing is one-directional; an earlier input cannot refer to a component defined in a later one.
+
+```ruby
+require 'systemrdl'
+
+# Compile files
+address_maps = SystemRDL.compile('gpio.rdl', 'pwm.rdl')
+
+# Compile a source string
+address_maps = SystemRDL.compile_source(<<~'RDL')
+  addrmap my_map {
+    reg {
+      field { sw = rw; hw = r; reset = 0x0; } value[32];
+    } data;
+  };
+RDL
+```
+
+### Accessing the model
+
+An elaborated model is a tree of address maps, registers, and fields.
+Each element carries the properties assigned to it in the source.
+
+```ruby
+require 'systemrdl'
+
+address_map = SystemRDL.compile_source(<<~'RDL').first
+  addrmap gpio {
+    name = "GPIO";
+    desc = "Simple general purpose I/O controller";
+
+    default sw = rw;
+    default hw = r;
+
+    reg {
+      name = "Port Direction";
+      field { desc = "0: input, 1: output"; reset = 0x0; } dir[32];
+    } direction;
+
+    reg {
+      name = "Input Data";
+      field { sw = r; hw = w; } value[32];
+    } data_in;
+  };
+RDL
+
+# GPIO: Simple general purpose I/O controller
+puts "#{address_map.display_name}: #{address_map.desc}"
+
+address_map.regs.each do |reg|
+  # direction @ 0x0
+  # data_in @ 0x4
+  puts "#{reg.name} @ 0x#{reg.address.to_s(16)}"
+
+  reg.fields.each do |field|
+    # dir [31:0] sw=rw hw=r
+    # value [31:0] sw=r hw=w
+    puts "  #{field.name} [#{field.msb}:#{field.lsb}] sw=#{field.sw} hw=#{field.hw}"
+  end
+end
+```
+
+## Scope
+
+This gem currently supports only the basic syntax needed to describe register maps that consist of address maps, registers, and fields.
+More advanced constructs of the SystemRDL language are not supported yet.
+
+## Design notes
+
+The design decisions behind this implementation, along with their rationale, are documented under the [`notes`](notes) directory.
+These notes focus on parts of the SystemRDL specification that are open to interpretation or left unspecified, and explain how this implementation resolves them.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/taichi-ishitani/systemrdl.
+
+* [Issue Tracker](https://github.com/taichi-ishitani/systemrdl/issues)
+* [Pull Request](https://github.com/taichi-ishitani/systemrdl/pulls)
+* [Discussion](https://github.com/taichi-ishitani/systemrdl/discussions)
+
+## Copyright & License
+
+Copyright &copy; 2026 Taichi Ishitani.
+SystemRDL is licensed under the terms of the [MIT License](https://opensource.org/licenses/MIT), see [LICENSE.txt](LICENSE.txt) for further details.

data/lib/systemrdl/error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SystemRDL
+  class Error < StandardError
+    def initialize(message)
+      super
+      @error_message = message
+    end
+
+    attr_reader :error_message
+  end
+
+  class ParseError < Error
+    def initialize(message, position)
+      super(message)
+      @position = position
+    end
+
+    attr_reader :position
+
+    def to_s
+      (@position && "#{super} -- #{@position}") || super
+    end
+  end
+
+  module RaiseParseError
+    private
+
+    def raise_parse_error(message, position)
+      raise ParseError.new(message, position)
+    end
+  end
+
+  class EvaluationError < Error
+    def initialize(message, *token_ranges)
+      super(message)
+      @token_ranges = token_ranges.compact
+    end
+
+    attr_reader :token_ranges
+
+    def to_s
+      position = token_ranges.first&.head&.position
+      (position && "#{super} -- #{position}") || super
+    end
+  end
+
+  module RaiseEvaluationError
+    private
+
+    def raise_evaluation_error(message, *token_ranges)
+      raise EvaluationError.new(message, *token_ranges)
+    end
+  end
+end

data/lib/systemrdl/evaluator/address_allocation.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module SystemRDL
+  module Evaluator
+    module AddressAllocation
+      private
+
+      def allocate_addresses(instance)
+        address = 0
+        instance.instances.each do |child_inst|
+          # For now, support reg only
+          next unless child_inst.reg?
+
+          assign_address(address, instance, child_inst)
+          address = calc_next_address(child_inst)
+        end
+      end
+
+      def assign_address(current_address, inst, child_inst)
+        if child_inst.first_element?
+          child_inst.address ||= begin
+            alignment = calc_alignment(inst, child_inst)
+            address = roundup(current_address, alignment)
+            Value.new(address, :bit, 64, nil)
+          end
+        else
+          # Array non-head elements carry a copy of the head's @ address at this point;
+          # overwrite with the stride-accumulated address for this element.
+          child_inst.address = Value.new(current_address, :bit, 64, nil)
+        end
+      end
+
+      def calc_alignment(inst, child_inst)
+        inst_alignment = child_inst.alignment&.value
+        return inst_alignment if inst_alignment
+
+        alignments = [
+          inst.property_value(:alignment)&.value || 0,
+          child_inst.accesswidth / 8,
+          alignment_by_addressing(inst, child_inst)
+        ]
+        alignments.max
+      end
+
+      def alignment_by_addressing(inst, child_inst)
+        addressing = inst.property_value(:addressing).value
+        case addressing
+        when :compact then child_inst.accesswidth / 8
+        when :regalign then aligned_size(child_inst)
+        when :fullalign then calc_fullalign_alignment(child_inst)
+        end
+      end
+
+      def calc_fullalign_alignment(child_inst)
+        return aligned_size(child_inst) unless child_inst.array?
+
+        array_size = calc_occupied_size(child_inst)
+        if power_of_2?(array_size, 1)
+          array_size
+        else
+          2**array_size.bit_length
+        end
+      end
+
+      def calc_next_address(child_inst)
+        delta =
+          if child_inst.last_element?
+            child_inst.size
+          else
+            element_stride(child_inst)
+          end
+        child_inst.address.value + delta
+      end
+
+      def check_overlapping_regs(instance)
+        # For now, support reg only but not regfile
+        regs = instance.instances.select { |reg| reg.reg? && reg.first_element? }
+        regs.combination(2).each do |(reg_a, reg_b)|
+          next unless overlapping_pair?(reg_a, reg_b)
+
+          message = 'overlapping regs not allowed'
+          raise_evaluation_error message, reg_a.token_range, reg_b.token_range
+        end
+      end
+
+      def overlapping_pair?(reg_a, reg_b)
+        range_a = calc_address_range(reg_a)
+        range_b = calc_address_range(reg_b)
+        return false unless range_a.include?(range_b.begin) || range_b.include?(range_a.begin)
+
+        r_a = reg_a.sw_readable?
+        w_a = reg_a.sw_writable?
+        r_b = reg_b.sw_readable?
+        w_b = reg_b.sw_writable?
+        (r_a && r_b) || (w_a && w_b)
+      end
+
+      def calc_address_range(child_inst)
+        base = child_inst.address.value
+        size = calc_occupied_size(child_inst)
+        base...(base + size)
+      end
+
+      def roundup(dividend, divisor)
+        divisor * dividend.ceildiv(divisor)
+      end
+
+      def aligned_size(child_inst)
+        roundup(child_inst.size, child_inst.accesswidth / 8)
+      end
+
+      def calc_occupied_size(child_inst)
+        if child_inst.array?
+          n_elements = child_inst.array_info.n_elements
+          ((n_elements - 1) * element_stride(child_inst)) + child_inst.size
+        else
+          child_inst.size
+        end
+      end
+
+      def element_stride(child_inst)
+        child_inst.stride&.value || aligned_size(child_inst)
+      end
+    end
+  end
+end

data/lib/systemrdl/evaluator/address_operation.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SystemRDL
+  module Evaluator
+    module AddressOperation
+      private
+
+      def apply_explicit_address(instance, inst_values)
+        address = inst_values[:address_assignment]
+        return unless address
+
+        instance.address = address
+      end
+
+      def apply_stride(instance, inst_values)
+        stride = inst_values[:address_stride]
+        return unless stride
+
+        unless instance.array?
+          message = "address stride not allowed for scalar #{layer} instance"
+          raise_evaluation_error message, stride.token_range
+        end
+
+        instance.stride = stride
+      end
+
+      def apply_alignment(instance, inst_values)
+        alignment = inst_values[:address_alignment]
+        return unless alignment
+
+        instance.alignment = alignment
+      end
+
+      def apply_address_operations(instance, inst_values)
+        apply_explicit_address(instance, inst_values)
+        apply_stride(instance, inst_values)
+        apply_alignment(instance, inst_values)
+
+        return unless instance.address && instance.alignment
+
+        message = '@ and %= address operations are mutually exclusive'
+        raise_evaluation_error message, instance.address.token_range, instance.alignment.token_range
+      end
+
+      def check_range(inst_values)
+        range = inst_values[:range]
+        return unless range
+
+        message = "range not allowed for #{layer} instance"
+        raise_evaluation_error message, range.token_range
+      end
+
+      def check_accesswidth_boundary(instance, label, value)
+        return unless value
+
+        accesswidth = instance.accesswidth
+        return if (value.value % (accesswidth / 8)) == 0
+
+        message =
+          "#{label} not aligned to accesswidth: " \
+          "#{label} 0x#{value.value.to_s(16)} accesswidth #{accesswidth}"
+        raise_evaluation_error message, value.token_range
+      end
+
+      def check_address(instance)
+        check_accesswidth_boundary(instance, :address, instance.address)
+      end
+
+      def check_stride(instance)
+        stride = instance.stride
+        return unless stride
+
+        check_accesswidth_boundary(instance, :stride, stride)
+
+        size = instance.size
+        return if stride.value >= size
+
+        message =
+          "stride less than #{instance.layer} size: " \
+          "stride 0x#{stride.value.to_s(16)} #{instance.layer} size #{size}"
+        raise_evaluation_error message, stride.token_range
+      end
+
+      def check_alignment(instance)
+        alignment = instance.alignment
+        return unless alignment
+
+        check_accesswidth_boundary(instance, :alignment, alignment)
+
+        return if alignment.value > 0
+
+        message = 'alignment must be positive'
+        raise_evaluation_error message, alignment.token_range
+      end
+
+      def check_address_operations(instance)
+        check_address(instance)
+        check_stride(instance)
+        check_alignment(instance)
+      end
+    end
+  end
+end

data/lib/systemrdl/evaluator/addrmap.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SystemRDL
+  module Evaluator
+    class AddrMapDefinition < ComponentDefinition
+      include AddressAllocation
+      include ContainerComponent
+
+      def evaluate(instance, **optargs)
+        if instance.root?
+          create_instance(instance, @id, nil, nil, nil, **optargs)
+        else
+          super
+        end
+      end
+
+      def validate(instance)
+        check_structural_component_instances(instance)
+        check_alignment(instance)
+        check_endianness_exclusivity(instance)
+        check_rsvdset_exclusivity(instance)
+        check_bit_ordering_exclusivity(instance)
+      end
+
+      def finalize(instance)
+        allocate_addresses(instance)
+        check_overlapping_regs(instance)
+      end
+
+      def layer
+        :addrmap
+      end
+
+      private
+
+      def instance_class
+        AddrMapInstance
+      end
+
+      def check_alignment(instance)
+        check_power_of_2(instance, :alignment, 1)
+      end
+
+      def check_endianness_exclusivity(instance)
+        check_property_exclusivity(instance, [:bigendian, :littleendian])
+      end
+
+      def check_rsvdset_exclusivity(instance)
+        check_property_exclusivity(instance, [:rsvdset, :rsvdsetX])
+      end
+
+      def check_bit_ordering_exclusivity(instance)
+        check_property_exclusivity(instance, [:msb0, :lsb0])
+      end
+    end
+
+    class AddrMapInstance < Instance
+      def definable?(definition)
+        definition.layer in :addrmap | :regfile | :reg | :field
+      end
+
+      def instantiable?(definition)
+        definition.layer in :addrmap | :regfile | :reg
+      end
+    end
+  end
+end

data/lib/systemrdl/evaluator/array_component.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SystemRDL
+  module Evaluator
+    ArrayInfo = Data.define(:id, :indices, :sizes, :first, :last) do
+      def n_elements
+        sizes.inject(:*)
+      end
+    end
+
+    module ArrayComponent
+      private
+
+      def eval_array(inst_values)
+        array = inst_values[:array]
+        return super unless array
+
+        sizes = array.elements.map do |size|
+          next size.value if size.value > 0
+
+          message = 'array size must be positive'
+          raise_evaluation_error message, size.token_range
+        end
+
+        index_list =
+          sizes
+            .map { |size| size.times.to_a }
+            .then { |list| list[0].product(*list[1..]) }
+        id = array_id
+        index_list.each.with_index(1) do |indices, i|
+          info = ArrayInfo.new(id, indices, sizes, i == 1, i == index_list.size)
+          yield(info)
+        end
+      end
+
+      def array_id
+        @array_id ||= - 1
+        @array_id += 1
+      end
+    end
+  end
+end