added README.md + format.md

README.md

@@ -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
+![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)