OTBN Random Instruction Generator

This directory contains a random instruction generator for OTBN. There is a wrapper at ../otbn-rig. Example usage:

./hw/ip/otbn/util/otbn-rig -o x.json --asm-output x.asm

This generates an assembly file (x.asm) containing a random program. When assembled, loaded into OTBN and executed, the execution trace should contain roughly 100 instructions. To override this default, pass the --size parameter.

The random program is built from blocks called “snippets”. The simplest possible snippet is a single instruction but more complicated snippets like short instruction sequences, if/else branches or function calls are possible. The implementation doesn’t currently do this, but eventually it will generate trees of snippets. For example, there might be an if/else branch where each arm contains a sequence of instructions described by a separate snippet.

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:

    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.

JSON output

As well as an assembly file, the example above generates a JSON file as output. This contains a description of the snippets that form the generated program. One way to use these snippets is to build a program: indeed, that’s what the instruction generator does internally.

However, the snippets contain more structured information about the program and its control flow than just an assembly file. This should eventually allow “advanced” tricks such as test case shrinking or maybe test case mutation for fuzzing.

At the moment, we don’t do anything with the JSON output, but’s it’s quite handy for debugging the generation process.