rivet - Register / Instruction Visualizer and Explainer Tool
---
## Table of contents
* [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)
---
## 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)):
Show / hide
```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
```
#### config.json
#### dark.json
#### blueprint.json
#### transparent.json
## 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)