Part 3 of refactoring template files into ./contrib

Docs!

4 files changed, 129 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.
diff --git a/contrib/HOWTO.coregen b/contrib/HOWTO.coregen
new file mode 100644
index 0000000..d679d23
--- /dev/null
+++ b/contrib/HOWTO.coregen
@@ -0,0 +1,13 @@
+
+== HOWTO Coregen =============================================================
+
+Run `make coregen` and use the GUI to generate a core.
+
+Depending on the output, copy .v files to hdl/ and/or .xco files to cores/.
+update the Makefile.
+
+For any .xco files, strip the "Project Options" section and the final CRC line.
+
+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.
diff --git a/contrib/README.tb_test b/contrib/HOWTO.testbench
index 3be00d6..3be00d6 100644
--- a/contrib/README.tb_test
+++ b/contrib/HOWTO.testbench
diff --git a/contrib/QUICK_START.txt b/contrib/QUICK_START.txt
new file mode 100644
index 0000000..852f11c
--- /dev/null
+++ b/contrib/QUICK_START.txt
@@ -0,0 +1,57 @@
+#!/usr/bin/env sh
+
+# Note: you can either follow the directions in this file, or just run it like:
+#
+#   sh ./contrib/QUICK_START.txt
+#
+# Make sure we are where we think we are; eg don't run this from the ./contrib
+# folder. Also, fail hard.
+set -e
+test -f ./contrib/QUICK_START.txt
+
+###############################################################################
+############## The Verilog Build Project Template Quick Start! ################
+###############################################################################
+
+# Move Makefile.example to Makefile and edit it. At least set a project name
+# and chose a board.
+# If you are using a board for which there does not (yet) exist a template in
+# ./contrib, you'll need to create a ./<boardname>.ucf file, and possibly also
+# ./<boardname>.opt and ./<boardname>.bitconf files as well.
+
+  git mv Makefile.example Makefile
+  $EDITOR Makefile
+
+# Edit the README file with project-specific info; include a snazzy title by
+# default if possible.
+
+  if [ -x /usr/bin/figlet ]; then
+      echo "Enter the project title (up to ~32 char), then press enter, then Ctrl-D"
+      figlet > README.new && cat README >> README.new && mv README.new README
+  fi
+  $EDITOR README
+
+# Edit the COPYING file with license information
+
+  $EDITOR COPYING
+
+# Change the 'origin' git remote to point to a new remote repository. Don't
+# accidentially push to the 'verilog-build' template repo!
+
+  $EDITOR .git/config
+
+# Add any hdl files to git
+
+  git add hdl/*.v hdl/*.vhd tb/*.v 2> /dev/null || true
+
+# Add any project-specific files to git (if there are any)
+
+  git add *.opt *.bmm *.ucf 2> /dev/null || true
+
+# Commit all that!
+
+  git commit -e -m "Starting new project using verilog-build template"
+
+echo "Alright, good to go."
+echo
+echo "NOTE: If you didn't get a chance to add any files you wanted in the initial commit, you can still add them now (with 'git add') and then update the most recent commit with 'git commit --amend'."