------------------------------------------------------------------------------
-- Title            : vhdl4dcd                                              --
-- Description      : A set of complete test designs in VHDL.               --
-- Author           : Nikolaos Kavvadias <nkavv@uop.gr>                     --
-- Author's URL     : http://www.nkavvadias.co.cc                           --
-- Release Date     : 11 December 2010                                      --
-- Version          : 0.0.1                                                 --
--------------------:---------------------------------------------------------
-- Revision history :                                                       --
--           v0.0.1 : 2010-12-11                                            --
--                  : Initial release.                                      --
------------------------------------------------------------------------------

1. INTRODUCTION
---------------

"vhdl4dcd" is a collection of sample designs along with their complete
testbenches, all written in VHDL. The sample designs include the following:
  - alu       : Arithmetic-Logic Unit
  - bcdcounter: Binary counter with BCD-encoded output (to a display)
  - dreg      : D-type register with synchronous reset and enable
  - fsm1p     : FSM written in the single-process style
  - fsm3p     : FSM written in the three-process style
  - gcd       : FSMD design for computing the Greatest Common Divisor of two
                integers
  - priority  : A priority encoder
  - ram_async : RAM (random access memory) with asynchronous read
  - ram_sync  : RAM with synchronous read
  - rca       : Parameterized ripple-carry adder
  - rom_async : Asynchronous read ROM (read-only memory)
  - rom_sync  : Synchronous read ROM


2. FILE LISTING
---------------

  The "vhdl4dcd" distribution includes the following files:

  /vhdl
    README                This file.
    clearall.sh           Bash shell script that clears all generated files
    testall.sh            Bash shell script for running all simulations
    /<design>
      <design>.mk         UNIX makefile for running the GHDL simulator
      <design>.sh         Bash shell script for running a complete simulation
      <design>.vhd        The digital circuit design in VHDL
      <design>_tb.vhd     A testbench for testing <design>.vhd


3. USAGE
--------

  There two alternative paths in using GHDL. Either follow steps 1-5 (for 
  cygwin) or follow 1-2,6 (no cygwin needed). The cygwin path is suggested, 
  though.

  1. First, install GHDL for Windows. Go to http://ghdl.free.fr, download ghdl 
  (from url: http://ghdl.free.fr/site/uploads/Main/ghdl-win-installer-latest.exe) 
  and install it in your local machine.
  In case you want to use GHDL under Linux downloading this installer:
  http://ghdl.free.fr/site/uploads/Main/ghdl-i686-linux-latest.tar.
  Then, follow steps 2-5 since using GHDL under cygwin and Linux is essentially 
  the same.

  2. Remember to install both GHDL and the included GTKwave (you will be
  prompted to). You can install GHDL, e.g. to C:\GHDL (don't use a path name
  with spaces).

  3. Install cygwin. Download setup.exe from http://sources.redhat.com/cygwin/.
  Then run setup.exe and follow instructions. Remember to check for "gcc" and
  "make" to be included in the web download (and installation).

  4. Run a single test. Assuming that you have unzipped "vhdl.zip" to C:\ the 
  design subdirectories will be placed under C:\vhdl. Open a Cygwin command 
  prompt and do the following:
  $ cd /cygdrive/c/vhdl
  $ cd alu
  $ ./alu.sh
  This has ran the simulation. To view the generated waveform data use:
  $ gtkwave alu.vcd
  In case that your design uses an FSM ("fsm1p", "fsm3p" and "gcd" do) run
  gtkwave in this way (e.g. for the case of "fsm1p"):
  $ gtkwave fsm1p.ghw
  For the FSM-based designs, instead of VCD waveform files, GHDL waveforms
  are generated (.ghw extension). The VCD format is limited and you cannot
  visualize enumerated variables/signals such as the state variable(s) that
  FSM typically use.

  5. Run a test for everything.
  $ cd /cygdrive/c/vhdl
  $ ./testall.sh
  In order to clean-up the automatically-generated files and subdirectories
  do the following:
  $ ./clearall.sh

  6. ALTERNATIVE way to run a GHDL simulation (e.g. for "alu") WITHOUT cygwin.
  In this case you will run the following commands from the windows command
  prompt.
  $ cd /cygdrive/c/vhdl
  $ cd alu
  $ del *.vcd *.ghw *.log
  $ rmdir work
  $ mkdir work
  $ ghdl.exe -a --ieee=synopsys -fexplicit --workdir=work alu.vhd
  $ ghdl.exe -a --ieee=synopsys -fexplicit --workdir=work alu_tb.vhd
  $ ghdl.exe --elab-run --ieee=synopsys -fexplicit --workdir=work alu_tb --vcd=alu.vcd --stop-time=1000ns
  $ gtkwave.exe --elab-run --ieee=synopsys -fexplicit --workdir=work alu_tb --vcd=alu.vcd --stop-time=1000ns


4. PREREQUISITIES
-----------------

- Cygwin

- Standard UNIX-based tools
  make, gcc, bash

- ghdl and gtkwave

5. CONTACT
----------

You may contact me at:

  Nikolaos Kavvadias <nkavv@uop.gr>
                     <nikolaos.kavvadias@gmail.com>
  http://www.nkavvadias.co.cc
