[docs] inline Wavedrom scripts (#1208)

This commit is contained in:
stnolting 2025-03-16 18:19:59 +01:00 committed by GitHub
commit fdeb9ff6a5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
29 changed files with 179 additions and 160 deletions

View file

@ -459,7 +459,34 @@ The figure below shows three exemplary bus accesses:
. A failing read access to address `C_addr` (slow response; `ERR` arrives after several cycles).
.Three Exemplary Bus Transactions (showing only in-band signals; privileged non-debug non-atomic accesses)
image::bus_interface.png[700]
[wavedrom, format="svg", align="center"]
----
{signal: [
{name: 'clk', wave: 'p..|.......|..'},
[
"request",
{name: 'addr', wave: 'x3.|.x4.x5.|.x', data: ['A_addr', 'B_addr', 'C_addr']},
{name: 'data', wave: 'x..|..4.x..|..', data: ['wdata']},
{name: 'ben', wave: 'x..|..4.x..|..', data: ['ben']},
{name: 'stb', wave: '010|..10.10|..', node: '.a....d..f....'},
{name: 'rw', wave: 'x0.|.x1.x0.|..', node: '..............'},
{name: 'src', wave: 'x0.|.x0.x0.|.x'},
{name: 'priv', wave: 'x1.|.x1.x1.|.x'},
{name: 'debug', wave: 'x0.|.x0.x0.|.x'},
{name: 'amo', wave: 'x0.|.x0.x0.|.x'},
{name: 'amoop', wave: 'x0.|.x0.x0.|.x'},
],
{},
[
"response",
{name: 'data', wave: '2..|32.....|x2', data: ['0', 'rdata', '0'], node: '....b.......g.'},
{name: 'ack', wave: '0..|10.10..|..', node: '....c..e......'},
{name: 'err', wave: '0..|.......|10', node: '............h.'}
]
],
edge: ['a~>b', 'a~>c', 'd~>e', 'f~>g', 'f~>h']
}
----
.Adding Register Stages
[TIP]

View file

@ -65,7 +65,17 @@ always compile-time-static.
Example operation: `rd <= rs1 xnor rs2` (bit-wise logical XNOR)
.CFU R3-type instruction format
image::cfu_r3type_instruction.png[align=left]
[wavedrom, format="svg", align="center"]
----
{reg: [
{bits: 7, name: 11, attr: 'Opcode: Custom-0'},
{bits: 5, name: 'rd', attr: 'Destination'},
{bits: 3, name: 'funct3', type: 1},
{bits: 5, name: 'rs1', attr: 'Source 1'},
{bits: 5, name: 'rs2', attr: 'Source 2'},
{bits: 7, name: 'funct7', type: 1}
]}
----
* `funct7`: 7-bit immediate (immediate data or function select)
* `rs2`: address of second source register (providing 32-bit source data)
@ -92,7 +102,18 @@ values are always compile-time-static.
Example operation: `rd <= (rs1 * rs2 + rs3)[31:0]` (multiply-and-accumulate; "MAC")
.CFU R4-type instruction format
image::cfu_r4type_instruction.png[align=left]
[wavedrom, format="svg", align="center"]
----
{reg: [
{bits: 7, name: 43, attr: 'Opcode: Custom-1'},
{bits: 5, name: 'rd', attr: 'Destination'},
{bits: 3, name: 'funct3', type: 1},
{bits: 5, name: 'rs1', attr: 'Source 1'},
{bits: 5, name: 'rs2', attr: 'Source 2'},
{bits: 2, name: 4, attr: '-'},
{bits: 5, name: 'rs3', attr: 'Source 3'}
]}
----
* `rs3`: address of third source register (providing 32-bit source data)
* `rs2`: address of second source register (providing 32-bit source data)

View file

@ -121,7 +121,6 @@ neorv32 - Project home folder
│ ├-datasheet - AsciiDoc sources for the NEORV32 data sheet
│ ├-figures - Figures and logos
│ ├-references - Data sheets and RISC-V specs
│ ├-sources - Sources for the images in 'figures/'
│ └-userguide - AsciiDoc sources for the NEORV32 user guide
├-rtl - VHDL sources

View file

@ -65,7 +65,16 @@ value. The actual data bits are transferred by modifying the duty cycle of the s
WS2812 are shown below). A RESET command is "send" by pulling the data line LOW for at least 50μs.
.WS2812 bit-level timing (timing does not scale)
image::neopixel_timing.png[align=left]
[wavedrom, format="svg", align="center"]
----
{signal: [
{name: '0-code', wave: '01...0...1', node: '.a...b...c' },
{name: '1-code', wave: '01....0..1', node: '.d....e..f' },
{name: 'reset', wave: '10.......1', node: '.g.......h' },
],
edge: ['a~>b T0H', 'b~>c T0L', 'd~>e T1H', 'e~>f T1L', 'g~>h TRESET']
}
----
.WS2812 interface timing
[cols="<2,<2,<6"]

View file

@ -118,13 +118,41 @@ controller: single-bit (0 or 1) transaction and reset with presence detect. Note
the single-bit operation eight times. The relevant points in time are shown as _absolute_ time points (in multiples of the
time base T~base~) with the falling edge of the bus as reference points.
[cols="^2,^2"]
[grid="none"]
|=======================
a| image::onewire_data.png[align=center]
a| image::onewire_reset.png[align=center]
| Single-bit data transmission (not to scale) | Reset pulse and presence detect (not to scale)
|=======================
.Single-bit data transmission (not to scale)
[wavedrom, format="svg", align="center"]
----
{ signal: [
{ wave: '10x....1.', node: '.........'},
{ node: '.ab......'},
{ node: '.X..c....'},
{ node: '.Y.....d.'},
{ node: '.Z......e'}
],
edge: [
'a-b t0',
'X-c t1',
'Y-d t2',
'Z-e t3'
]
}
----
.Reset pulse and presence detect (not to scale)
[wavedrom, format="svg", align="center"]
----
{ signal: [
{ wave: '10..x...1', node: '.........'},
{ node: '.f..g....'},
{ node: '.X.. h...'},
{ node: '.Y......i'}
],
edge: [
'f-g t4',
'X-h t5',
'Y-i t6',
]
}
----
.Data Transmission Timing
[cols="<2,<6,^3,^3"]

View file

@ -49,6 +49,18 @@ The SLINK interface consists of four signals for each channel:
* `rdy` indicates that the receiver is ready to receive
* `src` and `dst` provide source/destination routing information (optional)
.SLINK example transmissions
[wavedrom, format="svg", align="center"]
----
{signal: [
{name: 'clk', wave: 'p.........'},
{name: 'dat', wave: 'x345..6x7x', data: ["A", "B", "C", "D", "E"]},
{name: 'val', wave: '01.....010'},
{name: 'rdy', wave: '01.0.1...0'},
{name: 'lst', wave: '0.......10'},
]}
----
.AXI4-Stream Compatibility
[NOTE]
The interface names (except for `src` and `dst`) and the underlying protocol is compatible to the AXI4-Stream protocol standard.

View file

@ -91,7 +91,43 @@ two operation types are illustrated in the following figure (note that the trans
to improve readability).
.TWD single-byte read and write transaction timing (not to scale)
image::twd_sequences.png[]
[wavedrom, format="svg", align="center"]
----
{signal: [
[
"write byte",
{name: 'SDA', wave: '10.7..7..7..7..7..7..7..0..0..x|.', node: 'a.b.....................c..d..e', data: ['A6', 'A5', 'A4', 'A3', 'A2', 'A1', 'A0']},
{name: 'SCL', wave: '1.0.10.10.10.10.10.10.10.10.10.|.'},
{},
{name: 'SDA', wave: 'x|.5..5..5..5..5..5..5..5..0..0.1', node: '...........................f..gh.i', data: ['D7', 'D6', 'D5', 'D4', 'D3', 'D2', 'D1', 'D0']},
{name: 'SCL', wave: '0|..10.10.10.10.10.10.10.10.10.1.'}
],
{},
{},
[
"read byte",
{name: 'SDA', wave: '10.7..7..7..7..7..7..7..1..0..x|.', node: 'j.k.....................l..m..n', data: ['A6', 'A5', 'A4', 'A3', 'A2', 'A1', 'A0']},
{name: 'SCL', wave: '1.0.10.10.10.10.10.10.10.10.10.|.'},
{},
{name: 'SDA', wave: 'x|.9..9..9..9..9..9..9..9..0..0.1', node: '...........................o..pq.r', data: ['D7', 'D6', 'D5', 'D4', 'D3', 'D2', 'D1', 'D0']},
{name: 'SCL', wave: '0|..10.10.10.10.10.10.10.10.10.1.'}
]
],
edge: [
'a-b START',
'c-d WRITE',
'd-e ACK by TWD',
'f-g ACK by TWD',
'h-i STOP',
'j-k START',
'l-m READ',
'm-n ACK by TWD',
'o-p ACK by HOST',
'q-r STOP'
]
}
----
Any new transaction starts with a **START** condition. Then, the host transmits the 7 bit device address MSB-first
(green signals `A6` to `A0`) plus a command bit. The command bit can be either **write** (pulling the SDA line low)

View file

@ -56,17 +56,45 @@ do not allow any bus timeouts. Hence, `XBUS_TIMEOUT` should be set to zero (disa
when using the XBUS-AHB bridge.
**Wishbone Bus Protocol**
**XBUS Bus Protocol**
The external bus interface complies to the **pipelined Wishbone b4** protocol. Even though this protocol
was explicitly designed to support pipelined transfers, only a single transfer will be "in fly" at once.
Hence, just two types of bus transactions are generated by the XBUS controller (see images below).
.XBUS/Wishbone Write Transaction
image::xbus_write.png[700]
.XBUS Write Transaction
[wavedrom, format="svg", align="center"]
----
{signal: [
{name: 'clk', wave: 'p....|...'},
{name: 'xbus_adr_o', wave: 'x3...|.x.', data: ['address']},
{name: 'xbus_dat_i', wave: 'x....|.x.'},
{name: 'xbus_dat_o', wave: 'x3...|.x.', data: ['wdata']},
{name: 'xbus_we_o', wave: 'x1...|.x.'},
{name: 'xbus_sel_o', wave: 'x3...|.x.', data: ['byte_enable']},
{name: 'xbus_stb_o', wave: '010..|...'},
{name: 'xbus_cyc_o', wave: '01...|.0.'},
{name: 'xbus_ack_i', wave: 'x0...|1x.'},
{name: 'xbus_err_i', wave: 'x0...|.x.'},
]}
----
.XBUS/Wishbone Read Transaction
image::xbus_read.png[700]
.XBUS Read Transaction
[wavedrom, format="svg", align="center"]
----
{signal: [
{name: 'clk', wave: 'p....|...'},
{name: 'xbus_adr_o', wave: 'x3...|.x.', data: ['address']},
{name: 'xbus_dat_i', wave: 'x....|3x.', data: ['rdata']},
{name: 'xbus_dat_o', wave: 'x....|.x.'},
{name: 'xbus_we_o', wave: 'x0...|.x.'},
{name: 'xbus_sel_o', wave: 'x....|.x.'},
{name: 'xbus_stb_o', wave: '010..|...'},
{name: 'xbus_cyc_o', wave: '01...|.0.'},
{name: 'xbus_ack_i', wave: 'x0...|1x.'},
{name: 'xbus_err_i', wave: 'x0...|.x.'},
]}
----
.Wishbone "Classic" Protocol
[IMPORTANT]

View file

@ -1,2 +1 @@
*.pptx
*.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.9 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.4 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.6 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

View file

@ -65,7 +65,7 @@ POSSIBILITY OF SUCH DAMAGE.
* "NeoPixel" is a trademark of Adafruit Industries.
* "Segger Embedded Studio" and "J-Link" are trademarks of Segger Microcontroller Systems GmbH.
* Images/figures made with _Microsoft Power Point_.
* Timing diagrams made with _WaveDrom Editor_.
* Diagrams made with _WaveDrom_.
* Documentation made with `asciidoctor`.
All further/unreferenced projects/products/brands belong to their according copyright holders.

View file

@ -1,25 +0,0 @@
{signal: [
{name: 'clk', wave: 'p..|.......|..'},
[
"request",
{name: 'addr', wave: 'x3.|.x4.x5.|.x', data: ['A_addr', 'B_addr', 'C_addr']},
{name: 'data', wave: 'x..|..4.x..|..', data: ['wdata']},
{name: 'ben', wave: 'x..|..4.x..|..', data: ['ben']},
{name: 'stb', wave: '010|..10.10|..', node: '.a....d..f....'},
{name: 'rw', wave: 'x0.|.x1.x0.|..', node: '..............'},
{name: 'src', wave: 'x0.|.x0.x0.|.x'},
{name: 'priv', wave: 'x1.|.x1.x1.|.x'},
{name: 'debug', wave: 'x0.|.x0.x0.|.x'},
{name: 'amo', wave: 'x0.|.x0.x0.|.x'},
{name: 'amoop', wave: 'x0.|.x0.x0.|.x'},
],
{},
[
"response",
{name: 'data', wave: '2..|32.....|x2', data: ['0', 'rdata', '0'], node: '....b.......g.'},
{name: 'ack', wave: '0..|10.10..|..', node: '....c..e......'},
{name: 'err', wave: '0..|.......|10', node: '............h.'}
]
],
edge: ['a~>b', 'a~>c', 'd~>e', 'f~>g', 'f~>h']
}

View file

@ -1,8 +0,0 @@
{reg: [
{bits: 7, name: 11, attr: 'Opcode: Custom-0'},
{bits: 5, name: 'rd', attr: 'Destination'},
{bits: 3, name: 'funct3', type: 1},
{bits: 5, name: 'rs1', attr: 'Source 1'},
{bits: 5, name: 'rs2', attr: 'Source 2'},
{bits: 7, name: 'funct7', type: 1}
]}

View file

@ -1,9 +0,0 @@
{reg: [
{bits: 7, name: 43, attr: 'Opcode: Custom-1'},
{bits: 5, name: 'rd', attr: 'Destination'},
{bits: 3, name: 'funct3', type: 1},
{bits: 5, name: 'rs1', attr: 'Source 1'},
{bits: 5, name: 'rs2', attr: 'Source 2'},
{bits: 2, name: 4, attr: '-'},
{bits: 5, name: 'rs3', attr: 'Source 3'}
]}

View file

@ -1,7 +0,0 @@
{signal: [
{name: '0-code', wave: '01...0...1', node: '.a...b...c' },
{name: '1-code', wave: '01....0..1', node: '.d....e..f' },
{name: 'reset', wave: '10.......1', node: '.g.......h' },
],
edge: ['a~>b T0H', 'b~>c T0L', 'd~>e T1H', 'e~>f T1L', 'g~>h TRESET']
}

View file

@ -1,14 +0,0 @@
{ signal: [
{ wave: '10x....1.', node: '.........'},
{ node: '.ab......'},
{ node: '.X..c....'},
{ node: '.Y.....d.'},
{ node: '.Z......e'}
],
edge: [
'a-b t0',
'X-c t1',
'Y-d t2',
'Z-e t3'
]
}

View file

@ -1,12 +0,0 @@
{ signal: [
{ wave: '10..x...1', node: '.........'},
{ node: '.f..g....'},
{ node: '.X.. h...'},
{ node: '.Y......i'}
],
edge: [
'f-g t4',
'X-h t5',
'Y-i t6',
]
}

View file

@ -1,7 +0,0 @@
{signal: [
{name: 'clk', wave: 'p.........'},
{name: 'dat', wave: 'x345..6x7x', data: ["A", "B", "C", "D", "E"]},
{name: 'val', wave: '01.....010'},
{name: 'rdy', wave: '01.0.1...0'},
{name: 'lst', wave: '0.......10'},
]}

View file

@ -1,34 +0,0 @@
{signal: [
[
"write byte",
{name: 'SDA', wave: '10.7..7..7..7..7..7..7..0..0..x|.', node: 'a.b.....................c..d..e', data: ['A6', 'A5', 'A4', 'A3', 'A2', 'A1', 'A0']},
{name: 'SCL', wave: '1.0.10.10.10.10.10.10.10.10.10.|.'},
{},
{name: 'SDA', wave: 'x|.5..5..5..5..5..5..5..5..0..0.1', node: '...........................f..gh.i', data: ['D7', 'D6', 'D5', 'D4', 'D3', 'D2', 'D1', 'D0']},
{name: 'SCL', wave: '0|..10.10.10.10.10.10.10.10.10.1.'}
],
{},
{},
[
"read byte",
{name: 'SDA', wave: '10.7..7..7..7..7..7..7..1..0..x|.', node: 'j.k.....................l..m..n', data: ['A6', 'A5', 'A4', 'A3', 'A2', 'A1', 'A0']},
{name: 'SCL', wave: '1.0.10.10.10.10.10.10.10.10.10.|.'},
{},
{name: 'SDA', wave: 'x|.9..9..9..9..9..9..9..9..0..0.1', node: '...........................o..pq.r', data: ['D7', 'D6', 'D5', 'D4', 'D3', 'D2', 'D1', 'D0']},
{name: 'SCL', wave: '0|..10.10.10.10.10.10.10.10.10.1.'}
]
],
edge: [
'a-b START',
'c-d WRITE',
'd-e ACK by TWD',
'f-g ACK by TWD',
'h-i STOP',
'j-k START',
'l-m READ',
'm-n ACK by TWD',
'o-p ACK by HOST',
'q-r STOP'
]
}

View file

@ -1,12 +0,0 @@
{signal: [
{name: 'clk', wave: 'p....|...'},
{name: 'xbus_adr_o', wave: 'x3...|.x.', data: ['address']},
{name: 'xbus_dat_i', wave: 'x....|3x.', data: ['rdata']},
{name: 'xbus_dat_o', wave: 'x....|.x.'},
{name: 'xbus_we_o', wave: 'x0...|.x.'},
{name: 'xbus_sel_o', wave: 'x....|.x.'},
{name: 'xbus_stb_o', wave: '010..|...'},
{name: 'xbus_cyc_o', wave: '01...|.0.'},
{name: 'xbus_ack_i', wave: 'x0...|1x.'},
{name: 'xbus_err_i', wave: 'x0...|.x.'},
]}

View file

@ -1,12 +0,0 @@
{signal: [
{name: 'clk', wave: 'p....|...'},
{name: 'xbus_adr_o', wave: 'x3...|.x.', data: ['address']},
{name: 'xbus_dat_i', wave: 'x....|.x.'},
{name: 'xbus_dat_o', wave: 'x3...|.x.', data: ['wdata']},
{name: 'xbus_we_o', wave: 'x1...|.x.'},
{name: 'xbus_sel_o', wave: 'x3...|.x.', data: ['byte_enable']},
{name: 'xbus_stb_o', wave: '010..|...'},
{name: 'xbus_cyc_o', wave: '01...|.0.'},
{name: 'xbus_ack_i', wave: 'x0...|1x.'},
{name: 'xbus_err_i', wave: 'x0...|.x.'},
]}