README: Core Logic, Bus, Bank

README

@@ -78,8 +78,8 @@ cluttered syntax at times when writing descriptions in FHDL, but we
 believe this is totally acceptable, particularly when compared to VHDL
 ;-)
 
-Migen is made up of several related components, which are described
-below.
+Migen is made up of several related components, which are briefly
+described below.
 
 Migen FHDL
 ==========
@@ -237,16 +237,16 @@ For convenience, there is also a Elif() method.
 
 Example:
 If(tx_count16 == 0,
-	tx_bitcount.be(tx_bitcount + 1),
-	If(tx_bitcount == 8,
-		self.tx.be(1)
-	).Elif(tx_bitcount == 9,
-		self.tx.be(1),
-		tx_busy.be(0)
-	).Else(
-		self.tx.be(tx_reg[0]),
-		tx_reg.be(Cat(tx_reg[1:], 0))
-	)
+    tx_bitcount.be(tx_bitcount + 1),
+    If(tx_bitcount == 8,
+        self.tx.be(1)
+    ).Elif(tx_bitcount == 9,
+        self.tx.be(1),
+        tx_busy.be(0)
+    ).Else(
+        self.tx.be(tx_reg[0]),
+        tx_reg.be(Cat(tx_reg[1:], 0))
+    )
 )
 
 Case statement
@@ -317,20 +317,77 @@ autofragment module.
 
 Migen Core Logic
 ================
+Migen Core Logic is a convenience library of common logic circuits
+implemented using FHDL:
+  - a multi-cycle integer divider.
+  - a round-robin arbiter, useful to build bus arbiters.
+  - a multiplexer bank (multimux), useful to multiplex composite
+    (grouped) signals.
+  - a condition-triggered static scheduler of FHDL synchronous statements
+    (timeline).
 
 Migen Bus
 =========
-
+Migen Bus contains classes providing a common structure for master and
+slave interfaces of the following buses:
   - Wishbone [5], the general purpose bus recommended by Opencores.
   - CSR-NG, a low-bandwidth, resource-sensitive bus designed for
     accessing the configuration and status registers of cores from
     software.
   - FastMemoryLink-NG, a split-transaction bus optimized for use with a
     high-performance, out-of-order SDRAM controller. (TODO)
 
+It also provides interconnect components for these buses, such as
+arbiters and address decoders. The strength of the Migen procedurally
+generated logic can be illustrated by the following example:
+  wbcon = wishbone.InterconnectShared(
+      [cpu.ibus, cpu.dbus, ethernet.dma, audio.dma],
+      [(0, norflash.bus), (1, wishbone2fml.wishbone),
+      (3, wishbone2csr.wishbone)])
+In this example, the interconnect component generates a 4-way round-robin
+arbiter, multiplexes the master bus signals into a shared bus, determines
+that the address decoding must occur on 2 bits, and connects all slave
+interfaces to the shared bus, inserting the address decoder logic in the
+bus cycle qualification signals and multiplexing the data return path. It
+can recognize the signals in each core's bus interface thanks to the
+common structure mandated by Migen Bus. All this happens automatically,
+using only that much user code. The resulting interconnect logic can be
+retrieved using wbcon.get_fragment(), and combined with the fragments
+from the rest of the system.
+
 Migen Bank
 ==========
-
+Migen Bank is a system comparable to wishbone-gen [6], which automates
+the creation of configuration and status register banks and
+(TODO) interrupt/event managers implemented in cores.
+
+Bank takes a description made up of a list of registers and generates
+logic implementing it with a slave interface compatible with Migen Bus.
+
+A register can be "raw", which means that the core has direct access to
+it. It also means that the register width must be less or equal to the
+bus word width. In that case, the register object provides the following
+signals:
+  - dev_r, which contains the data written from the bus interface.
+  - dev_re, which is the strobe signal for dev_r. It is active for one
+    cycle, after or during a write from the bus. dev_r is only valid when
+    dev_re is high.
+  - dev_w, which must provide at all times the value to be read from the
+    bus.
+
+Registers that are not raw are managed by Bank and contain fields. If the
+sum of the widths of all fields attached to a register exceeds the bus
+word width, the register will automatically be sliced into words of the
+maximum size and implemented at consecutive bus addresses, MSB first.
+Field objects have two parameters, access_bus and access_dev, determining
+respectively the access policies for the bus and core sides. They can
+take the values READ_ONLY, WRITE_ONLY and READ_WRITE.
+If the device can read, the field object provides the dev_r signal, which
+contains at all times the current value of the field (kept by the logic
+generated by Bank).
+If the device can write, the field object provides the following signals:
+  - dev_w, which provides the value to be written into the field.
+  - dev_we, which strobes the value into the field.
 
 Migen Flow
 ==========
@@ -344,6 +401,7 @@ References:
 [3] http://milkymist.org/thesis/thesis.pdf
 [4] http://www.xilinx.com/publications/archives/xcell/Xcell77.pdf p30-35
 [5] http://cdn.opencores.org/downloads/wbspec_b4.pdf
+[6] http://www.ohwr.org/projects/wishbone-gen
 
 Practical information
 =====================