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 <seanga2@gmail.com>

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

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
 

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]

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`.