CS 202 - Homework 4.2 Notes

This document provides detailed instructions and hints for working on the assembly programming portion of HW 4, including setting up your environment and debugging using gdb. Carefully follow all instructions. If you have trouble, see me in office hours.

Setting up your environment

To compile x86-64 assembly code, you need to work under Linux. Here are your options, in increasing order of effort:

  1. Work on the machines in MBH 632.

  2. From your Mac or PC, ssh to basin so you have a Linux terminal, and mount basin as a network drive, so you can edit your files with an editor installed on your local computer (e.g., Atom).
    Be sure to do both! In brief:

  3. Install Linux as a virtual machine on your computer

Once you have a terminal open, navigate to your cs202 folder. If you don't have one yet, follow the instructions at the end of HW 1. If you are working on the lab machines or on basin, you can copy my HW 4 code directory as follows:

basin:~/cs202$ cp -r ~schar/cs202/hw4 .
basin:~/cs202$ cd hw4
basin:~/cs202/hw4$ gcc -g -o hw4 hw4main.c hw4asm.s
Next, make sure the given code compiles and runs:
basin:~/cs202/hw4$ gcc -g -o hw4 hw4main.c hw4asm.s
basin:~/cs202/hw4$ ./hw4
usage: ./hw4  
basin:~/cs202/hw4$ ./hw4 3 5
input: a=3, b=5
mult(a, b)   = 15
avg(a, b)    = -1
max(a, b)    = -1
maxabs(a, b) = -1
sumseq(a, b) = -1
countbits(a) = -1

Now, open the file hw4asm.s in your editor and start tackling one assembly function at a time, testing using the familiar cycle of "save, compile, run". Except, even better than run, "debug":

Debugging using gdb -tui

We will use the Gnu debugger GDB with option TUI (Text User Interface). If you want to learn more, check out one of the many tutorials, for instance Beej's Quick Guide to GDB.

Compiling our program with option "-g" allows us to use the debugger gdb to step through our C code and/or assembly code one line at a time, and even observe the current values of the registers. Here are the basic steps involved:

  1. Start the debugger with option -tui, providing the name of the executable as an argument:
    gdb -tui hw4
    You will see the "(gdb)" prompt at the bottom, as well as the source code listing within a black frame in the top half of your terminal window. Be sure to make the window large enough.

  2. The code listing is provided by the TUI mode, which is nice, but can also be confusing. If the window ever looks messed up, try typing Control-L to redraw it.

  3. To debug one of the assembly functions, we'll set a "breakpoint" at the beginning of the function, so execution halts when we reach it. For illustration, we will examine the function "mult", but of course you should later set the breakpoint in the function you're currently working on:
    (gdb) break mult
  4. Next, we start the program using the command "run". Note that our program expects command-line arguments. We can provide them after the "run" command:
    (gdb) run 3 5
  5. The program will now run until it hits our breakpoint. You should see the assembly listing in the window, with the beginning of the "mult" function highlighted. (If the black frame is messed up, hit Contol-L.)

  6. Before we start single-stepping through our program, we also want to see the registers. We can do this by typing "tui reg general", or shorter:
    (gdb) tui reg gen
  7. Now we're ready to step through our program. Type
    (gdb) step
    and see how the highlighted line of code advances.

  8. To keep stepping, simply hit Enter, which repeats the last command. (Note that we cannot use the arrow keys to get our previous commands, since in TUI mode they instead scroll the code window.)

  9. As you are stepping through the code, note that register contents keep updating as you go. This will be extremely useful for debugging the assembly code you write.

  10. If you want to resume execution of your program (when you are done single-stepping), type "continue", or shorter
    (gb) cont
  11. To quit the debugger, type
    (gb) quit
    or Control-D.
Have fun!