From 12b98c8d46406841b6ff408a3d174240c1cc708f Mon Sep 17 00:00:00 2001 From: Sean Anderson Date: Wed, 15 Mar 2023 15:00:50 -0400 Subject: [PATCH] doc: Move interface documentation to its own document This is more detailed technical documentation, and doesn't really need to go at the top-level. Signed-off-by: Sean Anderson --- Makefile | 1 + README.adoc | 52 --------------------------------------------- doc/index.adoc | 1 + doc/interfaces.adoc | 51 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 53 insertions(+), 52 deletions(-) create mode 100644 doc/interfaces.adoc diff --git a/Makefile b/Makefile index f2af636..7993d39 100644 --- a/Makefile +++ b/Makefile @@ -170,6 +170,7 @@ doc/output/%.html: doc/%.adoc doc/docinfo.html | doc/output $(ADOC) -o $@ $< DOCS += index +DOCS += interfaces DOCS += uart_wb_bridge .PHONY: htmldocs diff --git a/README.adoc b/README.adoc index 87ca757..7ab17d2 100644 --- a/README.adoc +++ b/README.adoc @@ -249,58 +249,6 @@ slave a (priority-decoded) address bit. Add a register stage to a wishbone bus. This helps improve timing, but will add a cycle of latency (and decrease throughput). -== Interfaces - -Throughout this project, a variety of interfaces, some standard and some -bespoke, are used to communicate between cores. This section describes these -interfaces. - -=== "`MII`" - -This is the Media-Independent Interface (MII) described by IEEE 802.3 clause 22. -However, instead of RX and TX clocks, clock-enables are used instead. This is a -better fit for the clocking resources found on iCE40 FPGAs. In the 125 MHz clock -domain used by these cores, the clock enable is asserted every 5 clock cycles. -The clock enable generated by `pcs_rx` may vary somewhat from this due to -differences in the local and far end clocks. The `mii_elastic_buffer` module can -be used to smooth out these variations over the course of a frame. - -=== "`PMD`" - -This is a bespoke interface used by modules in the receive data path below the -PCS layer. It consists of three signals: `clk`, `data`, and `data_valid`. `data` -and `data_valid` are both two bits wide. Data is transferred on the rising edge -of `clk`. The following table shows the relation between `data` and -`data_valid`: - -[cols="1,1,1"] -|=== -| `data_valid` | `data[1]` | `data[0]` - -| 0 | Invalid | Invalid -| 1 | Valid | Invalid -| 2 or 3 | Valid | Valid -|=== - -In the case where both bits in `data` are valid, `data[1]` is the most recent -bit. As a consequence, when `data_valid` is non-zero, `data[1]` always holds the -new bit to process. Because three bits cannot be transferred at once, only -`data_valid[1]` is necessary to determine if two bits are to be transferred. - -=== AXI-Stream - -This is https://zipcpu.com/doc/axi-stream.pdf[AMBA 4 AXI4-Stream], minus several -signals. Generally, `ARESETn`, `TSTRB`, `TKEEP`, `TID`, `TDEST` are ommitted. -Sometimes `TUSER` is omitted as well. Additionally, the `A` and `T` prefixes -are not used. - -=== Wishbone - -This is https://cdn.opencores.org/downloads/wbspec_b4.pdf[Wishbone B4] in -non-pipelined mode. Generally, `RST`, `TGA`, `TGC`, `TGD`, `RTY`, `SEL`, and -`LOCK` signals are omitted. The `_I` and `_O` suffixes are not used. `DAT` is -named `data_read` or `data_write`, depending on the direction of transfer. `ADR` -is expanded to `addr`. == Licensing diff --git a/doc/index.adoc b/doc/index.adoc index e9975ae..7357744 100644 --- a/doc/index.adoc +++ b/doc/index.adoc @@ -3,4 +3,5 @@ This is the documentation for my https://github.com/Forty-Bot/ethernet[ethernet cores]. +* xref:interfaces.adoc[Interfaces] * xref:uart_wb_bridge.adoc[UART-Wishbone Bridge] diff --git a/doc/interfaces.adoc b/doc/interfaces.adoc new file mode 100644 index 0000000..94aad84 --- /dev/null +++ b/doc/interfaces.adoc @@ -0,0 +1,51 @@ += Interfaces + +Throughout this project, a variety of interfaces, some standard and some +bespoke, are used to communicate between cores. + +== "`MII`" + +This is the Media-Independent Interface (MII) described by IEEE 802.3 clause 22. +However, instead of RX and TX clocks, clock-enables are used instead. This is a +better fit for the clocking resources found on iCE40 FPGAs. In the 125 MHz clock +domain used by these cores, the clock enable is asserted every 5 clock cycles. +The clock enable generated by `pcs_rx` may vary somewhat from this due to +differences in the local and far end clocks. The `mii_elastic_buffer` module can +be used to smooth out these variations over the course of a frame. + +== "`PMD`" + +This is a bespoke interface used by modules in the receive data path below the +PCS layer. It consists of three signals: `clk`, `data`, and `data_valid`. `data` +and `data_valid` are both two bits wide. Data is transferred on the rising edge +of `clk`. The following table shows the relation between `data` and +`data_valid`: + +[cols="1,1,1"] +|=== +| `data_valid` | `data[1]` | `data[0]` + +| 0 | Invalid | Invalid +| 1 | Valid | Invalid +| 2 or 3 | Valid | Valid +|=== + +In the case where both bits in `data` are valid, `data[1]` is the most recent +bit. As a consequence, when `data_valid` is non-zero, `data[1]` always holds the +new bit to process. Because three bits cannot be transferred at once, only +`data_valid[1]` is necessary to determine if two bits are to be transferred. + +== AXI-Stream + +This is https://zipcpu.com/doc/axi-stream.pdf[AMBA 4 AXI4-Stream], minus several +signals. Generally, `ARESETn`, `TSTRB`, `TKEEP`, `TID`, `TDEST` are ommitted. +Sometimes `TUSER` is omitted as well. Additionally, the `A` and `T` prefixes +are not used. + +== Wishbone + +This is https://cdn.opencores.org/downloads/wbspec_b4.pdf[Wishbone B4] in +non-pipelined mode. Generally, `RST`, `TGA`, `TGC`, `TGD`, `RTY`, `SEL`, and +`LOCK` signals are omitted. The `_I` and `_O` suffixes are not used. `DAT` is +named `data_read` or `data_write`, depending on the direction of transfer. `ADR` +is expanded to `addr`.