hw/ip/otbn/dv/rig/README.md

# OTBN Random Instruction Generator

This directory contains a random instruction generator for OTBN called
`otbn-rig`. This is intended to be run in multiple phases. If you just
want to generate some random binaries, it might be easier to call the
wrapper at `../uvm/gen-binaries.py`.

At the moment, there are two sub-commands: `gen` and `asm`. In future,
we might add more (to do things like test case mutation or shrinking).

## The gen command

The `gen` command is in charge of actually generating a random
program. This program is written to stdout in an JSON format. This
format may change over time, but it is understood by the `asm`
command.

Example usage:
```
hw/ip/otbn/dv/rig/otbn-rig gen --seed 123 --size 1000 >foo.json
```

To control random generation, there is a `--seed` parameter. The
output should be stable for a fixed seed. If not specified, the seed
is zero.

### The size parameter

The `--size` parameter is used to control how big the program grows. A
snippet with a single unconditionally executed instruction has a size
of one. A snippet containing a sequence of `N` instructions has a size
of `N`. For a more interesting example, consider an if/else branch
that would look something like this in C:

```C
    if (A) {
        B;
    } else {
        C;
    }
```

If calculating `A` takes `a` cycles and `B` and `C` have a size of `b`
and `c` respectively, then the entire snippet has size `a + max(b,
c)`. The general idea is that the size taken by a snippet is an upper
bound on the number of instructions that it causes the processor to
execute. This might not be a strict upper bound: for example, it won't
be strict if `a != b` in the if/else snippet above.

### Snippets

The random program is built from blocks called "snippets". The
simplest possible snippet is a sequence of straight-line instructions.
There are also more complicated snippets like conditional branches and
loops. The JSON output format represents this tree of snippets.

### Initialised data

The generated program is designed never to trigger architecturally
unspecified behaviour. It might trigger errors, but its execution will
never depend on things like the initial contents of the register file
or uninitialised memories.

To provide some data so that RIG can generate load instructions even
near the start of the run, the generated program also includes a few
words of (randomly) initialised data, scattered around dmem.

## The asm command

Once a random program has been generated, the `asm` command can be
used to convert it to an assembly listing. This, in turn, can be
assembled and linked using the toolchain in `hw/ip/otbn/util`.

Unlike the `gen` command, this step does no random generation: it's a
deterministic translation from the JSON input to assembly and linker
script output.

Example usage:
```
hw/ip/otbn/dv/rig/otbn-rig asm --output foo foo.json
```

When given the `--output` parameter, this command generates two output
files. With `--output foo`, it generates `foo.s` and `foo.ld`. These
are an assembly listing and a linker script, respectively.

To assemble and link, use commands like:
```
hw/ip/otbn/util/otbn_as.py -o foo.o foo.s
hw/ip/otbn/util/otbn_ld.py -o foo.elf -T foo.ld foo.o
```
This is automated in the `gen-binaries.py` wrapper described above.

Occasionally, it's helpful to just read the assembly listing for a
JSON file. To do this, run the command with no `--output` parameter to
see the assembly listing on stdout. The linker script will not be
generated.