LegUp Quick Start Guide

Last Author
bains
Last Updated
1015 Days Ago
Subscribers
None

LegUp Quick Start

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.

1. Recommended Reading

Background

LegUp: what it is, what it does, why it is important.

Getting Started
NOTE: the LegUp documentation may be more up-to-date in the legup/docs directory of the LegUp git repo.

2. Getting and Building LegUp and Required Tools

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
NOTE: You may also want to install the full version of ModelSim

There are several resources to help you set this up:

3. Using LegUp

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/*/*

4. LegUp Development

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

git push Rules

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
git pull Suggestions

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.

Mailing Lists

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.

Directories

There are several important directories you should know about:

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
git

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.

Personal git Branch

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.

Testing

Try to write short unit tests to test parts of your code that may not be tested by the LegUp benchmarks.

Quantifying results

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.

Gathering Experimental Data

Avoid using buildbot for generating experimental data.
If you need to run a lot of test cases, use SciNet. scinet.

Coding Standards

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

5. Notes

  • 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