yarig 0.13.0

A register interface generator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# YARIG: Yet Another Register Interface Generator

YARIG is a code generation tool to describe register interface of an IP or ASIC/FPGA design.

This allows to have one common source to describes registers for all the different views:
 - Hardware: for the actual hardware implementation (SystemVerilog and VHDL)
 - Software: for interacting with the register such a C header, UVM RAL, python classes, ...
 - Documentation: for readable description (HTML/Latex/...)

More details on targets are available in [hardware targets](doc/package.md)
and [other targets](doc/targets.md).

## Description Language
YARIG uses its own file format named `.rif` to describe the registers.

The objectives when designing the language were:
 - Must be easy to read and write
 - Simple registers (read/write or read-only) should be described in a single line
 - Offers fine control on the generated hardware
 - Allow re-use and hierarchical description

Complete details are available in the [syntax page](doc/syntax.md)

### Syntax example

Here is a simple RIF definition:
```
rif: test_rif
  addrWidth: 8
  dataWidth: 16
  - Main:
    registers:
      - ctrl: "Basic control register"
        - en      = 0    0:0        "Block enable"
        - start   = 0    0:0  pulse "Start block"
        - version = 0x12 15:8 ro    "Block version"
          hw na
      - interrupt: "Interrupt register"
        interrupt rising en=0x13 mask=0x37 pending w1clr
        enable.description "Enable interrupt"
        mask.description "Mask interrupt"
        pending.description "Pending interrupt"
        - gen   = 0 7:0 rw "Generic Events"
        - busy  = 0 8:8 "Busy"
        - ready = 0 9:9 "Ready"
      - status: "Status register"
        - state  3:0 "Current state"
        - success 4:4 "Last operation succeed"
        - failed  5:5 "Last operation failed"
    instances: auto
```

Highlighting for SublimeText is available on [github](https://github.com/TheClams/rif).

### Why another language ?

Of all existing approach, I think that only SystemRDL comes close to covering all the features I need.
The idea of separating register definition and instance is key to allow re-use amongst different project.
But the main weakness of SystemRDL (in my opinion) is that the syntax is neither easy to read nor easy to write.

How simpler is the RIF syntax compare to the SystemRDL is quite subjective, but like can be seen in the syntax example
it is quite compact when defining simple register, with default behavior that should intuitive.
For example, if there is no reset value an no hardware/software defined, then it is assumed this is a read-only register driven by hardware.

In term of features missing from SystemRDL, the main one I have identified are:
  - Overriding default precedence hw/sw, paritycheck field
  - Automatic control of endianness
  - Definition of HDL path, constraint

But I think RIF has a few improved featured (in no particular order) :
  - RIF mapping: it is possible to defines the whole register map of a SoC by instantiating multiple RIFs.
  - Fine control over both the hardware register structure and its software mapping: instead of defining a whole register structure
    which is then mapped automatically on address aligned with the software bus, the definition of register must be aligned on the software bus,
    but each register can have a group name so that they appear in the same structure in hardware.
  - fine control of clock/reset used per register/field: there is still the hypothesis that all clock are synchronous but it is easy to have fields driven by different clock/reset.
  - pulse field can be defined as combinatorial or register
  - password field: allows to set high an internal signal only when a given value is written.
    This allows to protect some register against write access until the password is written, useful for critical register related to power or clock tree for example.
  - limit property: allows to ensure only a subset of value can be written in a register
  - enum can have a representation value on top of their encoded integer value. (for example `CR_1_2 = 1 (0.5) "Coderate 1/2" `)
  - Defining number of fractional bits associated with a field: allows to define reset value in a more intuitive way when the register represent fixed-point values
  - Control visibility of description: when generating documentation for public purposes, sometimes is is useful to hide some register,
    some part of the description, or automatically rename fields as `reserved_xx` to allow access without exposing the full meaning behind the register


## Configuration
 A configuration file allows to specify many options of the generators like the RIF file, a list of target, the output path for each targets, ...

Here is an example:
```
filename = "my_chip.rif"
gen_inc = ["*"]
targets = ["py", "sv", "html", "latex", "c"]

[suffixes.spi]
name = "full"
pkg = true

[outputs]
doc = "../yarig/doc"
c = "../yarig/c"
py = "../yarig/py"
rtl = "../yarig/rtl"
sim = "../yarig/sim"
vhdl = "../yarig/vhdl"
```

Most settings from the configuration file can be overriden by command-line arguments. Run `yarig -h` to list all available options.

## Generator Traits

To streamline the developement of new output targets, the library contains three base generator traits,
which basically go through the different elements of the structure and apply the visibility checks (public/private).
The exact behavior of each traits can be tweaked with some associated constant.

### Software

### Hardware

### Documentation

---
# TODO

## Feature
 - [x] Improve nb_frac support:
   - [x] Support reset value in floating-point
   - [x] Use floating-point value in documentation when nb_frac is non-zero (and use a tool-tip in html to display corresponding integer value)
 - [ ] Support for generics
 - [x] Support reset value as enum name
 - [ ] Support pipe option RTL
 - [ ] Support option to repeat field description for interrupt derived register
 - [x] Support latex equation in description
 - [ ] Support overlapping register in hardware. Exclusive access (RO/WO) is already check at compile time: might be a good place to add some overlap flag to ease the generator job ...
 - [ ] Check enum size matches the field size
 - [ ] Option to add representation value for enum. Syntax could be 'NAME = VAL (repr) "description"'. Could be usefull when enum is representing a limited set of integer or real values.
   - [x] Update parser to support new syntax
   - [x] Add python function in the enum class for conversion to/from float
   - [ ] Add C function for conversion to/from float/int ? Would need to add option to the generator allowing to disable the feature, use int, float or double as the representation type
 - [ ] Option to control if clear works without clock enable or not

## Documentation
 - [x] Config file: full description
 - [ ] Base generator trait
 - [x] Why Yarig vs other existing solution (mostly SystemRDL)
 - [ ] List of syntax example for typical use-cases

## Known Bugs / Edge cases
 - [ ] Support partial fields arrays
 - [ ] Support partial counter (for counter larger than register size)
 - [x] Add parsing of LogicExpr (currently logic expression works only for SystemVerilog)
 - [x] Add check on password not being partial fields