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. This gem targets the SystemRDL 2.0 specification.

Installation

Install the gem and add it to the application's Gemfile by executing:

bundle add systemrdl

If bundler is not being used to manage dependencies, install the gem by executing:

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.

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.

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

Supported Features

The following SystemRDL 2.0 language features are supported (parsed and evaluated).

Components

The addrmap, regfile, reg, field, and mem components
Definitive and anonymous component definitions/instances
Arrays of instances
Address allocation operators (@, +=, %=)
internal / external instance types

Properties

Most built-in properties of the supported components, except the counter and interrupt property groups (see below)
Property assignment in all three forms: direct assignment, default assignment (default), and dynamic assignment (->)
Property references and instance references as property values

Unsupported Features

The following features are not supported. Some of their keywords are recognized by the lexer (reserved), but they are not evaluated.

signal component
User-defined properties (property definitions)
Enumerations (enum) and encode
struct types
constraint
alias registers
Counter field properties
Interrupt field properties
Component parameters
Preprocessing, both embedded Perl preprocessing and Verilog-style directives

Design notes

The design decisions behind this implementation, along with their rationale, are documented under the 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.