From 2f3c87dade24f918b07b27e3ed6c17140f8035cd Mon Sep 17 00:00:00 2001
From: Howard Mao <zhehao.mao@gmail.com>
Date: Wed, 25 Sep 2019 17:25:38 -0700
Subject: [PATCH] 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 <https://fires.im/>`_. A diagram of IceNet's microarchitecture
-is shown below.
+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
 
@@ -68,7 +68,7 @@ Linux Driver
 ------------
 
 The default Linux configuration provided by `firesim-software <https://github.com/firesim/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.