rivet/format.md

Schema Format

Supported syntaxes: JSON, XML, YAML

The following description uses the JSON syntax

For examples in different formats, see example1.yaml, example2.yaml, example3.json and example4.xml.

Main layout

A schema contains a dictionary of structures. There must be at least one defined structure named "main"

{
  "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). A range's structure can also depend on another range's value (see 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.

"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.

Note

In YAML, make sure to wrap values in quotes because some values can be interpreted as octal notation (e.g. 010)

"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:

"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)

"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:

{
  "structures": {
    "main": {
      ...
    },
    "immediateValue": {
      "bits": 4,
      ...
    },
    "registerValue": {
      "bits": 4,
      ...
    },
    ...
  }
}