Merge remote-tracking branch 'origin/dev' into alon-docs-dev

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/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -1,6 +1,13 @@
 Initial Repository Setup
 ========================================================
 
+Requirements
+-------------------------------------------
+
+Chipyard is developed and tested on Linux-based systems.
+It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
+Working under Windows is not recommended.
+
 Checking out the sources
 ------------------------
 
@@ -28,6 +35,6 @@ But to get a basic installation, just the following steps are necessary.
 
     ./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions
 
-Once the script is run, a ``env.sh`` file is emitted at sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
+Once the script is run, a ``env.sh`` file is emitted that sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
 You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables.
 These variables need to be set for the make system to work properly.

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

@@ -1,12 +1,19 @@
+.. _generator-index:
+
 Generators
 ============================
 
-Generator can be thought of as a generalized RTL design, written using a mix of meta-programming and standard RTL.
+A Generator can be thought of as a generalized RTL design, written using a mix of meta-programming and standard RTL.
 This type of meta-programming is enabled by the Chisel hardware description language (see :ref:`Chisel`).
 A standard RTL design is essentially just a single instance of a design coming from a generator.
 However, by using meta-programming and parameter systems, generators can allow for integration of complex hardware designs in automated ways.
 The following pages introduce the generators integrated with the Chipyard framework.
 
+Chipyard bundles the source code for the generators, under the ``generators`` directory.
+It builds them from source each time (although the build system will cache results if they have not changed),
+so changes to the generators themselves will automatically be used when building with Chipyard and propagate to software simulation, FPGA-accelerated simulation, and VLSI flows.
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Generators:
@@ -15,5 +22,7 @@ The following pages introduce the generators integrated with the Chipyard framew
    Rocket
    BOOM
    Hwacha
+   IceNet
+   TestChipIP
    SiFive-Generators   
    SHA3

docs/Quick-Start.rst

@@ -1,6 +1,13 @@
 Quick Start
 ===============================
 
+Requirements
+-------------------------------------------
+
+Chipyard is developed and tested on Linux-based systems.
+It is possible to use this on macOS or other BSD-based systems, although GNU tools will need to be installed; it is also recommended to install the RISC-V toolchain from ``brew``.
+Working under Windows is not recommended.
+
 Setting up the Chipyard Repo
 -------------------------------------------
 
@@ -49,7 +56,8 @@ This depends on what you are planning to do with Chipyard.
 
 * If you want to learn about the structure of Chipyard, go to :ref:`chipyard-components`.
 
+* If you intend to change the generators (BOOM, Rocket, etc) themselves, see :ref:`generator-index`.
+
 * If you intend to run a VLSI flow using one of the vanilla Chipyard examples, go to <> and follow the instructions.
 
 * If you intend to build a chip using one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
-

docs/Software/FireMarshal.rst

@@ -0,0 +1,23 @@
+FireMarshal
+=================
+
+FireMarshal is a workload generation tool for RISC-V based systems. It
+currently only supports the FireSim FPGA-accelerated simulation platform.
+
+**Workloads** in FireMarshal consist of a series of **Jobs** that are assigned
+to logical nodes in the target system. If no jobs are specified, then the
+workload is considered ``uniform`` and only a single image will be produced for
+all nodes in the system. Workloads are described by a ``json`` file and a
+corresponding workload directory and can inherit their definitions from
+existing workloads. Typically, workload configurations are kept in
+``workloads/`` although you can use any directory you like. We provide a few
+basic workloads to start with including buildroot or Fedora-based linux
+distributions and bare-metal.
+
+Once you define a workload, the ``marshal`` command will produce a
+corresponding boot-binary and rootfs for each job in the workload. This binary
+and rootfs can then be launched on qemu or spike (for functional simulation), or
+installed to a platform for running on real RTL (currently only FireSim is
+automated).
+
+To get started, checkout the full `FireMarshal documentation <https://firemarshal.readthedocs.io/en/latest/index.html>`_.

docs/Software/Spike.rst

@@ -0,0 +1,4 @@
+The RISC-V ISA Simulator (Spike)
+=================================
+
+.. attention:: This article is a stub. Fill it out!

docs/Software/index.rst

@@ -0,0 +1,21 @@
+Target Software
+==================================
+
+Chipyard includes tools for developing target software workloads. The primary
+tool is FireMarshal, which manages workload descriptions and generates binaries
+and disk images to run on your target designs. Workloads can be bare-metal, or
+be based on standard Linux distributions. Users can customize every part of the
+build process, including providing custom kernels (if needed by the hardware).
+
+FireMarshal can also run your workloads on high-performance functional
+simulators like Spike and Qemu. Spike is easily customized and serves as the
+official RISC-V ISA reference implementation. Qemu is a high-performance
+functional simulator that can run nearly as fast as native code, but can be
+challenging to modify.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   FireMarshal
+   Spike

docs/index.rst

@@ -38,6 +38,8 @@ Table of Contents
 
    Customization/index
 
+   Software/index
+
    Advanced-Usage/index
 
    TileLink-Diplomacy-Reference/index