LegUp Quick Start Guide
- LegUp Quick Start
- 1. Recommended Reading
- 2. Getting and Building LegUp and Required Tools
- 3. Using LegUp
- 4. LegUp Development
- 5. Notes
This page is meant to be a quick guide for new members of the LegUp team. Hopefully it will help you get started with LegUp.
LegUp: what it is, what it does, why it is important.
- Read a paper on LegUp: http://legup.eecg.utoronto.ca/fpga60-legup.pdf
- All LegUp publications: http://legup.eecg.utoronto.ca/publications.php
- LegUp website: http://legup.eecg.utoronto.ca/
- Read the LegUp Documentation http://legup.eecg.utoronto.ca/docs/3.0/index.html
The quickest and easiest way to get a copy of LegUp is by downloading the latest VirtualBox image: http://legup.eecg.utoronto.ca/download.php
However, ideally you will want to work with LegUp directly on your computer.
The following steps outline this process for Ubuntu 14.04 x64:
- Install the current LTS release of Ubuntu 64-bit (14.04 at the time of writing)
- Install packages required by LegUp using the package manager (apt-get)
- git tcl8.5-dev dejagnu expect texinfo build-essential liblpsolve55-dev libgmp3-dev automake libtool clang-3.5 libmysqlclient-dev qemu-system-arm qemu-system-mips gcc-4.8-plugin-dev libc6-dev-i386 libqt4-dev
- optional: vim gitk meld kdiff3 libgraphviz-dev
- Install gxemul. Download version 0.4.7.2-1 here http://packages.ubuntu.com/lucid/gxemul or here http://archive.ubuntu.com/ubuntu/pool/universe/g/gxemul/
- Install Quartus (version 11.1sp2 recommended at this time) and ModelSim
- Follow instructions for Installing ModelSim and Quartus II 11.1 on Ubuntu 14.04 64-bit here: LegUp Wiki - Computer Setup - Quartus
- Setup git commit access and clone the LegUp git repository computer_setup#commit-access
- Build LegUp by typing 'make' in head directory
There are several resources to help you set this up:
- Computer Setup Wiki Page: computer_setup
- LegUp Documentation - Installation: http://legup.eecg.utoronto.ca/docs/3.0/gettingstarted.html#installation
- git push access: computer_setup#commit-access
- Quartus: computer_setup#quartus
- ModelSim (full version): computer_setup#modelsim
Run through the LegUp tutorials: http://legup.eecg.utoronto.ca/tutorials.php
Read the LegUp Documentation - User Guide: http://legup.eecg.utoronto.ca/docs/3.0/userguide.html#userguide
The LegUp Documentation - User Guide introduces several important make targets.
These make targets are mostly defined in legup/examples/Makefile.common.
You should be familiar with most of the following targets:
- make v
- make hybrid
- make tiger
- make emul
- make sim_proc
- make parallel
- make w
- make f
The legup/examples directory contains many different benchmarks.
You may want to play around with compiling and simulating some of them using these make targets.
- Pure HW benchmarks:
- Hybrid Benchmarks:
- Parallel Benchmarks:
Read the LegUp Documentation - Programmer's Manual: http://legup.eecg.utoronto.ca/docs/3.0/programmermanual.html#progman
Familiarize yourself with the LegUp buildbot: http://www.legup.org:9100/waterfall
The following apply when doing a 'git push' to the LegUp master branch:
- Avoid pushing when buildbot is failing
- Check buildbot after you push to make sure all tests still pass
- Only push once you've made sure your changes haven't broken anything:
- run 'runtest_checkin' from the legup/examples directory and make sure everything passes
After doing a 'git pull' it is a good idea to run 'make' from the legup root directory.
This ensures that any changes to the LegUp source (in legup/llvm/lib/Target/Verilog, legup/llvm/lib/Transforms/LegUp/ etc) will be incorporated into the LLVM binaries when you run tests, benchmarks etc.
Subscribe to the legup-builds mailing list: http://lists.legup.org/listinfo/. You may also want to subscribe to the legup-dev and legup-commits lists.
There are several important directories you should know about:
- legup/llvm -> see: http://legup.eecg.utoronto.ca/docs/3.0/programmermanual.html#source-files
There are a few git commands you should be familiar with:
- git push
- git pull
- git commit
- git log
- git status
- git status -uno (do not show untracked files)
- git checkout
- git branch
- git merge
- git mergetool (for resolving merge conflicts)
- gitk (or gitg)
You may also want to install and familiarize yourself with a merge tool such as meld, opendiff, emerge, or vimdiff.
This will help you handle git merge conflicts.
If you often work on multiple computers (home/work/school) you may want to set up your own branch for anything that is a work-in-progress.
When it is 'finished' and passes all the test cases, then you can merge it into the master branch and push it to the remote.
This way you can conveniently synchronize your working directory with git, while not breaking the master branch for other members of the team.
In addition, you have a backup copy of your work in the remote repository in the case of local computer failure.
Try to write short unit tests to test parts of your code that may not be tested by the LegUp benchmarks.
You can run the legup/examples/benchmark.pl script to collect the cycles, fmax, LUTs, etc. for chstone and dhrystone.
This takes a while, but is a good way to quantify the effect of your changes.
Avoid using buildbot for generating experimental data.
If you need to run a lot of test cases, use SciNet. scinet.
I'm not sure if LegUp has any coding standards, or if we want to have any.
Basically just try to write clean code and use comments...
For reference the LLVM coding standards are here: http://llvm.org/docs/CodingStandards.html
- If you see something in the legup code that looks wrong, it probably is. Either fix it, bring it up in the group meeting, or ask someone about it.
- The current HEAD of the LegUp git repository may contain a more up-to-date version of the LegUp Documentation in the legup/docs directory.
- Feel free to update/improve this wiki document or any LegUp wiki document. Also feel free to update the LegUp documentation in legup/docs