Legup Wiki

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 *Note: the LegUp documentation may be more up-to-date in the legup/docs directory of the LegUp git repo.

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:

1. Install the current LTS release of Ubuntu 64-bit (14.04 at the time of writing)
2. Install packages required by LegUp using the package manager (apt-get)

sudo apt-get install 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 meld \
libqt4-dev libgraphviz-dev libfreetype6-dev buildbot-slave libXi6:i386 \
libpng12-dev:i386 libfreetype6-dev:i386 libfontconfig1:i386 libxft2:i386 \
libncurses5:i386 libsm6:i386 libxtst6:i386 vim gitk kdiff3 gxemul clang-3.5 \
openssh-server mysql-server python3-mysql.connector python3-serial \
python3-pyqt5

• 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

1. 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/
2. 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
• Note: You may also want to install the full version of ModelSim

1. Setup git commit access and clone the LegUp git repository http://legup.eecg.utoronto.ca/wiki/doku.php?id=computer_setup#commit_access
2. Build LegUp by typing 'make' in head directory

There are several resources to help you set this up:

• Computer Setup Wiki Page: http://legup.eecg.utoronto.ca/wiki/doku.php?id=computer_setup
• LegUp Documentation - Installation: http://legup.eecg.utoronto.ca/docs/3.0/gettingstarted.html#installation
• git push access: http://legup.eecg.utoronto.ca/wiki/doku.php?id=computer_setup#commit_access
• Quartus: http://legup.eecg.utoronto.ca/wiki/doku.php?id=computer_setup#quartus
• ModelSim (full version): http://legup.eecg.utoronto.ca/wiki/doku.php?id=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
• 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:
  • chstone/*
  • dhrystone
  • array
  • matrixmultiply
  • pipeline/*
  • …
• Hybrid Benchmarks:
  • chstone_hybrid/*
  • …
• Parallel Benchmarks:
  • parallel/*/*

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
  • NOTE: If possible, try not to modify LLVM files outside of legup/llvm/lib/Target/Verilog and legup/llvm/lib/Transforms/LegUp.
• legup/examples → benchmark files, etc.
• legup/boards → board- and device-specific configurations, pin assignments, etc
• legup/swtools → binutils, linker scripts, startup files, and libraries for ARM processor
• legup/tiger → same as above, but for tiger MIPS

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