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)

format.md

@@ -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,
+      ...
+    },
+    ...
+  }
+}
+```