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. |