Merge pull request #252 from ucb-bar/howie-docs

Basic IceNet and Test Chip IP docs

docs/Chipyard-Basics/Configs-Parameters-Mixins.rst

@@ -80,17 +80,56 @@ This example shows a Rocket Chip based SoC that merges multiple system component
 .. code-block:: scala
 
   class MySoC(implicit p: Parameters) extends RocketSubsystem
-    with CanHaveMisalignedMasterAXI4MemPort
+    with CanHaveMasterAXI4MemPort
     with HasPeripheryBootROM
     with HasNoDebug
     with HasPeripherySerial
     with HasPeripheryUART
     with HasPeripheryIceNIC
   {
-     //Additional top-level specific instantiations or wiring
+     lazy val module = new MySoCModuleImp(this)
   }
 
-Mix-in
+  class MySoCModuleImp(outer: MySoC) extends RocketSubsystemModuleImp(outer)
+    with CanHaveMasterAXI4MemPortModuleImp
+    with HasPeripheryBootROMModuleImp
+    with HasNoDebugModuleImp
+    with HasPeripherySerialModuleImp
+    with HasPeripheryUARTModuleImp
+    with HasPeripheryIceNICModuleImp
+
+There are two "cakes" here. One for the lazy module (ex. ``HasPeripherySerial``) and one for the lazy module
+implementation (ex. ``HasPeripherySerialModuleImp`` where ``Imp`` refers to implementation). The lazy module defines
+all the logical connections between generators and exchanges configuration information among them, while the
+lazy module implementation performs the actual Chisel RTL elaboration.
+
+In the MySoC example class, the "outer" ``MySoC`` instantiates the "inner"
+``MySoCModuleImp`` as a lazy module implementation. This delays immediate elaboration
+of the module until all logical connections are determined and all configuration information is exchanged.
+The ``RocketSubsystem`` outer base class, as well as the
+``HasPeripheryX`` outer traits contain code to perform high-level logical
+connections. For example, the ``HasPeripherySerial`` outer trait contains code
+to lazily instantiate the ``SerialAdapter``, and connect the ``SerialAdapter``'s
+TileLink node to the Front bus.
+
+The ``ModuleImp`` classes and traits perform elaboration of real RTL.
+For example, the ``HasPeripherySerialModuleImp`` trait physically connects
+the ``SerialAdapter`` module, and instantiates queues.
+
+In the test harness, the SoC is elaborated with
+``val dut = Module(LazyModule(MySoC))``.
+After elaboration, the result will be a MySoC module, which contains a
+SerialAdapter module (among others).
+
+From a high level, classes which extend LazyModule *must* reference
+their module implementation through ``lazy val module``, and they
+*may* optionally reference other lazy modules (which will elaborate
+as child modules in the module hierarchy). The "inner" modules
+contain the implementation for the module, and may instantiate
+other normal modules OR lazy modules (for nested Diplomacy
+graphs, for example).
+
+ Mix-in
 ---------------------------
 
 A mix-in is a Scala trait, which sets parameters for specific system components, as well as enabling instantiation and wiring of the relevant system components to system buses.

docs/Generators/IceNet.rst

@@ -0,0 +1,87 @@
+IceNet
+======
+
+IceNet is a library of Chisel designs related to networking. The main component
+of IceNet is IceNIC, a network interface controller that is used primarily
+in `FireSim <https://fires.im/>`_ for multi-node networked simulation.
+A diagram of IceNet's microarchitecture is shown below.
+
+.. image:: ../_static/images/nic-design.png
+
+There are four basic parts of the NIC: the :ref:`Controller`, which takes requests 
+from and sends responses to the CPU; the :ref:`Send Path`, which reads data from
+memory and sends it out to the network; the :ref:`Receive Path`, which receives
+data from the network and writes it to memory; and, optionally,
+the :ref:`Pause Handler`, which generates Ethernet pause frames for the purpose
+of flow control.
+
+Controller
+----------
+
+The controller exposes a set of MMIO registers to the CPU. The device driver
+writes to registers to request that packets be sent or to provide memory
+locations to write received data to. Upon the completion of a send request or
+packet receive, the controller sends an interrupt to the CPU, which clears
+the completion by reading from another register.
+
+Send Path
+---------
+
+The send path begins at the reader, which takes requests from the controller
+and reads the data from memory.
+
+Since TileLink responses can come back out-of-order, we use a reservation
+queue to reorder responses so that the packet data can be sent out in the
+proper order.
+
+The packet data then goes to an arbiter, which can arbitrate access to the
+outbound network interface between the NIC and one or more "tap in" interfaces,
+which come from other hardware modules that may want to send Ethernet packets.
+By default, there are no tap in interfaces, so the arbiter simply passes
+the output of the reservation buffer through.
+
+Receive Path
+------------
+
+The receive path begins with the packet buffer, which buffers data coming
+in from the network. If there is insufficient space in the buffer, it will
+drop data at packet granularity to ensure that the NIC does not deliver
+incomplete packets.
+
+From the packet buffer, the data can optionally go to a network tap, which
+examines the Ethernet header and select packets to be redirected from the NIC
+to external modules through one or more "tap out" interfaces. By default, there
+are no tap out interfaces, so the data will instead go directly to the writer,
+which writes the data to memory and then sends a completion to the controller.
+
+Pause Handler
+-------------
+
+IceNIC can be configured to have pause handler, which sits between the
+send and receive paths and the Ethernet interface. This module tracks the
+occupancy of the receive packet buffer. If it sees the buffer filling up, it
+will send an `Ethernet pause frame <https://en.wikipedia.org/wiki/Ethernet_flow_control#Pause_frame>`_
+out to the network to block further packets from being sent. If the NIC receives
+an Ethernet pause frame, the pause handler will block sending from the NIC.
+
+Linux Driver
+------------
+
+The default Linux configuration provided by `firesim-software <https://github.com/firesim/firesim-software>`_
+contains an IceNet driver. If you launch a FireSim image that has IceNIC on it,
+the driver will automatically detect the device, and you will be able to use
+the full Linux networking stack in userspace.
+
+Configuration
+-------------
+
+To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module
+and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you
+are confused about the distinction between lazy module and module
+implementation, refer to :ref:`Cake Pattern`.
+
+Then add the ``WithIceNIC`` config mixin to your configuration. This will
+define ``NICKey``, which IceNIC uses to determine its parameters. The mixin
+takes two arguments. The ``inBufFlits`` argument is the number of 64-bit flits
+that the input packet buffer can hold and the ``usePauser`` argument determines
+whether or not the NIC will have a pause handler.

docs/Generators/TestChipIP.rst

@@ -0,0 +1,63 @@
+Test Chip IP
+============
+
+Chipyard includes a Test Chip IP library which provides various hardware
+widgets that may be useful when designing SoCs. This includes a :ref:`Serial Adapter`,
+:ref:`Block Device Controller`, :ref:`TileLink SERDES`, and :ref:`TileLink Switcher`.
+
+Serial Adapter
+--------------
+
+The serial adapter is used by tethered test chips to communicate with the host
+processor. An instance of RISC-V frontend server running on the host CPU 
+can send commands to the serial adapter to read and write data from the memory
+system. The frontend server uses this functionality to load the test program
+into memory and to poll for completion of the program. More information on
+this can be found in :ref:`Chipyard Boot Process`.
+
+Block Device Controller
+-----------------------
+
+The block device controller provides a generic interface for secondary storage.
+This device is primarily used in FireSim to interface with a block device
+software simulation model. The default Linux configuration in `firesim-software <https://github.com/firesim/firesim-software>`_
+
+To add a block device to your design, add ``HasPeripheryBlockDevice`` to your
+lazy module and ``HasPeripheryBlockDeviceModuleImp`` to the implementation.
+Then add the ``WithBlockDevice`` config mixin to your configuration.
+
+
+TileLink SERDES
+---------------
+
+The TileLink SERDES in the Test Chip IP library allow TileLink memory requests
+to be serialized so that they can be carried off chip through a serial link.
+The five TileLink channels are multiplexed over two SERDES channels, one in
+each direction.
+
+There are three different variants provided by the library, ``TLSerdes``
+exposes a manager interface to the chip, tunnels A, C, and E channels on
+its outbound link, and tunnels B and D channels on its inbound link. ``TLDesser``
+exposes a client interface to the chip, tunnels A, C, and E on its inbound link,
+and tunnels B and D on its outbound link. Finally, ``TLSerdesser`` exposes
+both client and manager interface to the chip and can tunnel all channels in
+both directions.
+
+For an example of how to use the SERDES classes, take a look at the
+``SerdesTest`` unit test in `the Test Chip IP unit test suite
+<https://github.com/ucb-bar/testchipip/blob/master/src/main/scala/Unittests.scala>`_.
+
+TileLink Switcher
+-----------------
+
+The TileLink switcher is used when the chip has multiple possible memory
+interfaces and you would like to select which channels to map your memory
+requests to at boot time. It exposes a client node, multiple manager nodes,
+and a select signal. Depending on the setting of the select signal, requests
+from the client node will be directed to one of the manager nodes.
+The select signal must be set before any TileLink messages are sent and be
+kept stable throughout the remainder of operation. It is not safe to change
+the select signal once TileLink messages have begun sending.
+
+For an example of how to use the switcher, take a look at the ``SwitcherTest``
+unit test in the `Test Chip IP unit tests <https://github.com/ucb-bar/testchipip/blob/master/src/main/scala/Unittests.scala>`_.

docs/Generators/index.rst

@@ -22,5 +22,7 @@ so changes to the generators themselves will automatically be used when building
    Rocket
    BOOM
    Hwacha
+   IceNet
+   TestChipIP
    SiFive-Generators   
    SHA3