rivet/README.md

<h3>rivet - Register / Instruction Visualizer and Explainer Tool</h3>

---
## Table of contents
<!-- TOC -->
  * [Table of contents](#table-of-contents)
  * [Introduction](#introduction)
  * [Requirements](#requirements)
  * [Usage](#usage)
  * [Options](#options)
  * [Examples](#examples)
      * [config.json](#configjson)
      * [dark.json](#darkjson)
      * [blueprint.json](#blueprintjson)
      * [transparent.json](#transparentjson)
  * [Config](#config)
<!-- TOC -->

---

## Introduction

This tool lets you generate visual explanations of binary instructions, or describe the contents of a register.

The layout and style can be customized to fit your needs.

For a full description of the schema format, please check out [format.md](format.md)

## Requirements

- [Python 3+](https://www.python.org/)
- [Pygame](https://pypi.org/project/pygame/) - used to render the images
- [Beautiful Soup 4](https://pypi.org/project/beautifulsoup4/) - used to parse XML files
- [PyYAML](https://pypi.org/project/PyYAML/) - used to parse YAML files

## Usage

Basic usage:
```bash
python3 main.py schema.xml
```

Directory mode + config:
```bash
python3 main.py -o out/ -c config.json -d schemas/
```

## Options

Several command line options are available:
- `-o PATH` sets the output path. If not given, the output file will be located in the same directory as the input file, and given the same name (different extension)
- `-d` enables directory mode. If set, the input and output paths are directories and all files inside the input directory are processed
- `-c PATH` sets the config path. For more details on available config parameters, please read the [Config section](#config).

## Examples

The following images were generated from this schema ([example1.yaml](example1.yaml)):

<details>
<summary>Show / hide</summary>

```yaml
structures:
  main:
    bits: 32
    ranges:
      31-28:
        name: cond
      27:
        name: 0
      26:
        name: 1
      25:
        name: I
      24:
        name: P
        description: pre / post indexing bit
        values:
          0: post, add offset after transfer
          1: pre, add offset before transfer
      23:
        name: U
        description: up / down bit
        values:
          0: down, subtract offset from base
          1: up, addition offset to base
      22:
        name: B
        description: byte / word bit
        values:
          0: transfer word quantity
          1: transfer byte quantity
      21:
        name: W
        description: write-back bit
        values:
          0: no write-back
          1: write address into base
      20:
        name: L
        description: load / store bit
        values:
          0: store to memory
          1: load from memory
      19-16:
        name: Rn
        description: base register
      15-12:
        name: Rd
        description: source / destination register
      11-0:
        name: offset
        depends-on: 25
        values:
          0:
            description: offset is an immediate value
            structure: immediateOffset
          1:
            description: offset is a register
            structure: registerOffset
  immediateOffset:
    bits: 12
    ranges:
      11-0:
        name: 12-bit immediate offset
        description: unsigned number
  registerOffset:
    bits: 12
    ranges:
      11-4:
        name: shift
        description: shift applied to Rm
      3-0:
        name: Rm
        description: offset register
```
</details>

#### config.json
![default black on white](example_normal.png)

#### dark.json
![white on black](example_dark.png)

#### blueprint.json
![white on blue](example_blueprint.png)

#### transparent.json
![grey on transparent](example_transparent.png)

## Config

The config file may change the following values to customize the layout and style:
- `defaultFontFamily`: the default font family
- `defaultFontSize`: the default font size
- `italicFontFamily`: the italic font family (for value description)
- `italicFontSize`: the italic font size
- `backgroundColor`: the image background color (ex: [222, 250, 206])
- `textColor`: the default text color
- `linkColor`: the color of linking lines and arrows
- `borderColor`: the color of register borders
- `bitWidth`: the width of 1 bit (in pixels)
- `bitHeight`: the height of 1 bit (in pixels)
- `descriptionMargin`: the space between descriptions (in pixels)
- `dashLength`: the length of one dash (for dashed lines)
- `dashSpace`: the space between dashes (for dashed lines)
- `arrowSize`: the arrow size (height in pixels, width for horizontal arrow)
- `margins`: the margins from the borders of the image (in pixels, [top, right, bottom, left])
- `arrowMargin`: the margin between arrows and registers (in pixels)
- `valuesGap`: the gap between values (in pixels)
- `arrowLabelDistance`: the distance between arrows and their label (in pixels)
- `forceDescsOnSide`: if true, descriptions are placed on the side of the register, otherwise, they are placed as close as possible to the bit
- `leftLabels`: if true, descriptions are put on the left, otherwise, they default to the right hand side
- `width`: the image width (in pixels)
- `height`: the image height (in pixels)

Some config examples are already included:
- [config.json](config.json): Default configuration values (black on white)
- [dark.json](dark.json): Dark theme (white on black)
- [blueprint.json](blueprint.json): Blueprint theme (white on blue)
- [transparent.json](transparent.json): Transparent background, for easy integration in other documents (grey on transparent)