Debugging PintOS Tests

You have several options to use gdb in VSCode, we however suggest you go with the first option described below.

Debugging PintOS from within VSCode

We have added two files .vscode/launch.json and .vscode/tasks.json to the starter repositories of the various projects that contain configurations enabling to debug the PintOS kernel from inside VSCode. Here is an excerpt from the file .vscode/tasks.json from Project 0:

{
  "version": "2.0.0",
  "tasks": [
    {
        "label": "[P1] compile",
        "type": "shell",
        "command": "make",
        "options": {
            "cwd": "${workspaceFolder}/src/userprog"
        }
    },
    {
        "label": "[P1] Run Test in GDB mode",
        "type": "shell",
        "isBackground": true,
        "problemMatcher": [],
        "dependsOn": [
            "[P1] compile"
        ],
        "command": "pintos -v -k -T 60 --bochs --gdb  -- -q  run do-nothing",
        "options": {
            "cwd": "${workspaceFolder}/src/userprog/build"
        }
    }
  ]
}

Please familiarize yourself with those files so you can modify them as needed in the future. For more information about this file format, please see the corresponding documentation.

With these files in place (and correctly edited to refer to the executable you would like to debug), select the Debug PintOS Executable from the top of the VSCode debugging pane. GDB should now be open and your program should stop executing at the entry point to PintOS. From here on you can set breakpoints and step through the code as usual when debugging in VSCode.

In this mode you can use the interactive VSCode commends for debugging and inspect variable values, the stack back trace and other information related to debugging through the VSCode interface. In addition you have all of the supported GDB commands available to you by prefixing them with -exec in the debugger command prompt at the very bottom of the ‘Debug Console’ window.

Debugging PintOS from the Command Line

The steps for running the debugger on an individual PintOS test are nearly identical to the steps given in Running PintOS tests, with the only difference being that you’ll need to add the PINTOS_DEBUG environment variable. For example, to debug the stack-align-0 test, you would do the following:

make
PINTOS_DEBUG=1 pintos-test stack-align-0

This will open GDB in your current terminal. Proceed with setting breakpoints, continuing, etc. When you are done debugging, type quit in GDB, and you then will see whatever output the test created while it was running.

When you want to debug a test, running pintos-test with PINTOS_DEBUG=1 is what you want to do 99% of the time.

On a rare occasion, you will want to see what the test is outputting while you are stepping through it in the debugger. To do this, the instructions are slightly different. Most of the above will remain the same, except that you will set PINTOS_DEBUG=2 (note 2 instead of 1). When you run pintos-test with PINTOS_DEBUG=2, GDB will not open in your current terminal; instead, the output of the test will be shown live in your current terminal. You’ll need to open a second terminal (either through tmux or by just ssh’ing into your VM again in a separate terminal window), navigate to the build/ subdirectory of the directory you ran pintos-test in, then run pintos-gdb kernel.o. For example, to debug the open-twice test while being able to observe its live output, you would do the following:

cd /pintos/src/userprog
make
PINTOS_DEBUG=2 pintos-test open-twice

Then open a second terminal, and do the following:

cd /pintos/src/userprog/build
pintos-gdb kernel.o

In your second terminal, GDB should now be open. You can proceed with debugging as usual. The only difference is that now the live output of the process you’re debugging will appear in your first terminal.