Part 3 of refactoring template files into ./contrib

Docs!

1 files changed, 59 insertions, 43 deletions

diff --git a/README b/README
index 826715e..e303770 100644
--- a/README
+++ b/README
@@ -1,31 +1,48 @@
 
-A very basic project template for Verilog simulation and synthesis using Isim
-and Xilinx tools. 
+* * < DELTEME > * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
-Contents:
+This folder contains a template Verilog/VHDL HDL project with a basic build
+system for using the Xilinx ISE toolchain to target FPGAs.                  
+                                                                            
+When using this as a project template, edit this file and then delete this
+section. See ./contrib/QUICK_START.txt for help setting up a new project. At a
+minimum you will need to copy ./contrib/Makefile.example to ./Makefile.     
+                                                                            
+Hint: search this file for "<board>"                                        
+
+* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+
+== About =====================================================================
+
+<fill this part in>
+
+See COPYING for copyright and licensing information.
+
+This folder contains Verilog/VHDL source code and a build system based on the
+no-cost Xilinx ISE WebPack toolchain for simulating and synthesizing targeting
+FPGAs.
+
+== Repository Contents =======================================================
 
   hdl/
-    Verilog Code
+    Synthesizable Verilog and VHDL source code
 
   tb/
-    "testbench" simulation code
+    Testbench simulation source code, unit tests, related data and scripts
 
   docs/
-    documentation
+    Documentation might live here
 
   contrib/
     Project-independent build scripts are set here
 
   backup/
-    A handful of old "known-good" bitfiles can get archived here.
-
-  sngdaq.ucf
-    Wired Leaf pinout definition file
+    A handful of old "known-good" bitfiles might get archived here.
 
   Makefile
     Project-specific build variables are set here
 
-== HOWTO Build a Bitfile =====================================================
+== Synthesis =================================================================
 
 The Xilinx ISE development must be installed and licensed on the local machine.
 A set of command-line build scripts are usually used to build the project
@@ -33,55 +50,54 @@ instead of the ISE IDE, but the later could be configured and used as well.
 
 Python and GNU make must be on the $PATH.
 
-Build a bitstream (to upload to an FPGA, preconfigured as Spartan 6 chip in
-Makefile) via:
+Synthesize a bitfile with:
 
     make
 
+To upload the bitfile over JTAG using the Xilinx Impact utility, run the
+command below. There may be other upload board-specific upload mechanisms; look
+elsewhere in this file or for a README in ./contrib/<board>.
+
 The toplevel ucf (constraints mapping netlist objects from the verilog
 compilation to hardware resources, and place and routing and timing
-constraints) is:
-
-    ./sngdaq.ucf
-
-The toplevel verilog module, which does nothing (just sets some pins to zero)
-lives in:
-
-    ./hdl/sngdaq.v
+constraints) will either be a .ucf file in this top directory, or, if a board
+template was used, might live in ./contrib/<board>/<board>.ucf.
 
-To edit the project with the ISE GUI, try:
+The toplevel verilog module, which probably does nothing (just sets some pins
+to zero) lives in:
 
-    make ise
+    ./hdl/main_<board>.v
 
-WARNING: the ISE configuration options may or may not be synchronized with the
-command line build options. Edit the options in project.opt and build only from
-the command line to be safe.
+To load a synthesized bitfile, 
 
-Simulate with isim via:
+== Simulation ================================================================
 
-    make simulate
+To simulate the testbench in ./tb/<testbench>_tb with the isim GUI:
 
-View the results using the isim GUI with:
+    make isim/<testbench>_tb
 
-    make isim
+A "tb/<testbench>_tb.wcfg" may be missing for new testbenches, which isim will
+complain about. After you set up your waveform configuration in isim for the
+first time, be sure to save and rename the configuration appropriately.
 
-In isim, you can open the "signals.wcfg" in the file menu to reload a the logic
-analyzer configuration. This cfg file will not be valid if you delete any
-signals from your design that are saves in the wcfg.
+After editing any HDL files (either the testbench itself or files in ./hdl/),
+instead of restarting isim you can simply run the following command and then
+hit the "Reload" button in the isim GUI:
 
-./testbench/tb.v  is the toplevel testbench file for simulation.
+    make resim/<testbench>_tb
 
-Please improve and push!
+Some testbenches may be written in a particular style and can be run as
+automated tests. To run a particular test, or to run all unit tests:
 
-== HOWTO Coregen =============================================================
+    make test/<testname>_tb
+    make tests
 
-Run `make coregen` and use the GUI to generate a core.
+== Development ===============================================================
 
-Depending on the output, copy .v files to hdl/ and/or .xco files to cores/.
-update the Makefile.
+This project uses a template HDL build system. You can read more about
+developing with this system in the HOWTO and README files in the ./contrib/
+directory. In particular, there are directions on:
 
-For any .xco files, strip the "Project Options" section and the final CRC line.
+ - using Xilinx Coregen to instantiate HDL cores
+ - creating unittest-style testbenches
 
-After making any changes to the target chipset (eg, by modifying Makefile),
-you'll need to do a 'make clean' to ensure that the coregen logic is
-resynthesized correctly.