Incorporate feedback

docs/Customization/Dsptools-Blocks.rst

@@ -1,11 +1,24 @@
 .. _dsptools-blocks:
 
+Dsptools is a Chisel library that aids in writing custom signal processing accelerators. It does this by:
+* Giving types and helpers that allow you to express mathematical operations more directly.
+* Typeclasses that let you write polymorphic generators, for example an FIR filter generator that works for both real- and complex-valued filters.
+* Structures for packaging DSP blocks and integrating them into a rocketchip-based SoC.
+* Test harnesses for testing DSP circuits, as well as VIP-style drivers and monitors for DSP blocks.
+
+The `Dsptools <https://github.com/ucb-bar/dsptools/>`_ repository has more documentation.
+
+
 Dsptools Blocks
 ===============
+A ``DspBlock`` is the basic unit of signal processing functionality that can be integrated into an SoC.
+It has a AXI4-stream interface and an optional memory interface.
+The idea idea is that these ``DspBlocks`` can be easily designed, unit tested, and assembled lego-style to build complex functionality.
+A ``DspChain`` is one example of how to assemble ``DspBlocks``, in which case the streaming interfaces are connected serially into a pipeline, and a bus is instatiated and connected to every block with a memory interface.
  
-Another way to create a MMIO peripheral is to use the Dsptools library for Chisel. In this method, a memory interface is created by creating a "chain". This chain consists of a custom module placed inside a ``DspBlock``, which is then sandwiched between a ``ReadQueue`` and ``WriteQueue``. Those queues then act as memory mapped interfaces to the Rocket Chip SoCs. This section will again primarily focus on designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps.
+This project has example designs that integrate a ``DspBlock`` to a rocketchip-based SoC as an MMIO peripheral. The custom ``DspBlock`` has a ``ReadQueue`` before it and a ``WriteQueue`` after it, which allow memory mapped access to the streaming interfaces so the rocket core can interact with the ``DspBlock``.  This section will primarily focus on designing Tilelink-based peripherals. However, through the resources provided in Dsptools, one could also define an AXI4-based peripheral by following similar steps. Furthermore, the examples here are simple, but can be extended to implement more complex accelerators, for example an `OFDM baseband <https://github.com/grebe/ofdm>`_ or a `spectrometer <https://github.com/ucb-art/craft2-chip>`_.
 
-For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO
+For this example, we will show you how to connect a simple FIR filter created using Dsptools as an MMIO peripheral. The full code can be found in ``generators/example/src/main/scala/dsptools/GenericFIR.scala``. That being said, one could substitute any module with a ready valid interface in the place of the FIR and achieve the same results. As long as the read and valid signals of the module are attached to those of a corresponding ``DSPBlock`` wrapper, and that wrapper is placed in a chain with a ``ReadQueue`` and a ``WriteQueue``, following the general outline establised by these steps will allow you to interact with that block as a memory mapped IO.
 
 The module ``GenericFIR`` is the overall wrapper of our FIR module. This module links together a variable number of ``GenericFIRDirectCell`` submodules, each of which performs the computations for one coefficient in a FIR direct form architecture. It is important to note that both modules are type generic, which means that they can be instantiated for any datatype that implements ``Ring`` operations per the specifications on ``T``.
 
@@ -56,10 +69,10 @@ As in the previous MMIO example, we use a cake pattern to hook up our module to
 
 .. literalinclude:: ../../generators/example/src/main/scala/dsptools/GenericFIR.scala
     :language: scala
-    :start-after: DOC include start: CanHavePeripheryUIntTestFIR chisel
-    :end-before: DOC include end: CanHavePeripheryUIntTestFIR chisel
+    :start-after: DOC include start: CanHavePeripheryFIR chisel
+    :end-before: DOC include end: CanHavePeripheryFIR chisel
 
-Note that this is the point at which we decide the datatype for our FIR. It is also possible with some reworking to push the datatype selection out to the top level.
+Note that this is the point at which we decide the datatype for our FIR.
 
 Our module does not need to be connected to concrete IOs or wires, so we do not need to create a concrete trait.
 
@@ -73,12 +86,12 @@ Once again following the path of the previous MMIO example, we now want to mix o
     :start-after: DOC include start: Top
     :end-before: DOC include end: Top
 
-Finally, we create the configuration class in ``generators/example/src/main/scala/RocketConfigs.scala`` that uses the ``WithUIntTestFIR`` mixin defined in ``generators/example/src/main/scala/ConfigMixins.scala``.
+Finally, we create the configuration class in ``generators/example/src/main/scala/RocketConfigs.scala`` that uses the ``WithFIR`` mixin defined in ``generators/example/src/main/scala/ConfigMixins.scala``.
 
 .. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
     :language: scala
-    :start-after: DOC include start: WithTestFIR
-    :end-before: DOC include end: WithTestFIR
+    :start-after: DOC include start: WithFIR
+    :end-before: DOC include end: WithFIR
 
 .. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
     :language: scala
@@ -88,7 +101,7 @@ Finally, we create the configuration class in ``generators/example/src/main/scal
 Testing
 -------
 
-We can now test that the FIR is working. The test program is found in ``tests/gcd.c``.
+We can now test that the FIR is working. The test program is found in ``tests/fir.c``.
 
 .. literalinclude:: ../../tests/fir.c
     :language: c