From 0d34adceb3665ad6d96cb4f2e8bd0ad55d712195 Mon Sep 17 00:00:00 2001 From: bryan newbold Date: Tue, 12 Nov 2013 18:16:19 -0500 Subject: Part 3 of refactoring template files into ./contrib Docs! --- README | 102 ++++++++++++++++++++++++++++-------------------- contrib/HOWTO.coregen | 13 ++++++ contrib/HOWTO.testbench | 12 ++++++ contrib/QUICK_START.txt | 57 +++++++++++++++++++++++++++ contrib/README.tb_test | 12 ------ 5 files changed, 141 insertions(+), 55 deletions(-) create mode 100644 contrib/HOWTO.coregen create mode 100644 contrib/HOWTO.testbench create mode 100644 contrib/QUICK_START.txt delete mode 100644 contrib/README.tb_test 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 "" + +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + +== About ===================================================================== + + + +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/. + 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//.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_.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/_tb with the isim GUI: -View the results using the isim GUI with: + make isim/_tb - make isim +A "tb/_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/_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/_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/HOWTO.testbench b/contrib/HOWTO.testbench new file mode 100644 index 0000000..3be00d6 --- /dev/null +++ b/contrib/HOWTO.testbench @@ -0,0 +1,12 @@ + +"testbenches" are helpful wrappers which exersize a piece of code. they should +live in ./tb/, end in "_tb.v" or "_tb.vhd", and have a signal file (ending in +"_tb.wcfg") associated with the same name. update the 'tbfiles' list in +Makefile. invoke the isim GUI with "make isim/name_tb" (for tb/name_tb.v). if +you make a source code change and don't want to reload the whole GUI, you can +do "make resim/name_tb" and then click the "Re-load" button. + +testbenches which can act as headless unit tests (reporting pass/fail by +printing to stdout) should be added to the 'alltests' list in Makefile. run the +test with 'make test/name_tb'; run all tests with 'make tests'. + 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 ./.ucf file, and possibly also +# ./.opt and ./.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'." diff --git a/contrib/README.tb_test b/contrib/README.tb_test deleted file mode 100644 index 3be00d6..0000000 --- a/contrib/README.tb_test +++ /dev/null @@ -1,12 +0,0 @@ - -"testbenches" are helpful wrappers which exersize a piece of code. they should -live in ./tb/, end in "_tb.v" or "_tb.vhd", and have a signal file (ending in -"_tb.wcfg") associated with the same name. update the 'tbfiles' list in -Makefile. invoke the isim GUI with "make isim/name_tb" (for tb/name_tb.v). if -you make a source code change and don't want to reload the whole GUI, you can -do "make resim/name_tb" and then click the "Re-load" button. - -testbenches which can act as headless unit tests (reporting pass/fail by -printing to stdout) should be added to the 'alltests' list in Makefile. run the -test with 'make test/name_tb'; run all tests with 'make tests'. - -- cgit v1.2.3