diff options
| -rw-r--r-- | README | 102 | ||||
| -rw-r--r-- | contrib/HOWTO.coregen | 13 | ||||
| -rw-r--r-- | contrib/HOWTO.testbench (renamed from contrib/README.tb_test) | 0 | ||||
| -rw-r--r-- | contrib/QUICK_START.txt | 57 |
4 files changed, 129 insertions, 43 deletions
@@ -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'." |