added README.md + format.md
This commit is contained in:
parent
d34ce4efd2
commit
b6e9c6f4db
GPG Key ID:
8D83DE470F8544E7
159
README.md
Normal file
159
README.md
Normal file
@ -0,0 +1,159 @@
|
||||
### rivet - Register / Instruction Visualizer and Explainer Tool
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
BIN
example_blueprint.png
Normal file
BIN
example_blueprint.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
BIN
example_dark.png
Normal file
BIN
example_dark.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
BIN
example_normal.png
Normal file
BIN
example_normal.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
BIN
example_transparent.png
Normal file
BIN
example_transparent.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 43 KiB |
125
format.md
Normal file
125
format.md
Normal file
@ -0,0 +1,125 @@
|
||||
# Schema Format
|
||||
|
||||
_**Supported syntaxes: JSON, XML, YAML**_
|
||||
|
||||
The following description uses the JSON syntax
|
||||
|
||||
For examples in different formats, see [example1.yaml](example1.yaml), [example2.yaml](example2.yaml), [example3.json](example3.json) and [example4.xml](example4.xml).
|
||||
|
||||
## Main layout
|
||||
|
||||
A schema contains a dictionary of structures. There must be at least one defined structure named "main"
|
||||
```json
|
||||
{
|
||||
"structures": {
|
||||
"main": {
|
||||
...
|
||||
},
|
||||
"struct1": {
|
||||
...
|
||||
},
|
||||
"struct2": {
|
||||
...
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Structure
|
||||
|
||||
A structure has a given number of bits and one or multiple ranges. Each range of bits can have a name, a description and / or values with special meaning (see [Range](#range)). A range's structure can also depend on another range's value (see [Dependencies](#dependencies))
|
||||
|
||||
The range name (or key) defines the left- and rightmost bits (e.g. 7-4 goes from bit 7 to bit 4). Bits are displayed in big-endian, i.e. the leftmost bit has the highest value.
|
||||
```json
|
||||
"main": {
|
||||
"bits": 8,
|
||||
"ranges": {
|
||||
"7-4": {
|
||||
...
|
||||
},
|
||||
"3-2": {
|
||||
...
|
||||
},
|
||||
"1": {
|
||||
...
|
||||
},
|
||||
"0": {
|
||||
...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Range
|
||||
|
||||
A range represents a group of consecutive bits. It can have a name (display in the bit cells), a description (displayed under the structure) and / or values.
|
||||
|
||||
For values depending on other ranges, see [Dependencies](#dependencies).
|
||||
|
||||
> **Note**<br>
|
||||
> In YAML, make sure to wrap values in quotes because some values can be interpreted as octal notation (e.g. 010)
|
||||
|
||||
```json
|
||||
"3-2": {
|
||||
"name": "op",
|
||||
"description": "Logical operation",
|
||||
"values": {
|
||||
"00": "AND",
|
||||
"01": "OR",
|
||||
"10": "XOR",
|
||||
"11": "NAND"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
The structure of one range may depend on the value of another. To represent this situation, first indicate on the child range the range on which it depends:
|
||||
|
||||
```json
|
||||
"7-4": {
|
||||
...
|
||||
"depends-on": "0"
|
||||
}
|
||||
```
|
||||
|
||||
Then, in its values, indicate which structure to use. A description can also be added (displayed above the horizontal dependency arrow)
|
||||
|
||||
```json
|
||||
"7-4": {
|
||||
...
|
||||
"depends-on": "0",
|
||||
"values": {
|
||||
"0": {
|
||||
"description": "immediate value",
|
||||
"structure": "immediateValue"
|
||||
},
|
||||
"1": {
|
||||
"description": "value in register",
|
||||
"structure": "registerValue"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, add the sub-structures to the structure dictionary:
|
||||
|
||||
```json
|
||||
{
|
||||
"structures": {
|
||||
"main": {
|
||||
...
|
||||
},
|
||||
"immediateValue": {
|
||||
"bits": 4,
|
||||
...
|
||||
},
|
||||
"registerValue": {
|
||||
"bits": 4,
|
||||
...
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user