From 13ee4899a386d417ab236df31abb7f91c7901327 Mon Sep 17 00:00:00 2001 From: Sean Anderson Date: Wed, 15 Mar 2023 15:12:17 -0400 Subject: [PATCH] doc: Expand interfaces documentation Expand a bit on the AXI stream and Wishbone interfaces, documenting the particular choices we use. The reset signalling could likely also use some further documentation, but I have deferred that until I have gone though all the cores and fixed bugs. Signed-off-by: Sean Anderson --- doc/interfaces.adoc | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/interfaces.adoc b/doc/interfaces.adoc index 94aad84..6f0caf9 100644 --- a/doc/interfaces.adoc +++ b/doc/interfaces.adoc @@ -13,7 +13,7 @@ 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`" +== "`100Base-X`" 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` @@ -34,18 +34,23 @@ 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. +However, all cores which generate `data_valid` must not generate a value of 3 +for `data_valid`. == 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. +signals. Generally, `ARESETn`, `TSTRB`, `TKEEP`, `TID`, `TDEST` are omitted. Sometimes `TUSER` is omitted as well. Additionally, the `A` and `T` prefixes -are not used. +are not used. When the `user` signal is present, it generally indicates that the +associated data is erronious. == 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`. +non-pipelined ("`classic`") mode. This imposes a performance penalty on the bus, +but wishbone is just used for management registers so I am not too concerned. +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`. All cores have 16-bit ports with 16-bit granularity.