Quick-Start Guide

Compiler setup
==============

Before using the compiler, you need to compile the compiler itself:

1.  Install the software necessary to build the compiler.  (This
    includes a Linux- or UNIX-like environment; you can use Cygwin on
    Windows.  It also requires an installation of OCaml.)

2.  Change to the main compiler directory (the directory containing
    README and Makefile).

3.  Use the `make` command to build the compiler:

        make


Using the interpreter
=====================

You can use the interpreter to run Verity progams directly, without
compiling them.

1.  Find a Verity program you want to interpret it (either write one,
    or look in the "examples" directory for some examples).  It need
    not be in the main compiler directory.

2.  The interpreter does not yet support libraries, so you must first
    remove or comment out any library calls (e.g. "print" statements)
    in the file you want to interpret (and alter the progam to return
    a value, if you want output out of it).

3.  Change to the main compiler directory.

4.  Use the `./gosi` command, giving it the path to the file you want
    to interpret as an argument:

        ./gosi examples/your_modified_file.ia

5.  The interpreter will output the final result of the program.


Compiling to hardware descriptions
==================================

The main purpose of the gosc compiler is to produce hardware
descriptions, that can be simulated, or (using other tools)
automatically synthesized into appropriate hardware.


Compiling for simulation
------------------------

1.  Find a Verity program you want to compile (either writing one, or
    using one of the provided examples in the examples/ directory).

2.  Change to the main compiler directory.

3.  Use the `./gosc` command to compile the program into VHDL:

    *   Use the `-m sim` switch to specify compiling for simulation.

    *   Use the `-o` switch to specify the filename of the generated
        linking file.

    *   If using GHDL as your simulator, use the `-l ghdl-fix` option
        to work around a bug in GHDL.  (You don't need this option
        with other simulators.)

    *   You might also want to use the `-v` option for the compiler to
        tell you what it is doing.

    A sample compilation command would look like this:

        ./gosc -m sim -l ghdl-fix -o /tmp/t.vhd examples/fibonacci-memoized.ia

    The compiler will compile the file given if it's never been
    compiled or is out of date, and any dependencies of it that are
    out of date, and list the resulting list of files that need to be
    used as input to your simulator:

        Use the following files as input to your simulation/synthesis tool:
        ./lib/constants.vhd
        tests/fibonacci-memoized.vhd
        ./include/ghdl-fix.vhd
        ./lib/sim/print.vhd
        /tmp/t.vhd
        ./lib/sim/toplevel.vhd

    Note that with many simulators, the order is significant.

4.  Give the resulting files as input to your simulator.  (Your
    simulator will also need to know the name of the top-level entity;
    for `-m sim`, unless your code imports platform-specific
    libraries that have their own simulation top-level entities, it
    will be called `work.simulation_toplevel`.)

    To do this in GHDL:

    1.  Analyze the files, by passing them to `ghdl -a` in the order
        listed.  You will also need to link in the IEEE libraries, for
        instance with the option `--ieee=synopsys`:

            ghdl -a --ieee=synopsys lib/constants.vhd tests/fibonacci-memoized.vhd include/ghdl-fix.vhd lib/sim/print.vhd a.vhd lib/sim/toplevel.vhd

    2.  Elaborate the files, by using `ghdl -e` and the name of the
        top-level entity, `simulation_toplevel`:

            ghdl -e --ieee=synopsys simulation_toplevel

    3.  Run the resulting simulation:
    
            ./simulation_toplevel
            
    To do this in ModelSim:
    
    1.  Open ModelSim.
    
    2.  Create a new project, and add the files listed by the compiler
        to it, in the order given.  (ModelSim cares about the order;
        if the files are added in the wrong order, you can change it
        via the "Compilation" right-click option on the list of
        files.)
    
    3.  Choose the `Compile All` option from the right-click menu on
        the file list.  (ModelSim might not seem to react to this
        immediately; look at the progress bar at the bottom of the
        screen to see its progress.)
        
    4.  Start the simulation (via the menu), choosing
        `work.simulation_toplevel` as the top-level entity.
        
    5.  Run the simulation.  (If your program terminates, it should
        work fine with no time limit.)
    
    The simulation will run.  If you imported the `<print>` library,
    then print statements in your code will produce output in the
    simulator's output window (standard output for GHDL, at the pane
    at the bottom of the screen for ModelSim).  Note that you might
    get warnings during the first 10 nanoseconds of simulated time;
    this is because the code is simulating a reset.  Additionally,
    code that uses the `<print>` library will halt the simulation when
    the code exits via asserting a failure (so if you see a "failure"
    message, it means your program terminated).

    
Compiling for synthesis, on an already supported architecture
-------------------------------------------------------------

Synthesizing a Verity program into hardware requires the use of
appropriate libraries in the hardware for communicating with the
hardware, and an appropriate synthesis tool.  So far, `gosc` has been
tested only in conjunction with the Quartus II tool by Altera,
although the process should be similar with other manufacturers.

This example uses the DE2-115 Development and Education board by
terasIC and Altera, for which drivers for some of the functionality
are provided in the `lib` and `include` directories.

1.  Find a Verity program you want to compile (either writing one, or
    using one of the provided examples in the examples/ directory).
    There may be translations of standard libraries for your platform
    (e.g. `<print>` exists for the DE2-115, and outputs the number
    given in hexadecimal on its seven-segment displays); but you will
    need to use a platform-specific library (e.g. `<de2>`) to take
    full advantage of the hardware.

2.  Create a new directory to use for the Quartus project.

3.  Change to the main compiler directory.

4.  Use the `./gosc` command to compile the program into VHDL:

    *   Use the `-m` switch to specify the architecture you are
        targeting (e.g. `-m de2`).

    *   Use the `-o` switch to specify the filename of the generated
        linking file.  (You probably want to put it in your new
        directory, but we'll use `tmp/t.vhd` in this example.)

    *   You might also want to use the `-v` option for the compiler to
        tell you what it is doing.

    A sample compilation command would look like this:

        ./gosc -m de2 -o /tmp/t.vhd examples/fibonacci-memoized.ia

    The compiler will compile the file given if it's never been
    compiled or is out of date, and any dependencies of it that are
    out of date, and list the resulting list of files that need to be
    used as input to your synthesis tool:

        Use the following files as input to your simulation/synthesis tool:
        ./lib/constants.vhd
        example/fib.vhd
        ./include/de2/print.vhd
        ./include/de2.vhd
        /tmp/t.vhd
        ./lib/de2/toplevel.v

    With some synthesis tools, the order is significant, but Quartus II
    is capable of inferring it.

5.  Start the DE2 System Builder tool (that generates Quartus II
    projects for use with the DE2-115 board.)
    
6.  For the libraries provided with the compiler, use the following
    configuration: disable all the checkbox options apart from Clock,
    Button x 4, 7-Segment x 8, Switch x 18, and leave all the other
    options at their defaults.

7.  Use the "generate" button, and place the generated project file in
    your new directory.  (You can close the system builder tool at
    this point.)

8.  Open your generated project file in Quartus II (by double-clicking
    on it, while Quartus II is closed, not from within Quartus II).

9.  Add the files mentioned by `gosc` above to your project.

10. In order for the entities in the files you just added to show up
    within Quartus II, run "Partition Merge" from the list in the
    sidebar.  (You're likely to get many warnings, because Quartus
    will be trying to compile the wrong top-level entity, but this is
    necessary before the top-level entity can be set.)

11. Set the top-level entity to `DE2_button_switch_7seg` (the
    top-level entity setting in Quartus is a little hard to find;
    right-click the device in the "hierarchy" tab, choose
    "settings...", then select general, then select the "..." next to
    the "Top-level entity" checkbox, and choose the entity from the
    resulting list).

12. Run "Fitter (Place and Route)" from the list in the sidebar.

13. Run "Assembler" from the list in the sidebar.

14. Connect the DE2-115 board to your computer (use a USB cable
    between your computer's USB port and the board's "BLASTER" port).

15. Run "Program Device" from the list in the sidebar.

16. Click the "Start" button in the programmer.

This should program the board with your program. To use it, press KEY3
on the board (which is mapped to the reset input); the program will
start running as soon as you release it.

ċ
quickstart.txt
(9k)
Dan Ghica,
8 Mar 2012, 01:47
Comments