1

Replay Debugger with Eclipse

v 1.0.x

Oct/28, 2010

Contacts:

Rohit Girme: rgirme@asu.edu

Young Wn Song: ywsong@asu.edu

2

Index

I. Intended Audience

II. Installation

III. Setup

IV. Project Creation

V. For Local debugging

i. Build & Run for Record

ii. Build for Replay

VI. Debug or Run in Replay mode

VII. For Remote debugging

i. Build for Record

ii. Build for Replay

3

I. Intended Audience

This document is intended to provide the Replay Debugger user detailed instructions on how to set up and use Replay debugger Eclipse. It is assumed that the user already compiled the Replay Debugger library, GDB, and Eclipse. The user can also download the compiled binaries.

II. Installation

1. Download & unzip files from the website.

2. Eclipse Installation

a. Just copy unzipped eclipse folder to any location in your home directory.

3. Record/Replay header files and libraries.

a. Copy the header files (replay_wrapper.h and replay_wrapper_def.h) and libraries (librecord.a and libreplay.a) in a single folder (e.g. Replay) to any location in your home directory.

b. Create a folder called Log some place in your home directory. This is required for storing the record/replay log files.

4. Make sure you have Java 1.5 (JDK and JRE) installed. This tool requires this particular version. Check https://help.ubuntu.com/community/Java for installation instructions on Ubuntu.

5. For more information on Eclipse in general visit http://www.eclipse.org/

6. For more information on GDB in general visit http://www.gnu.org/software/gdb/

7. For remote debugging, i.e. when development machine and target machine are not the same, we use the Zylin Embedded CDT plugin for Eclipse.

8. It is pre installed in the Eclipse available on our website.

Note: This tool has been tested with and works perfectly with the following configuration : Ubuntu 9.04 & Java 1.5. Please follow the instructions in this manual for successful configuration.

III. Setup

1. Create two environment variables with the following names.

a. REPLAY_PATH : This points to the Log folder created in the above section.

b. REPLAY_INCLUDE : This points to the single folder created in the above section, which contains the header files and libraries.

c. Make sure you have the above environment variables for correct working of the tool.

2. For information on environment variables in Ubuntu visit https://help.ubuntu.com/community/EnvironmentVariables

3. In the Eclipse downloaded from the website, make sure to do the following configuration

a. Window -> Preferences -> Java -> Compiler -> Select Java 1.5.

4

b. Window -> Preferences -> Run/Debug -> Launching -> C/C++ Application\ Debug -> Standard Process Create Launcher.

c. After the above configurations, press Apply.

5

IV. Project Creation

1. After starting Eclipse, it asks for workspace. Select any location in your home directory.

2. Start by creating a new C Project. Go to File in the menu bar and select New.

3. Select RecordReplay as the Project Type and give it some name.

6

4. Select Next to make sure that Record and Replay are added/selected as configurations

along with Debug and Release.

5. Click Finish to create the project.

7

6. You can create a new Source File or Drag and drop it to the C project created in Eclipse. Add any header files for your project.

7. Now you have finished creating the project. We can now move on to building the project.

V. For Local debugging - The host and the target are in the same machine

i. Build & Run for Record

1. After adding all the files necessary, we need to build the project. Click on Build button with the hammer icon on it to make sure we have selected Record configuration. Build it by selecting Record.

8

2. You will understand that build is over when you see Finished building target in the Console

window. It is highlighted in the figure below.

3. Run the Record executable created for the project. This will start the recording as the

project runs.

4. Enter input values if any, as and when required in the Console. This is input to the program. You will understand the program has finished running when you see terminated in the Console as shown.

9

ii. Build for Replay

1. Now we need to select the Replay configuration.

a. Right click on the project which is in the window on the left side under the Project Explorer tab.

b. Go to Build Configurations -> Set Active -> Select Replay.

2. You can follow the above step or skip to next step.

3. Click on Build button with the hammer icon on it to make sure we have selected Replay configuration. Build it by selecting Replay.

10

4. Now you have finished Record and Replay stage. You can now start Debug/Run

VI. Debug or Run in Replay mode

1. Now we start Debug. Go to Run in menu bar -> Debug Configurations.

2. When the Debug Configurations window opens, go to the bottom part of the window.

Make sure you Standard Process Create Launcher selected.

3. After selecting OK in the previous step. Go to Build Configuration and select Use Replay.

11

4. Now click Search Project and select the executable with the Replay configuration. We have build two executables, one for Record and another for Replay. We need to use Replay executable for Debugging.

5. Select the appropriate GDB in the Main tab: GDB debugger text box. Use the Browse button to select the gdb executable.

6. (Optional ) In the debugger tab at the bottom of the main tab, select Verbose Console Mode for extra debugging features (Recommended). Then select Apply on the bottom right corner. This option enables you to see output in the Eclipse console as shown in the “Local Debugging with GDB” section in the UserManualGDB manual.

12

7. Then select Debug on the bottom right corner to start Debug. It will ask for Perspective

switch. Select Yes.

8. The Debug Perspective will be opened and program will stop at the first line of main

function.

9. In the Replay Commands menu option, there are 4 commands available.

13

10. Use Thread Information to display LCEvent – Thread table in the Console. If you set an

LCBreakpoint you can make sure it has been added in the last column of the aforementioned table.

a. Use Set Minima Mode to set the minima mode for a particular thread.

b. Use Set Maxima Mode to set the maxima mode for a particular thread.

c. Use Set LC Breakpoint to set LC Breakpoint at any LCEvent.

11. After the threads have been created, you can select which thread to run by selecting the thread from the Debug tab at the top.

12. To check where a particular thread has stopped its execution after it has started to run,

expand the thread in the Debug tab. After expanding you will see the stack frame for that thread. Select the top most line to see where the thread has stopped.

14

13. Use the Resume button at the top, to continue. Eclipse does not have an explicit continue button. Resume does that instead of continue.

14. You can use Thread Information to see the LCEvent – Thread table (This will work only if

you have Verbose Mode on). You can also use the Replay Graphs menu option.

15

a. Show Graph will show you the entire table in graph format.

16

b. Refresh Graph will show the same table. However everything in red signifies it has been executed while everything in black signifies it still has to be executed.

c. For any of the above two graphs, clicking on the event (red or black circle), will take

you to the line in the source file which caused that event.

VII. For Remote Debugging – the target machine is in the different place as the host

*Installation is the same for remote debugging as for local debugging.

i. Setup

1. Follow the same instruction as for local debugging.

2. The remote machine must have the same path name for the log path as the host machine.

3. You may use ssh to login to the remote target.

ii. Build & Run for Record

1. The build instructions are the same as for local debugging. Please refer to that section.

2. After build is complete, copy the Record executable from the host machine to the folder structure mentioned in Setup, on the target machine. You may use scp for the same.

3. On the target machine, run the executable from command line.

iii. Build & Run for Replay

17

1. The build instructions are the same as for local debugging. Please refer to that section.

2. After build is complete, copy the Replay executable from the host machine to the folder structure mentioned in Setup, on the target machine. You may use scp for the same.

iv. Debug in Replay mode

1. On the target machine, from command line, go to the folder having the Replay executable copied earlier.

2. Make sure you have gdbserver installed on the target machine. Enter the following commands.

%> gdbserver :portnumber replay-executable

3. This will start the debugger agent on the target machine. It will wait for gdb to contact it from the host machine.

4. On the host machine, for remote debugging, we use the Zylin Embedded CDT plugin in Eclipse.

5. Go to Debug Configurations as described in the Debug or Run in Replay mode section for local debugging.

6. Select Zylin Embedded debug (Native) to get below figure.

7. Enter the appropriate Project. However do not enter anything in the C/C++ Application text box as shown below.

5. (Optional) Go to the Debugger tab and select Verbose Console mode.

6. Go to the Commands tab. Enter the following

18

a. target remote IP : port number

b. symbol-file /path/to/replay/executable

c. break main

7. The IP is the IP address of the remote target machine. The port number is the port number

specified with the gdbserver command on target machine.

8. Select Debug to start the debugging. You may have to switch manually to Debug perspective. You also may have to resume so that the program stops at the first line of the main function.

9. Follow the same instructions from Step 10 in the Debug or Run in Replay mode section for local debugging.