dsp rework: rehash of the custom module stuff and readme

1 files changed, 50 insertions, 3 deletions

diff --git a/README.txt b/README.txt
index bfdf317c1..29e891f6d 100644
--- a/README.txt
+++ b/README.txt
@@ -26,6 +26,53 @@ usrp2/
         3) make -f Makefile.<device> bin
         4) bin file in build-<device>/*.bin
 
-    Customize the DSP:
-        Implement design in usrp2/custom/custom_*.v
-        Instructions are included in the module.
+########################################################################
+## Customizing the DSP
+########################################################################
+
+As part of the USRP FPGA build-framework,
+there are several convenient places for users to insert
+custom DSP modules into the transmit and receive chains.
+
+* before the DDC module
+* after the DDC module
+* replace the DDC module
+* before the DUC module
+* after the DUC module
+* replace of the DUC module
+* as an RX packet engine
+* as an TX packet engine
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Customizing the top level makefile
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Each USRP device has a makefile associated with it.
+This makefile contains all of the necessary build rules.
+When making a customized FPGA design,
+start by copying the current makefile for your device.
+Makefiles can be found in the usrp2/top/<dir>/Makefile.*
+
+Edit your new makefile:
+* set BUILD_DIR to a unique directory name
+* set CUSTOM_SRCS for your verilog sources
+* set CUSTOM_DEFS (see section below)
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Inserting custom modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+CUSTOM_DEFS is a string of space-separate key-value pairs.
+Set the CUSTOM_DEFS variable so the FPGA fabric glue
+will substitute your custom modules into the DSP chain.
+
+Example:
+CUSTOM_DEFS = "TX_ENG0_MODULE=my_tx_engine RX_ENG0_MODULE=my_rx_engine"
+Where my_tx_engine and my_rx_engine are the names of custom verilog modules.
+
+The following module definition keys are possible (X is a DSP number):
+
+* TX_ENG<X>_MODULE: set the module for the transmit chain engine.
+* RX_ENG<X>_MODULE: set the module for the receive chain engine.
+* RX_DSP<X>_MODULE: set the module for the transmit dsp chain.
+* TX_DSP<X>_MODULE: set the module for the receive dsp chain.
+
+Examples of custom modules can be found in usrp2/custom/*.v