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/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 f48e24f8..462c20e2 100644 --- a/docs/Generators/index.rst +++ b/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 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