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. On the first page of the wizard select “Hello, World” as the module template:
  3. On the second wizard page select the Linux machine where you want to build and run your kernel module:
  4. If your machine is not in the “Targeted Linux computer” list, select “Create a new SSH connection” and provide the connection details:
  5. When you press “Next” VisualKernel will start configuring your Linux machine to build and debug a kernel module. Before this can be done, it will ask you to specify a local directory where kernel symbols and sources will be stored. Please specify a directory on a disk containing at least 5GB of free space:
  6. VisualKernel will now automatically determine and install the Linux packages required to build and debug your kernel:
  7. Then the kernel symbols and sources will be downloaded to the Windows machine:
  8. Finally VisualKernel will ensure that the kernel image and all included modules are readable by the GNU debugger:Note that downloading and indexing only takes place once per target Linux machine. When you create subsequent kernel modules, the files will be automatically loaded from the Kernel Cache directory.
  9. Once the sources and symbols are ready, select the location on the Linux machine where you want to build your module or press ‘next’ to proceed with the default one:
  10. 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’):
  11. 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:
  12. 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:Note that IntelliSense will show some false positive errors due to GNU-specific extensions unknown to Visual Studio. You can hide those errors by right-clicking at the error list and unchecking “Show IntelliSense errors”. Code completion features will still work normally.
  13. 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:
  14. If you switch the View mode to ‘All GDB interaction’ you will see how VisualKernel automatically detected the module load event, determined the section addresses for your module and seamlessly loaded the symbol file. No manual action was required:
  15. Press F10 to step over printk(). The “Hello, World” message will now appear in the “Linux” pane in Visual Studio:
  16. Set a breakpoint in the exit function and select ‘Unload’ in the GDB Session pane:
  17. Press F11 to step into the printk() function. Note how VisualKernel will automatically load the kernel source code. You can use all normal Visual Studio debugging techniques (e.g. call stack or hovering mouse over variables) to debug your module and the kernel itself:
  18. Press Shift-F5 to stop debugging. You can change various settings of your project by right-clicking on it in Solution Explorer and selecting “VisualKernel Project Properties”:

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.