diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 2d93f2b3..e83bc9e2 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/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. diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst index 7b7042ee..499939f4 100644 --- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst +++ b/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. diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst new file mode 100644 index 00000000..b520eb6c --- /dev/null +++ b/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 `_ 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 `_ +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 `_ +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. diff --git a/docs/Generators/TestChipIP.rst b/docs/Generators/TestChipIP.rst new file mode 100644 index 00000000..7d490c5f --- /dev/null +++ b/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 `_ + +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 +`_. + +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 `_. diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index c917db05..462c20e2 100644 --- a/docs/Generators/index.rst +++ b/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 diff --git a/docs/Quick-Start.rst b/docs/Quick-Start.rst index eb7ba3e5..542e3a30 100644 --- a/docs/Quick-Start.rst +++ b/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. - diff --git a/docs/Software/FireMarshal.rst b/docs/Software/FireMarshal.rst new file mode 100644 index 00000000..ecc23736 --- /dev/null +++ b/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 `_. diff --git a/docs/Software/Spike.rst b/docs/Software/Spike.rst new file mode 100644 index 00000000..015ec5b2 --- /dev/null +++ b/docs/Software/Spike.rst @@ -0,0 +1,4 @@ +The RISC-V ISA Simulator (Spike) +================================= + +.. attention:: This article is a stub. Fill it out! diff --git a/docs/Software/index.rst b/docs/Software/index.rst new file mode 100644 index 00000000..e7fe9925 --- /dev/null +++ b/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 diff --git a/docs/_static/images/nic-design.png b/docs/_static/images/nic-design.png new file mode 100644 index 00000000..0ebaf0e0 Binary files /dev/null and b/docs/_static/images/nic-design.png differ diff --git a/docs/index.rst b/docs/index.rst index 61acfae3..75c3714e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,6 +38,8 @@ Table of Contents Customization/index + Software/index + Advanced-Usage/index TileLink-Diplomacy-Reference/index