From f7138a8d715420777a04aeba4135d50662e1a229 Mon Sep 17 00:00:00 2001 From: Brendan Sweeney Date: Wed, 25 Sep 2019 12:53:08 -0700 Subject: [PATCH 01/15] Notes on building with macOS doesn't really work --- docs/Chipyard-Basics/Initial-Repo-Setup.rst | 17 ++++++++++++++++- docs/Quick-Start.rst | 15 +++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst index 7b7042ee..5375a604 100644 --- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst +++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst @@ -1,6 +1,21 @@ Initial Repository Setup ======================================================== +Requirements +------------------------------------------- + +Using Linux is recommended. +The provided scripts will not work on macOS out of the box, but they may be able to be modified to support it. +Working under Windows is not recommended. + +* dtc (design-tree-compiler) + +* GNU awk + +* GNU sed + +* GNU make + Checking out the sources ------------------------ @@ -28,6 +43,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/Quick-Start.rst b/docs/Quick-Start.rst index 86d62b11..65b854b9 100644 --- a/docs/Quick-Start.rst +++ b/docs/Quick-Start.rst @@ -1,6 +1,21 @@ Quick Start =============================== +Requirements +------------------------------------------- + +Using Linux is recommended. +The provided scripts will not work on macOS out of the box, but they may be able to be modified to support it. +Working under Windows is not recommended. + +* dtc (design-tree-compiler) + +* GNU awk + +* GNU sed + +* GNU make + Setting up the Chipyard Repo ------------------------------------------- From 12d4e7d8372c0b4efd357d5b4feeb0596206651b Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 11:24:08 -0700 Subject: [PATCH 02/15] add section on IceNet [ci skip] --- docs/Generators/IceNet.rst | 73 +++++++++++++++++++++++++++++ docs/Generators/index.rst | 1 + docs/_static/images/nic-design.png | Bin 0 -> 20566 bytes 3 files changed, 74 insertions(+) create mode 100644 docs/Generators/IceNet.rst create mode 100644 docs/_static/images/nic-design.png diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst new file mode 100644 index 00000000..2b3ac596 --- /dev/null +++ b/docs/Generators/IceNet.rst @@ -0,0 +1,73 @@ +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 `_. 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 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. diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index a147ffeb..a3594666 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -15,3 +15,4 @@ The following pages introduce the generators integrated with the Chipyard framew BOOM Hwacha RocketChip + IceNet diff --git a/docs/_static/images/nic-design.png b/docs/_static/images/nic-design.png new file mode 100644 index 0000000000000000000000000000000000000000..0ebaf0e0a41424ffeefa8c722e82888b00125a07 GIT binary patch literal 20566 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

sH=P4?|; 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

  • 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 literal 0 HcmV?d00001 From c8e846518058f4b34364b1f8ef041e64505dbeb3 Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 13:01:51 -0700 Subject: [PATCH 03/15] add Test Chip IP section [ci skip] --- docs/Generators/TestChipIP.rst | 51 ++++++++++++++++++++++++++++++++++ docs/Generators/index.rst | 1 + 2 files changed, 52 insertions(+) create mode 100644 docs/Generators/TestChipIP.rst diff --git a/docs/Generators/TestChipIP.rst b/docs/Generators/TestChipIP.rst new file mode 100644 index 00000000..cf4dc64b --- /dev/null +++ b/docs/Generators/TestChipIP.rst @@ -0,0 +1,51 @@ +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 `_ + +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. + +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. diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index a3594666..674decd7 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -16,3 +16,4 @@ The following pages introduce the generators integrated with the Chipyard framew Hwacha RocketChip IceNet + TestChipIP From a3a05ec9881144ba3535adb06ea81de04109f8d2 Mon Sep 17 00:00:00 2001 From: Brendan Sweeney Date: Wed, 25 Sep 2019 13:45:21 -0700 Subject: [PATCH 04/15] [docs] [ci skip] Update generators and quick start so it is clear how to edit the generators to get changed outputs (You just edit the source) --- docs/Generators/index.rst | 8 +++++++- docs/Quick-Start.rst | 2 ++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index a01b5adc..8bd17024 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -1,12 +1,18 @@ +.. _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 ``sbt`` will cache results if they have not changed), +so changes to the generators themselves will automatically be used when building with Chipyard. + .. toctree:: :maxdepth: 2 :caption: Generators: diff --git a/docs/Quick-Start.rst b/docs/Quick-Start.rst index 86d62b11..8d45e436 100644 --- a/docs/Quick-Start.rst +++ b/docs/Quick-Start.rst @@ -52,3 +52,5 @@ This depends on what you are planning to do with Chipyard. * To run a FPGA-accelerated simulation using FireSim, see :ref:`firesim-sim-intro`. * To run a VLSI flow using one of the vanilla Chipyard examples, see <>. + +* To change the generators (BOOM, Rocket, &c) themselves, see :ref:`generator-index`. From 9dc0abb4854e6b626961aff7ff67771140350eee Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 16:41:32 -0700 Subject: [PATCH 05/15] explain how to add IceNet and TestChipIP hardware to design --- docs/Generators/IceNet.rst | 11 +++++++++++ docs/Generators/TestChipIP.rst | 12 ++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst index 2b3ac596..4dca3daa 100644 --- a/docs/Generators/IceNet.rst +++ b/docs/Generators/IceNet.rst @@ -71,3 +71,14 @@ The default Linux configuration provided by `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 --------------- @@ -38,6 +43,10 @@ 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 ----------------- @@ -49,3 +58,6 @@ 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 `_. From e8a197d8a85f8d9e43b451b5c37c6c1e7eda619b Mon Sep 17 00:00:00 2001 From: Brendan Sweeney Date: Wed, 25 Sep 2019 17:18:27 -0700 Subject: [PATCH 06/15] [docs] [ci skip] --- docs/Generators/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index 8bd17024..0e120e45 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -10,7 +10,7 @@ However, by using meta-programming and parameter systems, generators can allow f 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 ``sbt`` will cache results if they have not changed), +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. .. toctree:: From 824c3177d8a96ccf147eb30ca26e87e05f746c26 Mon Sep 17 00:00:00 2001 From: Nathan Pemberton Date: Wed, 25 Sep 2019 17:22:18 -0700 Subject: [PATCH 07/15] Added software section. Marshal is populated (mostly points to Marshal's own readthedocs). Spike is a stub. --- docs/Software/FireMarshal.rst | 23 +++++++++++++++++++++++ docs/Software/Spike.rst | 4 ++++ docs/Software/index.rst | 21 +++++++++++++++++++++ docs/index.rst | 2 ++ 4 files changed, 50 insertions(+) create mode 100644 docs/Software/FireMarshal.rst create mode 100644 docs/Software/Spike.rst create mode 100644 docs/Software/index.rst diff --git a/docs/Software/FireMarshal.rst b/docs/Software/FireMarshal.rst new file mode 100644 index 00000000..cbece68d --- /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/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 From 2f3c87dade24f918b07b27e3ed6c17140f8035cd Mon Sep 17 00:00:00 2001 From: Howard Mao Date: Wed, 25 Sep 2019 17:25:38 -0700 Subject: [PATCH 08/15] add explanation of LazyModule vs. LazyModuleImp [skip ci] --- .../Configs-Parameters-Mixins.rst | 17 +++++++++++++++-- docs/Generators/IceNet.rst | 13 ++++++++----- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 2d93f2b3..b1d6ebd0 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -80,16 +80,29 @@ 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) } + 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 and one for the module +implementation. The lazy module defines all the logical connections between +generators and exchanges configuration information among them, while the +module implementation performs the actual Chisel RTL elaboration. + Mix-in --------------------------- diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst index 4dca3daa..b520eb6c 100644 --- a/docs/Generators/IceNet.rst +++ b/docs/Generators/IceNet.rst @@ -3,8 +3,8 @@ 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 `_. A diagram of IceNet's microarchitecture -is shown below. +in `FireSim `_ for multi-node networked simulation. +A diagram of IceNet's microarchitecture is shown below. .. image:: ../_static/images/nic-design.png @@ -68,7 +68,7 @@ Linux Driver ------------ The default Linux configuration provided by `firesim-software `_ -contains an IceNet driver. If launch a FireSim image that has IceNIC on it, +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. @@ -76,9 +76,12 @@ Configuration ------------- To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module -and ``HasPeripheryIceNICModuleImp`` to the module implementation. +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 mixin +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. From 438bb8c785f84b5e0aceddb55dd7163012d28ffb Mon Sep 17 00:00:00 2001 From: Brendan Sweeney Date: Wed, 25 Sep 2019 17:26:44 -0700 Subject: [PATCH 09/15] [docs] [skip ci] Change based on Abe's comments --- docs/Chipyard-Basics/Initial-Repo-Setup.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst index 5375a604..499939f4 100644 --- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst +++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst @@ -4,18 +4,10 @@ Initial Repository Setup Requirements ------------------------------------------- -Using Linux is recommended. -The provided scripts will not work on macOS out of the box, but they may be able to be modified to support it. +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. -* dtc (design-tree-compiler) - -* GNU awk - -* GNU sed - -* GNU make - Checking out the sources ------------------------ From 23b667ad765f345fc3a4a787d79197ce161bb31e Mon Sep 17 00:00:00 2001 From: Brendan Sweeney Date: Wed, 25 Sep 2019 17:27:10 -0700 Subject: [PATCH 10/15] [ci skip] [docs] Abe's comments 2 --- docs/Quick-Start.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/Quick-Start.rst b/docs/Quick-Start.rst index 65b854b9..da2e2abc 100644 --- a/docs/Quick-Start.rst +++ b/docs/Quick-Start.rst @@ -4,18 +4,10 @@ Quick Start Requirements ------------------------------------------- -Using Linux is recommended. -The provided scripts will not work on macOS out of the box, but they may be able to be modified to support it. +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. -* dtc (design-tree-compiler) - -* GNU awk - -* GNU sed - -* GNU make - Setting up the Chipyard Repo ------------------------------------------- From c4c8cc65afb5bb68d8ab8a28a8949191c4c10151 Mon Sep 17 00:00:00 2001 From: Brendan Sweeney Date: Wed, 25 Sep 2019 17:56:16 -0700 Subject: [PATCH 11/15] [docs] [ci skip] Alon's comments --- docs/Generators/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index 0e120e45..b93a3681 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -11,7 +11,8 @@ The following pages introduce the generators integrated with the Chipyard framew 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. +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 From 7cfac672c14759a0821aa6046b5136247adbba98 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Wed, 25 Sep 2019 19:34:47 -0700 Subject: [PATCH 12/15] Update docs/Chipyard-Basics/Configs-Parameters-Mixins.rst [skip ci] Co-Authored-By: Jerry Zhao --- .../Configs-Parameters-Mixins.rst | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index b1d6ebd0..1f726f51 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -103,7 +103,32 @@ implementation. The lazy module defines all the logical connections between generators and exchanges configuration information among them, while the module implementation performs the actual Chisel RTL elaboration. -Mix-in +In the MySoC example class, the "outer" ``MySoC`` instantiates the "inner" +``MySoCModuleImp`` as a lazy module. This delays immediate elaboration +of the module. 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 frontbus. + +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. This is very advanced). + + 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. From d0e5a4068704c6ab65369caadfa9a2d1bd2d3068 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 20:02:16 -0700 Subject: [PATCH 13/15] slightly more clarity in the diplomacy example [skip ci] --- .../Configs-Parameters-Mixins.rst | 41 ++++++++++--------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 1f726f51..864bd969 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -98,36 +98,37 @@ This example shows a Rocket Chip based SoC that merges multiple system component with HasPeripheryUARTModuleImp with HasPeripheryIceNICModuleImp -There are two "cakes" here. One for the lazy module and one for the module -implementation. The lazy module defines all the logical connections between -generators and exchanges configuration information among them, while the -module implementation performs the actual Chisel RTL elaboration. +There are two "cakes" here. One for the lazy module (ex. ``HasNoDebug``) and one for the lazy module +implementation (ex. ``HasNoDebugModuleImp`` 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. This delays immediate elaboration -of the module. The ``RocketSubsystem`` outer base class, as well as the -``HasPeripheryX`` outer traits contain code to perform high-level logical +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 frontbus. +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. +the ``SerialAdapter`` module, and instantiates queues. -In the test harness, the SoC is elaborated with -``val dut = Module(LazyModule(MySoC))``. +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 +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. This is very advanced). - +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 --------------------------- From eb7fbec624777dc4d60f6f97938b3484cdbf87b9 Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Wed, 25 Sep 2019 20:06:58 -0700 Subject: [PATCH 14/15] Update docs/Software/FireMarshal.rst [skip ci] --- docs/Software/FireMarshal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Software/FireMarshal.rst b/docs/Software/FireMarshal.rst index cbece68d..ecc23736 100644 --- a/docs/Software/FireMarshal.rst +++ b/docs/Software/FireMarshal.rst @@ -7,7 +7,7 @@ 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 +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 From 461829678edd10bf616db6fbbe0737e05f54b132 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 25 Sep 2019 20:24:20 -0700 Subject: [PATCH 15/15] switch from no debug to peripheryserial [skip ci] --- docs/Chipyard-Basics/Configs-Parameters-Mixins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index 864bd969..e83bc9e2 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -98,8 +98,8 @@ This example shows a Rocket Chip based SoC that merges multiple system component with HasPeripheryUARTModuleImp with HasPeripheryIceNICModuleImp -There are two "cakes" here. One for the lazy module (ex. ``HasNoDebug``) and one for the lazy module -implementation (ex. ``HasNoDebugModuleImp`` where ``Imp`` refers to implementation). The lazy module defines +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.