ECEN 676 Advanced Computer ArchitectureLab 0: Getting Familiar with Pin

Assigned: January 22, 2021

Due on: Thursday January 28th by 11:59pm

1 Summary

This term in ECEN 676 we will be using Pin, a binary instrumentation toolprovided by Intel. The purpose of this lab is to familiarize you with compilingand running Pin tools, as well as to make sure that you are able to use theclass infrastructure and computers. To test the infrastructure, you will buildand run a small Pin tool. In order to develop architectures that run programsquickly architects must thoroughly understand the properties of representativeprograms. Architects experiment with different programs to help them makedesign decisions about features that will be included in processors. There area few approaches that can be used to evaluate the behavior a program. One issimulation. In this case, a software model of a processor is built, and the pro-gram executed on the model. Simulators have the advantage of being arbitrarilydetail – in theory one could build a SPICE processor simulator. Typically, ar-chitectural simulators give cycle-accurate timing estimates. The penalty forthis level of detail is simulation speed: the more detailed a software simula-tor is, the slower it can execute programs; advanced software simulators cansimulate at rates of tens of KIPS (kilo instructions per second). A second op-tion is code instrumentation. Code instrumentation collects information aboutprogram characteristics. In general, code instrumentation is less detailed thansimulation, but code instrumentation is faster to implement and enjoys fasterprogram execution. Thus code instrumentation which can be very useful inguiding architectural decisions early in the development process, before detailedsimulators are available. The simplest form of code instrumentation, terminaldisplay statements (e.g. printf), is used by almost every programmer, computerarchitect or otherwise. Clearly such manual instrumentation is time-consuming,both in terms of writing code and collecting execution results. A better choiceis to use a meta language to describe the code instrumentation and develop atool that will efficiently instrument the target program at compile or runtime.

Pin is a free (though not open), industrial grade binary instrumentationtool produced by Intel and used widely in industry and academia. Pin acceptsas inputs a compiled Pin tool and a generic binary executable. A Pin tool isa C++ program that makes a series of calls to an instrumentation API andprovides code for Pin to execute at instrumented locations. The executable

1

itself is just-in-time compiled by Pin and the instruments are inserted. Thecode is then executed natively on the host machine. A major advantage of Pinis that it can instrument programs without requiring recompilation. Thus, evenlegacy binaries can be analyzed. Since Pin executes large portions of the targetprogram natively, it can be very fast, however, this constrains the programsanalyzed to the host architecture, namely x86. Yet, Pin is surprisingly versatile:new instructions can be emulated by hijacking unused x86 opcodes.

If you would like, you may install Pin on your home machine. Pin can bedownloaded from: Pin download and run on any Linux, Mac or Windows ma-chine. Please note that Pin is under active development. Thus, it is frequentlyupdated. If you install your own version of Pin, take care to update it peri-odically. In this lab we’re using Intel Pin 3.17. As always, this lab is to becompleted individually. You are encouraged to discuss lab concepts with fellowclassmates.

1.1 Setting up:

Although you can develop Pin tools on your home machine, we suggest you usethe ECEN servers. In Section 2 we give instructions on how you can do this.Once you have decided which machine to use, download the TAR file we haveprovided through Canvas and extract it. If you’re on the command line, youcan do this by running the following command in the same directory where thedownload is located:

tar xfz labs.tar.gz

The compressed file will contain two things: the lab assignment directorylabhandouts/, and the base/ directory, which contains both the Intel Pin exe-cutable, and the benchmarks you will be using. In the labhandouts/lab0handout/directory, you should find a make file, some sample source code, and a test script.Type the following at the command prompt:

cd labhandouts/lab0handout

chmod a+x lab0test.pl

make all

You will notice that make inscount0 fails to compile due to a parse error.While your instructor is an expert in Verilog, his C is not so good. Fix his sillyparse error, and run make again. Now run the Perl script:

./lab0test.pl

The Perl script will invoke Pin using the inscount0.so Pin tool on multiplePARSEC and SPLASH2 binaries. Pin can also be invoked from the commandline in the following manner:

../../base/pin pin -t toolname -- target_executable

2

Executing the Perl script will produce a results directory and an outputs di-rectory. Results directory contains a set of files, each of which is named inthe following manner: ExecName Arg1 Arg2 ... .out As you might imagine,the naming scheme is based on the executable and arguments that are instru-mented and analyzed by Pin tool. Since the inscount0 Pin tool counts thenumber of instructions in the instrumented program, these output files will con-tain the number of instructions executed. If you are interested in the innerworkings of a real Pin tool, examine inscount0.cpp. We will cover this toolin detail in lecture. Although we will release a script that will test the lab Pintools, these scripts will not verify your Pin tools, and we will not release theexpected results of the test cases. Further, we reserve the right to run test casesnot included in the released test script. You are encouraged to compare yourresults with your lab mates.

1.2 Submitting your lab:

When you have completed the lab to your satisfaction, submit your inscount0.cppto Canvas by the submission deadline. No late submissions will be accepted!

1.3 Guides for the perplexed:

• Pin home page• Pin documentation

2 Connecting to the Olympus servers

Intel Pin is packaged into the TAR-ed lab we have on the website. You can runthis lab either on your personal Linux machine, or e.g. on the ECEN Olympusservers. Below we provide instructions to log into Olympus.

The hostname for the server is olympus.ece.tamu.edu. You can use differenttools initiate the SSH connection. If you do not have an ECEN account, askthe Unix system administrator in the ECEN department to create one.

2.1 MobaXterm (for Windows)

MobaXterm is an SSH connection tool on Windows platform. Download MobaX-term from https://mobaxterm.mobatek.net/

• Launch MobaXterm.

• Click on Session. Session settings window opens up.

• Click on SSH.

• Enter the following information:- Host name: olympus.ece.tamu.edu- Port: 22

• Click OK.

• Enter your NetID and password.

3

Figure 1: Host Name Setting

Figure 2: Terminal Window

4

2.2 Putty & Xming

Putty is an SSH connection tool on Windows platform. Xming helps putty toshow graphic window. You can download Putty from https://www.putty.org/and Xming from https://xming.en.softonic.com/

• Install Putty and Xming.

• Launch Xming. It will run in the background.

• Launch Putty.

• Enter the following information:- Host name: olympus.ece.tamu.edu- Port: 22

• Go to connection → SSH → X11

• Check the ‘Enable X11 Forwarding’ box.

• Click open then a terminal will show up.

• Enter your NetID and password

Figure 3: Putty Setting

5

Figure 4: Terminal Window

2.3 Layer 2 Tunneling Protocol (for MacBook Users)

• Open your ‘System Preferences’ and choose ‘Network’.

Figure 5: System Preference and Network

6

• In the list of network connections on the left, click ‘Add (+)’

Figure 6: Add Network

• Choose ‘VPN’ as the Interface and use ‘L2TP over IPSec’ as the VPNType. You can enter anything you’d like as the Service Name. Click‘Create’.

Figure 7: Add Network

7

• Enter the following information:- Server Address: connect.tamu.edu- Account Name: Your NetID

• Click Authentication Settings.

Figure 8: Server and Account

8

• For User Authentication, enter your NetID password as the Password.For Machine Authentication, enter ‘tamuvpn’ as the Shared Secret. Click‘OK’

• Click ‘Advanced’ and check the box for ‘Send all traffic over VPN connec-tion’. Click OK.

Figure 9: Password and Advanced Setting

• Click ‘Apply’, then ‘Connect’. In the future, you should only need to click‘Connect’ on this screen to start your VPN connection.

Figure 10: Advanced Setting

9

3 Copying files from/to the server

To upload Pin tool on the server or submit your files to Canvas, we need tocopy and paste the files between the Olympus server and your PC. Linux andMac users can use a simple security copy command, and Windows users canuse a FTP software such as MobaXterm. You also can use other FTP softwaresuch as Filezilla and WinSCP. To set up Pin Tool on the server, download theTAR file we have provided on the lab website and open a terminal in the samedirectory.

3.1 Mac and Linux users

scp <NetID>@olympus.ece.tamu.edu:<file directory> <PC directory>

3.2 Windows users

• Download and launch the MobaXterm.

• Click ‘Scp’ on the left side

• Select the file and click ‘Download’.

• When you want to upload a file, click ‘Upload’.

Figure 11: Copy Files Using MobaXterm

10