Compare commits
5 Commits
9f8bf02522
...
v0.0.2
Author | SHA1 | Date | |
---|---|---|---|
b8a84b1430 | |||
94d4ac8328
|
|||
01fe756862
|
|||
995564382a
|
|||
7c62a16146
|
@ -1,9 +1,11 @@
|
|||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
## [v0.0.2] - _WIP_
|
## [v0.0.2] - 2024-06-15
|
||||||
### Added
|
### Added
|
||||||
- `width` parameter to `schema.render` for easier integration
|
- `width` parameter to `schema.render` for easier integration
|
||||||
- `all-bit-i` config option
|
- `all-bit-i` config option
|
||||||
|
- colored ranges
|
||||||
|
- format specification in the manual
|
||||||
|
|
||||||
## [v0.0.1] - 2024-05-19
|
## [v0.0.1] - 2024-05-19
|
||||||
- initial version
|
- initial version
|
||||||
|
@ -101,5 +101,11 @@
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
},
|
||||||
|
"colors": {
|
||||||
|
"main": {
|
||||||
|
"31-28": "#FF0000",
|
||||||
|
"11-4": [34, 176, 43]
|
||||||
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
BIN
gallery/test.pdf
BIN
gallery/test.pdf
Binary file not shown.
@ -65,4 +65,7 @@
|
|||||||
<description>offset register</description>
|
<description>offset register</description>
|
||||||
</range>
|
</range>
|
||||||
</structure>
|
</structure>
|
||||||
|
<color structure="main" color="#FF0000" start="28" end="31" />
|
||||||
|
<color structure="main" color="#255961" start="4" end="11" />
|
||||||
|
<color structure="immediateOffset" color="89,97,37" start="4" end="11" />
|
||||||
</schema>
|
</schema>
|
@ -71,3 +71,11 @@ structures:
|
|||||||
3-0:
|
3-0:
|
||||||
name: Rm
|
name: Rm
|
||||||
description: offset register
|
description: offset register
|
||||||
|
|
||||||
|
colors:
|
||||||
|
main:
|
||||||
|
31-28: "#3EFA6B"
|
||||||
|
25-23:
|
||||||
|
- 100
|
||||||
|
- 150
|
||||||
|
- 200
|
BIN
manual.pdf
BIN
manual.pdf
Binary file not shown.
196
manual.typ
196
manual.typ
@ -1,4 +1,6 @@
|
|||||||
#import "@preview/tidy:0.3.0"
|
#import "@preview/tidy:0.3.0"
|
||||||
|
#import "@preview/codelst:2.0.1": sourcecode
|
||||||
|
#import "@preview/showybox:2.0.1": showybox
|
||||||
#import "src/lib.typ"
|
#import "src/lib.typ"
|
||||||
#import "src/schema.typ"
|
#import "src/schema.typ"
|
||||||
#import "docs/examples.typ"
|
#import "docs/examples.typ"
|
||||||
@ -26,13 +28,26 @@
|
|||||||
link(label(label-name))[#display-name]
|
link(label(label-name))[#display-name]
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#let note(it) = showybox(
|
||||||
|
title: "Note",
|
||||||
|
title-style: (
|
||||||
|
color: white,
|
||||||
|
weight: "bold"
|
||||||
|
),
|
||||||
|
frame: (
|
||||||
|
title-color: blue.lighten(30%),
|
||||||
|
border-color: blue.darken(40%)
|
||||||
|
),
|
||||||
|
it
|
||||||
|
)
|
||||||
|
|
||||||
#show link: set text(blue)
|
#show link: set text(blue)
|
||||||
|
|
||||||
= Introduction
|
= Introduction
|
||||||
|
|
||||||
This package provides a way to make beautiful register diagrams using the CeTZ package. It can be used to document Assembly instructions or binary registers
|
This package provides a way to make beautiful register diagrams using the CeTZ package. It can be used to document Assembly instructions or binary registers
|
||||||
|
|
||||||
This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst. For more information on the schema format, please check out the original project's #link("https://git.kb28.ch/HEL/rivet/src/branch/main/format.md")[format.md]
|
This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python script] for Typst.
|
||||||
|
|
||||||
= Usage
|
= Usage
|
||||||
|
|
||||||
@ -43,6 +58,185 @@ Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse
|
|||||||
#schema.render(doc)
|
#schema.render(doc)
|
||||||
```]
|
```]
|
||||||
|
|
||||||
|
= Format
|
||||||
|
|
||||||
|
This section describes the structure of a schema definition. The examples given use the JSON syntax. For examples in different formats, see #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.yaml")[test.yaml], #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.json")[test.json] and #link("https://git.kb28.ch/HEL/rivet-typst/src/branch/main/gallery/test.xml")[test.xml]. You can also directly define a schema using Typst dictionaries and arrays.
|
||||||
|
|
||||||
|
Since the XML format is quite different from the other, you might find it helpful to look at the examples on GitHub to get familiar with it.
|
||||||
|
|
||||||
|
== Main layout
|
||||||
|
|
||||||
|
A schema contains a dictionary of structures. The must be at least one defined structure named "main".
|
||||||
|
|
||||||
|
It can also optionnaly contain a "colors" dictionary. More details about this in #link(<format-colors>)[Colors]
|
||||||
|
|
||||||
|
#sourcecode[```json
|
||||||
|
{
|
||||||
|
"structures": {
|
||||||
|
"main": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"struct1": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"struct2": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```]
|
||||||
|
|
||||||
|
#pagebreak(weak: true)
|
||||||
|
|
||||||
|
== Structure <format-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 #link(<format-range>)[Range]). A range's structure can also depend on another range's value (see #link(<format-dependencies>)[Dependencies]).
|
||||||
|
|
||||||
|
The range name (or key) defines the left- and rightmost bits (e.g. `7-4` goes from bit 7 down to bit 4). Bits are displayed in big-endian, i.e. the leftmost bit has the highest value.
|
||||||
|
|
||||||
|
#sourcecode[```json
|
||||||
|
"main": {
|
||||||
|
"bits": 8,
|
||||||
|
"ranges": {
|
||||||
|
"7-4": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"3-2": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"1": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"0": {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```]
|
||||||
|
|
||||||
|
== Range <format-range>
|
||||||
|
|
||||||
|
A range represents a group of consecutive bits. It can have a name (displayed in the bit cells), a description (displayed under the structure) and / or values.
|
||||||
|
|
||||||
|
For values depending on other ranges, see #link(<format-dependencies>)[Dependencies].
|
||||||
|
|
||||||
|
#note[
|
||||||
|
In YAML, make sure to wrap values in quotes because some values can be interpreted as octal notation (e.g. 010 #sym.arrow.r 8)
|
||||||
|
]
|
||||||
|
|
||||||
|
#sourcecode[```json
|
||||||
|
"3-2": {
|
||||||
|
"name": "op",
|
||||||
|
"description": "Logical operation",
|
||||||
|
"values": {
|
||||||
|
"00": "AND",
|
||||||
|
"01": "OR",
|
||||||
|
"10": "XOR",
|
||||||
|
"11": "NAND"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```]
|
||||||
|
|
||||||
|
#pagebreak(weak: true)
|
||||||
|
|
||||||
|
== Dependencies <format-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.
|
||||||
|
|
||||||
|
Then, in its values, indicate which structure to use. A description can also be added (displayed above the horizontal dependency arrow)
|
||||||
|
|
||||||
|
#sourcecode[```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:
|
||||||
|
|
||||||
|
#sourcecode[```json
|
||||||
|
{
|
||||||
|
"structures": {
|
||||||
|
"main": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"immediateValue": {
|
||||||
|
"bits": 4,
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"registerValue": {
|
||||||
|
"bits": 4,
|
||||||
|
...
|
||||||
|
},
|
||||||
|
...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```]
|
||||||
|
|
||||||
|
#pagebreak(weak: true)
|
||||||
|
|
||||||
|
== Colors <format-colors>
|
||||||
|
|
||||||
|
You may want to highlight some ranges to make your diagram more readable. For this, you can use colors. Colors may be defined in a separate dictionary, at the same level as the "structures" dictionary:
|
||||||
|
|
||||||
|
#sourcecode[```json
|
||||||
|
{
|
||||||
|
"structures": {
|
||||||
|
...
|
||||||
|
},
|
||||||
|
"colors": {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```]
|
||||||
|
|
||||||
|
It can contain color definitions for any number of ranges. For each range, you may then define a dictionary mapping bit ranges to a particular color:
|
||||||
|
|
||||||
|
#sourcecode[```json
|
||||||
|
"colors": {
|
||||||
|
"main": {
|
||||||
|
"31-28": "#ABCDEF",
|
||||||
|
"27-20": "12,34,56"
|
||||||
|
},
|
||||||
|
"registerValue": {
|
||||||
|
"19-10": [12, 34, 56]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```]
|
||||||
|
|
||||||
|
Valid color formats are:
|
||||||
|
- hex string starting with `#`, e.g. `"#23fa78"`
|
||||||
|
- array of three integers (only JSON, YAML and Typst), e.g. `[35, 250, 120]`
|
||||||
|
- string of three comma-separated integers (useful for XML), e.g. `"35,250,120"`
|
||||||
|
- a Typst color (only Typst), e.g. `colors.green` or `rgb(35, 250, 120)`
|
||||||
|
|
||||||
|
#note[
|
||||||
|
The XML format implements colors a bit differently. Instead of having a "colors" dictionary, color definitions are directly put on the same level as structure definitions. For this, you can use a `color` node with the attributes "structure", "color", "start" and "end", like so:
|
||||||
|
#sourcecode[```xml
|
||||||
|
<schema>
|
||||||
|
<structure id="main" bits="8">
|
||||||
|
...
|
||||||
|
</structure>
|
||||||
|
...
|
||||||
|
<color structure="main" color="#FF0000" start="4" end="7" />
|
||||||
|
<color structure="main" color="255,0,0" start="0" end="3" />
|
||||||
|
</schema>
|
||||||
|
```]
|
||||||
|
]
|
||||||
|
|
||||||
|
#pagebreak(weak: true)
|
||||||
|
|
||||||
= Config presets
|
= Config presets
|
||||||
|
|
||||||
Aside from the default config, some example presets are also provided:
|
Aside from the default config, some example presets are also provided:
|
||||||
|
@ -50,6 +50,28 @@
|
|||||||
parse-raw(path-or-schema)
|
parse-raw(path-or-schema)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
if "colors" in schema {
|
||||||
|
for struct in schema.colors.keys() {
|
||||||
|
for (span, col) in schema.colors.at(struct) {
|
||||||
|
if type(col) == str {
|
||||||
|
if col.starts-with("#") {
|
||||||
|
col = rgb(col)
|
||||||
|
} else {
|
||||||
|
let (r, g, b) = col.split(",").map(v => int(v))
|
||||||
|
col = rgb(r, g, b)
|
||||||
|
}
|
||||||
|
} else if type(col) == array {
|
||||||
|
col = rgb(..col)
|
||||||
|
} else if type(col) != color {
|
||||||
|
panic("Invalid color format")
|
||||||
|
}
|
||||||
|
schema.colors.at(struct).at(span) = col
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
schema.insert("colors", (:))
|
||||||
|
}
|
||||||
|
|
||||||
let structures = (:)
|
let structures = (:)
|
||||||
for (id, data) in schema.structures {
|
for (id, data) in schema.structures {
|
||||||
id = str(id)
|
id = str(id)
|
||||||
|
@ -83,8 +83,10 @@
|
|||||||
|
|
||||||
#let parse(content) = {
|
#let parse(content) = {
|
||||||
let struct-elmts = content.children.filter(e => "tag" in e and e.tag == "structure")
|
let struct-elmts = content.children.filter(e => "tag" in e and e.tag == "structure")
|
||||||
|
let color-elmts = content.children.filter(e => "tag" in e and e.tag == "color")
|
||||||
|
|
||||||
let structures = (:)
|
let structures = (:)
|
||||||
|
let colors = (:)
|
||||||
|
|
||||||
for struct-elmt in struct-elmts {
|
for struct-elmt in struct-elmts {
|
||||||
structures.insert(
|
structures.insert(
|
||||||
@ -93,8 +95,19 @@
|
|||||||
)
|
)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
for color-elmt in color-elmts {
|
||||||
|
let struct = color-elmt.attrs.structure
|
||||||
|
if not struct in colors {
|
||||||
|
colors.insert(struct, (:))
|
||||||
|
}
|
||||||
|
|
||||||
|
let span = color-elmt.attrs.end + "-" + color-elmt.attrs.start
|
||||||
|
colors.at(struct).insert(span, color-elmt.attrs.color)
|
||||||
|
}
|
||||||
|
|
||||||
return (
|
return (
|
||||||
structures: structures
|
structures: structures,
|
||||||
|
colors: colors
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
Reference in New Issue
Block a user