Debugging Linux Kernel with Visual Studio and KGDB

This tutorial shows how to create and debug a basic Linux Kernel Module using Visual Studio and VisualKernel. Before you begin please install the following:

• Visual Studio
• VisualKernel
• A recent version of Linux (we recommend Ubuntu, CentOS or Fedora)
• Ensure that you can access your Linux machine over SSH

1. Start Visual Studio. Select File->New->Project->VisualKernel->Linux Kernel Module Wizard:
2. Enter the name and location for your project:
3. On the first page of the wizard select “Hello, World” as the module template:
4. On the second wizard page select the Linux machine where you want to build and run your kernel module:
5. Select the location on the Linux machine where you want to build your module or press ‘next’ to proceed with the default one:
6. Debugging with KGDB is done by connecting a COM port on the Linux machine to the Windows machine. If you are using a virtual machine, you can easily create a virtual COM port and connect it to a named pipe. E.g. on VMWare it can be configured through the VM settings dialog (right-click on a VM in the list and select ‘settings’):
7. Specify the COM port number (note that VMWare creates COM2 by default) and the pipe you have created on the last page of the Kernel Module Wizard. It is also recommended to select 115200 as the connection speed:Note that debugging the target via COM port could be very slow. We recommend setting the GDB command timeout to at least 20 seconds as shown above. For older VisualKernel versions, you can set the timeout by adding the “set remotetimeout 20” command to the list of startup commands (see below).
8. Press “Finish” to create your project. Now you can build your kernel module by pressing Ctrl-Shift-B. VisualKernel will automatically transfer the necessary files to the Linux machine and translate any error messages so that Visual Studio can display them in the list:
9. KGDB over COM port (KGDBoC) is the slowest of all supported debugging methods. To reduce delays when starting the debug session, we advise turning off printk() hooking:
10. If you encounter issues with starting a debug session, consider enabling the gdb-level debugging by adding “set debug remote 1” to the Additional GDB Commands: If you are using an older VisualKernel version that does not show the GDB timeout option in the KGDBoC settings, you can add “set remotetimeout 20” to the pre-target commands as well.
11. Set a breakpoint in the LinuxKernelModule1_init() function and press F5 to start debugging. VisualKernel will automatically connect to the Linux kernel and load your kernel module:
12. Note that due to the low speed of KGDBoC, starting the session can take long time. You can reduce it by disabling module enumeration at the beginning of the debug session:
13. Once VisualKernel finishes setting up the debug session, it will automatically load the kernel module, triggering the breakpoitn you set in the init() function:
14. You can use the regular stepping and breakpoint functionality to debug your module as usual. When finished, use the button in the GDB Session window to unload the module:

Note that KGDB is not 100% reliable. It can sometimes crash the Linux system or display incorrect results. VisualKernel employs various fixes and workarounds that solve most KGDB problems, however hangs or crashes can still occur. If you are using VMWare, it is recommended to use the VMWare GDB stub instead of KGDB. See our VMWare debugging tutorial for more details.