Main CS97 Page
 
Top

Setting up git, ssh, etc

We are going to be using git for handing in all materials in CS97. You will have two repositories: one for yourself (named cs97fa13_${USER}) and one for your project team (named cs97fa13_teamXX). I am going to shamelessly lean on the instructions that Andy Danner wrote for graphics (CS40). The links are below. Here are the few modifications for CS97.

  • We will not be using the handin scripts. Ignore all references to them.
  • Please give me a copy of your public key with the following command:
    cp id_rsa.pub ~bylvisa1/Public/Keys/${USER}.pub
    chmod a+r ~bylvisa1/Public/Keys/${USER}.pub
    If you have taken another class that used the CS department's gitolite server, you maybe/probably don't have to do this.

http://svn.cs.swarthmore.edu/cs40/wiki/gitRepo

http://svn.cs.swarthmore.edu/cs40/wiki/Labs01

If everything is set up properly, you should be able to run the following clone command to get a copy of your repo.

git clone gituser@git.cs.swarthmore.edu:cs97fa13_${USER}

Please report any snags you hit on Piazza. The instructions will be amended here.

Pintool Tutorial

Pin is a dynamic instrumentation framework maintained by Intel. Here is its home on the web. Pin is one of two frameworks (valgrind is the other one) that are recommended platforms for your CS97 project. In this lab you will gain familiarity with the process of writing analyses with Pin and begin to learn about the kind of information and control that Pin affords.

Tasks

1. Read Some Documentation

Read at least the first two sections of the Pin manual ("Introduction" and "How to Instrument with Pin"). You will probably have lots of questions about terminology and how Pin works. Please post these questions on Piazza.

2. Get a Couple of Example Pintools Working

Pin is installed on the CS network in the directory /usr/local/pin. (Actually, that's a symlink to a particular pin version, but close enough.) The makefiles that come with Pin are designed to work best when you work within the directory tree where Pin is installed. This is a little inconvenient with the shared Pin install on the CS network, so we will need to work around that.

(You are welcome to install Pin on your own computers(s) and work from there. It is a very easy installation procedure. It is possible to install Pin in your CS home directory, but we ask that you not do that. The Pin installation directory is fairly large (~160M), so it would be an unnecessary drain on network storage resources if everyone in the class installed their own copy.)

2a. PIN_ROOT

To let Pin's makefiles know where Pin is installed, set the PIN_ROOT environment variable with a command like:

export PIN_ROOT=/usr/local/pin

It is probably a good idea to put this command in a startup script like .bash_profile, so that you don't need to set the variable every time you log in.

2b. Make a new directory for this lab

mkdir pin_is_fun
cd pin_is_fun

2c. Make a skeleton makefile

Create a file in your lab directory called makefile with the following contents. This will grab all the standard Pin make magic.

CONFIG_ROOT := $(PIN_ROOT)/source/tools/Config
include $(CONFIG_ROOT)/makefile.config
include $(PIN_ROOT)/source/tools/SimpleExamples/makefile.rules
include $(TOOLS_ROOT)/Config/makefile.default.rules

2d. Copy the source file for an example pintool

cp /usr/local/pin/source/tools/SimpleExamples/opcodemix.cpp .

2e. Build the pintool

make -e obj-intel64/opcodemix.so

There are a few unusual pieces of this make invocation that deserve a word of explanation:

  • The "-e" flag tells make that environment variables should override definitions of variables of the same name within makefiles. Some of Pin's makefile magic redefines PIN_ROOT, which is annoying and dumb, but whatever.
  • obj-intel64 is the directory where your compiled pintool will go.
  • The .so suffix indicates that your pintool is not an independent executable. Rather, it's an object that will be linked in to Pin itself to form a complete analysis.

2e. Run the pintool

$PIN_ROOT/pin -t obj-intel64/opcodemix.so -- ls

Everything that appears after "--" is the actual command that will be executed. This can be an arbitrary shell command. The "-t obj-intel64/opcodemix.so" part tells Pin which pintool to use.

Take a look at the output in opcodemix.out

2f. Again, Again

Choose another pintool from the collection that comes with Pin. Build it and run it on a few commands.

3. Tweak an Existing Pintool to do Something Fun

Now that you have the basic mechanics of Pin down, take a few minutes to browse through the Pin API Reference. Use your newly acquired knowledge of Pin's capabilities to add a little twist to one of the simple examples you ran. Don't stress about coming up with something particularly interesting, I just want you to start getting familiar with how the Pin API works.

4. Grading

Show the instructor that you've done the tasks. You win!