Skip to content
STIMSMITH

JSON program representation

Concept WIKI v1 · 6/1/2026

A JSON-based intermediate format used by OTBN's random instruction generator. `otbn-rig gen` emits random programs in this format, and `otbn-rig asm` deterministically translates it to assembly (and optionally a linker script). The representation models a generated program as a tree of snippets and may change over time.

Overview

The JSON program representation is the format written by otbn-rig gen when it generates a random OTBN program. The same representation is consumed by otbn-rig asm, which translates it into an assembly listing and, when requested, a linker script. The documentation explicitly notes that this JSON format may change over time, but it is understood by the asm command.

Structure

The generated program is built from blocks called snippets. The JSON output format represents the program as a tree of snippets.

The simplest snippet is a straight-line sequence of instructions, but the representation also covers more complex control-flow constructs such as conditional branches and loops.

Size semantics

otbn-rig gen accepts a --size parameter that controls how large the program grows. Size is defined in terms of snippets:

  • A snippet with one unconditionally executed instruction has size 1.
  • A straight-line snippet with N instructions has size N.
  • For a branch-shaped snippet such as if (A) { B; } else { C; }, where evaluating A takes a cycles and the branch bodies have sizes b and c, the snippet size is a + max(b, c).

More generally, snippet size is intended as an upper bound on the number of instructions a snippet causes the processor to execute, though the documentation notes that this bound is not necessarily strict in every case.

Behavioral constraints of represented programs

Programs emitted into this JSON representation are designed not to trigger architecturally unspecified behavior. They may still trigger errors, but their execution is not supposed to depend on undefined factors such as the initial contents of the register file or uninitialized memories.

To support load generation even near the start of execution, generated programs also include a few words of randomly initialized data scattered around DMEM.

Consumption by otbn-rig asm

The asm subcommand performs a deterministic translation from the JSON input to assembly and linker-script output; unlike gen, it does no random generation. With --output, it produces a .s assembly file and a .ld linker script. Without --output, it prints only the assembly listing to stdout.

LINKED ENTITIES

2 links
otbn-rig USES
snippet PART_OF

CITATIONS

5 sources
5 citations
[1] `otbn-rig gen` writes a random program to stdout in JSON format, and this format is understood by `otbn-rig asm`, though it may change over time. OTBN Random Instruction Generator - OpenTitan
[2] The JSON output format represents the generated program as a tree of snippets. OTBN Random Instruction Generator - OpenTitan
[3] Snippet size is used to control program growth: single-instruction snippets have size 1, straight-line snippets of `N` instructions have size `N`, and an if/else-style snippet has size `a + max(b, c)`; size is intended as an upper bound on executed instructions, though not always a strict one. OTBN Random Instruction Generator - OpenTitan
[4] Programs represented in this JSON format are designed not to trigger architecturally unspecified behavior, though they may still trigger errors; generated programs also include a few words of randomly initialized data scattered around DMEM. OTBN Random Instruction Generator - OpenTitan
[5] `otbn-rig asm` performs a deterministic translation from JSON input to assembly and linker-script output; with `--output` it writes `.s` and `.ld` files, and without `--output` it prints the assembly listing to stdout. OTBN Random Instruction Generator - OpenTitan