Add clarifications for wishbone.

doc/wishbone.md

+Wishbone
+--------
+
+most of the cores available on OHWR are wishbone based.  The official
+document describing the bus can be read from ohwr at
+https://www.ohwr.org/attachments/179/wbspec_b4.pdf or from
+opencores.org at https://cdn.opencores.org/downloads/wbspec_b4.pdf
+The previous version (b3) can also be read for historical reasons at
+https://cdn.opencores.org/downloads/wbspec_b3.pdf
+
+You can refer to https://zipcpu.com/zipcpu/2017/11/07/wb-formal.html
+for some issues about wishbone.
+
+The specifications define several variants of the bus and also several
+optional signals.  The purpose of this document is to define which
+variants are commonly used and to clarify some ambiguities.
+
+
+Variants
+~~~~~~~~
+
+* Only the standard cycle or the pipelined cycle are supported.  In
+  particular, registered feedback bus cycles aren't supported.
+
+* Although RTY is present in the VHDL records that declare types for the
+  wishbone bus, it must not be used.
+
+* ERR is also present, but may not be correctly conveyed to the
+  original master.  The reason is that the semantic may be different
+  from the wishbone semantic (for example, VME allows to report an
+  error only on the first cycle of a burst transaction, while wishbone
+  allows it on any cycle).
+
+* So the wishbone signals are: RST, CLK, ADR, DATI, DATO, WE, SEL,
+  STB, ACK, CYC and STALL.
+
+* Whether the protocol is standard or pipelined wishbone is indicated
+  either by the documentation or through a generic.  It would have
+  been better to use two different types for the two different
+  protocols.
+
+
+Clarifications for standard cycle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* The master is always synchronous for its outputs and always sample
+  its inputs synchronously.
+
+* The slave can be synchronous or asynchronous.  Asynchronous slaves
+  allow to build very simple slaves.
+
+* Although Rule 3.50 hints that ACK cannot be deasserted before STB is
+  deasserted, this is not clearly stated and all waveforms show that
+  ACK and STB are deasserted together.  In all waveforms, ACK is
+  asserted for only one cycle.
+
+* So a a slave asserts ACK for only one cycle and a master deasserts
+  STB once ACK has been asserted.  A transfer is completed when STB,
+  CYC and ACK are asserted.
+
+
+Rationale
+~~~~~~~~~
+
+* How long ACK can stay asserted once STB is deasserted?  That's an
+  important point.  If ACK is asynchronous, it can be deasserted
+  almost immediately.  If ACK is synchronous, it can be deasserted in
+  the next cycle.  But if we want to be able to easily insert
+  registers, the deassertion can be delayed for more cycles.
+
+* Should master wait for ACK to be deasserted before starting a new
+  transaction ?  That depends on the previous answer.  But note this
+  has some consequences on the throughoutput: if yes, there will be
+  one data transfer every 4 clock edges (set STB, set ACK, clear STB,
+  clear ACK), if no one every 3 edges (in the case of a synchronous
+  slave: set STB, set ACK, clear STB, and a new transaction can start
+  again where ACK is cleared on the first cycle).
+
+Examples
+~~~~~~~~
+
+Using wavedrom.
+
+This is a standard cycle.  As often shown in the wishbone specification
+(eg illustration 3-2 and 3-3), the stb signal is deasserted at the same
+time as ack.
+
+{signal: [
+  {name: 'clk', wave: 'p....'},
+  {name: 'dat', wave: 'x.=.x'},
+  {name: 'stb', wave: '0.1.0'},
+  {name: 'cyc', wave: '0.1.0'},
+  {},
+  {name: 'ack', wave: '0..10'}
+]}
+
+If rule 3.50 is closely followed (ACK/ERR/RTY signals are asserted and
+negated in response to the assertion and negation of STB), this can
+only happen if ACK is combinational.
+
+Assuming a synchronous ACK signal and following closely the rule 3.50,
+a transaction would look like:
+
+{signal: [
+  {name: 'clk', wave: 'p.....'},
+  {name: 'dat', wave: 'x.=.x.'},
+  {name: 'stb', wave: '0.1.0.'},
+  {name: 'cyc', wave: '0.1.0.'},
+  {},
+  {name: 'ack', wave: '0..1.0'}
+]}
+
+Can a transaction start when the ACK is still asserted ?  The wishbone
+specification says in permission 3.35 that the ACK signal can stay asserted.
+And if rule 3.55 is followed (master must operate normally when the slave
+inteface holds ACK asserted), the master doesn't know the state of ACK in
+the next cycle and starting a new transaction would be ambiguous (how to
+interpret the ACK? is it still part of the previous transaction or is it an
+ack for this transaction?).
+
+This means a transaction would require at least 4 cycles (assertion of CYC+STB,
+assertion of ACK, deassertion of CYC+STB, deassertion of ACK).
+
+The rule 3.50 looks badly written, so let's assume ACK can be immediately
+negated:
+
+{signal: [
+  {name: 'clk', wave: 'p....'},
+  {name: 'dat', wave: 'x.=.x'},
+  {name: 'stb', wave: '0.1.0'},
+  {name: 'cyc', wave: '0.1.0'},
+  {},
+  {name: 'ack', wave: '0..10'}
+]}
+
+As a consequence, a transaction requires at least 3 cycles.  Hence the
+clarification about 1 cycle ACK.
+
+Note that if ACK is combinational, a transaction requires at least 2 cycles:
+
+{signal: [
+  {name: 'clk', wave: 'p...'},
+  {name: 'dat', wave: 'x.=x'},
+  {name: 'stb', wave: '0.10'},
+  {name: 'cyc', wave: '0.10'},
+  {},
+  {name: 'ack', wave: '0.10'}
+]}
+
+For block read/write, STB has to be deasserted before starting a transfer:
+
+{signal: [
+  {name: 'clk', wave: 'p.......'},
+  {name: 'dat', wave: 'x.3.x4.x'},
+  {name: 'stb', wave: '0.1.01.0'},
+  {name: 'cyc', wave: '0.1....0'},
+  {},
+  {name: 'ack', wave: '0..10.10'}
+]}
+
+Considerations beyond the spec
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If we could suppose that the both master and slave knew that the ACK
+were asserted for one cycle, we could even have shorter transfers without
+deasserting STB:
+
+{signal: [
+  {name: 'clk', wave: 'p......'},
+  {name: 'dat', wave: 'x.3.4.x'},
+  {name: 'stb', wave: '0.1...0'},
+  {name: 'cyc', wave: '0.1...0'},
+  {},
+  {name: 'ack', wave: '0..1010'}
+]}
+
+Note that this is not allowed by these clarifications.  We could even go
+farther by not requiring ACK to be deasserted:
+
+{signal: [
+  {name: 'clk', wave: 'p.....'},
+  {name: 'dat', wave: 'x.3.4x'},
+  {name: 'stb', wave: '0.1..0'},
+  {name: 'cyc', wave: '0.1..0'},
+  {},
+  {name: 'ack', wave: '0..1.0'}
+]}
+
+(Again, this is not allowed by the specifications or the
+clarifications).  But this means the slave tries to do forecast.
+Compare with just one transfer:
+
+{signal: [
+  {name: 'clk', wave: 'p.....'},
+  {name: 'dat', wave: 'x.3.x.'},
+  {name: 'stb', wave: '0.1.0.'},
+  {name: 'cyc', wave: '0.1.0.'},
+  {},
+  {name: 'ack', wave: '0..1.0'}
+]}
+
+In that case, because master/slaves know the ACK is asserted only for one
+cycle, it is asserted for two cycles...
+
+Examples of a bus register
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is a waveform with a synchronous slave for a register on bus between
+a master and a slave:
+
+{signal: [
+  {name: 'clk',  wave: 'p......'},
+  {name: 'dat1', wave: 'x.=...x'},
+  {name: 'stb1', wave: '0.1...0'},
+  {name: 'cyc1', wave: '0.1...0'},
+  {name: 'ack1', wave: '0....10'},
+  {},
+  {name: 'dat2', wave: 'x..=..x'},
+  {name: 'stb2', wave: '0..1.0.'},
+  {name: 'cyc2', wave: '0..1.0.'},
+  {name: 'ack2', wave: '0...10.'}
+]}
+
+
+Same but with an asynchronous slave:
+
+{signal: [
+  {name: 'clk',  wave: 'p.....'},
+  {name: 'dat1', wave: 'x.=..x'},
+  {name: 'stb1', wave: '0.1..0'},
+  {name: 'cyc1', wave: '0.1..0'},
+  {name: 'ack1', wave: '0...10'},
+  {},
+  {name: 'dat2', wave: 'x..=.x'},
+  {name: 'stb2', wave: '0..10.'},
+  {name: 'cyc2', wave: '0..10.'},
+  {name: 'ack2', wave: '0..10.'}
+]}