aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorbryan newbold <bnewbold@leaflabs.com>2013-11-12 18:16:19 -0500
committerbryan newbold <bnewbold@leaflabs.com>2013-11-12 18:16:19 -0500
commit0d34adceb3665ad6d96cb4f2e8bd0ad55d712195 (patch)
tree86cc1f3b3a1160f6b0d93f759dee7a99f0868e82
parent75fc9c1613ffbeea2be843c3aa0e5fcd978ad60b (diff)
downloadbasic-hdl-template-0d34adceb3665ad6d96cb4f2e8bd0ad55d712195.tar.gz
basic-hdl-template-0d34adceb3665ad6d96cb4f2e8bd0ad55d712195.zip
Part 3 of refactoring template files into ./contrib
Docs!
-rw-r--r--README102
-rw-r--r--contrib/HOWTO.coregen13
-rw-r--r--contrib/HOWTO.testbench (renamed from contrib/README.tb_test)0
-rw-r--r--contrib/QUICK_START.txt57
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'."