diff --git a/README.md b/README.md index 8a28dde..7c5ef3f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,44 @@ # rivet-typst -Register / Instruction Visualizer & Explainer Tool with Typst, using CeTZ \ No newline at end of file +RIVET _(Register / Instruction Visualizer & Explainer Tool)_ is a [Typst](https://typst.app) package for visualizing binary instructions or describing the contents of a register, using the [CeTZ](https://typst.app/universe/package/cetz) package. + +It is based on the [homonymous Python script](https://git.kb28.ch/HEL/rivet) + +## Examples + + + + + + + + + + + + + +
+ + + +
A bit of eveything
+ + + +
RISC-V memory instructions (blueprint)
+ +*Click on the example image to jump to the code.* + +## Usage +For information, see the [manual](manual.pdf) + +To use this package, simply import `schema` [src/lib.typ](src/lib.typ) and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà ! +```typ +#import "src/lib.typ": schema +#let doc = schema.load("path/to/schema.yaml") +#schema.render(doc) +``` + +## Installing +> TODO diff --git a/gallery/example1.pdf b/gallery/example1.pdf new file mode 100644 index 0000000..eeb4e1e Binary files /dev/null and b/gallery/example1.pdf differ diff --git a/gallery/example1.png b/gallery/example1.png new file mode 100644 index 0000000..70bf2ae Binary files /dev/null and b/gallery/example1.png differ diff --git a/gallery/example1.typ b/gallery/example1.typ new file mode 100644 index 0000000..bfb9ca0 --- /dev/null +++ b/gallery/example1.typ @@ -0,0 +1,6 @@ +#import "../src/lib.typ": schema, config + +#let example = schema.load("/gallery/example1.yaml") +#schema.render(example, config: config.config( + full-page: true +)) \ No newline at end of file diff --git a/gallery/example1.yaml b/gallery/example1.yaml new file mode 100644 index 0000000..2ca7964 --- /dev/null +++ b/gallery/example1.yaml @@ -0,0 +1,73 @@ +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 diff --git a/gallery/example2.pdf b/gallery/example2.pdf new file mode 100644 index 0000000..a6beb04 Binary files /dev/null and b/gallery/example2.pdf differ diff --git a/gallery/example2.png b/gallery/example2.png new file mode 100644 index 0000000..33c0ef3 Binary files /dev/null and b/gallery/example2.png differ diff --git a/gallery/example2.typ b/gallery/example2.typ new file mode 100644 index 0000000..012dd9b --- /dev/null +++ b/gallery/example2.typ @@ -0,0 +1,7 @@ +#import "../src/lib.typ": schema, config + +#let example = schema.load("/gallery/example2.yaml") +#schema.render(example, config: config.blueprint( + full-page: true, + left-labels: true +)) \ No newline at end of file diff --git a/gallery/example2.yaml b/gallery/example2.yaml new file mode 100644 index 0000000..778fac2 --- /dev/null +++ b/gallery/example2.yaml @@ -0,0 +1,78 @@ +structures: + main: + bits: 32 + ranges: + 31-20: + name: src + depends-on: 5 + values: + 0: + description: + structure: srcImmediate + 1: + description: + structure: srcRegister + 19-15: + name: rs1 + 14-12: + name: funct3 + description: function modifier + values: + 000: byte + 001: half-word + "010": word + 100: upper byte (load only) + 101: upper half (load only) + 11-7: + name: dst + depends-on: 5 + values: + 0: + description: + structure: dstRegister + 1: + description: + structure: dstImmediate + 6: + name: 0 + 5: + name: I + 4: + name: 0 + 3: + name: 0 + 2: + name: 0 + 1: + name: 1 + 0: + name: 1 + + srcImmediate: + bits: 12 + ranges: + 11-0: + name: src + description: source memory address + srcRegister: + bits: 12 + ranges: + 11-5: + name: dstU + description: destination address upper bits + 4-0: + name: rs2 + description: source register + + dstImmediate: + bits: 5 + ranges: + 4-0: + name: destL + description: destination address lower bits + dstRegister: + bits: 5 + ranges: + 4-0: + name: rd + description: destination register \ No newline at end of file diff --git a/gallery/riscv/riscv.pdf b/gallery/riscv/riscv.pdf index 70c5651..7f5387c 100644 Binary files a/gallery/riscv/riscv.pdf and b/gallery/riscv/riscv.pdf differ diff --git a/manual.pdf b/manual.pdf index 3225ecb..414b565 100644 Binary files a/manual.pdf and b/manual.pdf differ diff --git a/manual.typ b/manual.typ index 26362b7..8124525 100644 --- a/manual.typ +++ b/manual.typ @@ -39,7 +39,7 @@ This is a port of the #link("https://git.kb28.ch/HEL/rivet")[homonymous Python s Simply import `schema` from #link("src/lib.typ") and call `schema.load` to parse a schema description. Then use `schema.render` to render it, et voilà ! #pad(left: 1em)[```typ #import "src/lib.typ": schema -#let doc = schema.load("path/to/schema.typ") +#let doc = schema.load("path/to/schema.yaml") #schema.render(doc) ```]