182 lines
5.5 KiB
Markdown
182 lines
5.5 KiB
Markdown
<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
|
|
|
|
|
|
#### 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)
|