Skip to content

Latest commit

 

History

History
256 lines (210 loc) · 11.7 KB

README.md

File metadata and controls

256 lines (210 loc) · 11.7 KB
Raw

VSCode for Linux kernel development

Features

Editor:

  • Symbol lookup (go-to-definition etc) based on your .config
  • Clangd and Checkpatch live squiggles and linting
  • Syntax highlighting for KConfig, assembly language, and Device Trees

Compilation:

  • Minimal defconfig generation that boots in a VM
  • Easy cross-compilation to arm64
  • Ctrl+Click on error messages point back to code

Testing on a local VM:

  • Minimal Debian VMs generation
  • Autostart of C and shell payloads
  • Integrated serial output
  • Easy SSH into the VM

Patch management:

  • git format-patch and send-email assistant
  • Mailing list exploration using Patchwork
  • kernel.org's cgit links generation

Debugging:

  • Integrated VM debugger using GDB (function and conditional breakpoints, watchpoints, backtraces, variable inspection, step-by-step, disassembly views etc...)
  • Integrated IPython notebook for ftrace analysis
  • BPF selftests cross-compilation and run tasks
  • Ctrl-Click addresses like __sys_sendmsg+0x284/0x370 in your backtraces and they will automatically get resolved by addr2line
  • Easy systemtap probing (right click -> "Trace this function") and logging with deep argument inspection (logs buffer opens immediately on logs)

Syzkaller:

  • Straightforward setup to test syzkaller fuzzer descriptions
  • Integrated IPython notebook to reproduce syzbot bugs

Other:

  • Transparent remote development from a laptop
  • Setup that is easy to modify (bash scripts) and contribute to
  • Easy to update

System-wide installation (done once)

Install the dependencies required to run all the supported commands/tasks:

curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
sudo install -o root -g root -m 644 microsoft.gpg /usr/share/keyrings/microsoft-archive-keyring.gpg
sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-archive-keyring.gpg] https://packages.microsoft.com/repos/vscode stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install code gdb-multiarch ccache clang clangd llvm lld libguestfs-tools libssl-dev trace-cmd python3-pip jsonnet libelf-dev bison bindfs mmdebstrap proot systemtap flex yacc bc

For VS Code to keep track of all the files in your kernel source tree:

sudo bash -c 'echo "fs.inotify.max_user_watches=524288" >> /etc/sysctl.conf'
sudo sysctl -p

Linux tree setup (done once per kernel tree)

Inside a fresh linux kernel tree, e.g.:

git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
cd linux

Create a .vscode directory with our config files inside:

git clone https://github.com/FlorentRevest/linux-kernel-vscode .vscode/
.vscode/tasks.sh update  # Needs to be run once to generate settings.json

Extensions (done once)

If you open the kernel tree in VSCode. A pop-up will appear recommending workspace extensions, install them all. Here is what they do:

  • C/C++ via Clangd this integrates with a compile_commands.json file autogenerated on kernel builds.
  • Git integration this provides a git blame at the end of the selected line and adds many options to the source control tab (commit log, file history, branches switching etc...).
  • x86 and x86_64 Assembly provides syntax highlighting for asm files.
  • ARM64 Assembly same, but for arm.
  • Device Tree provides syntax highlighting for dts files.
  • KConfig provides syntax highlighting for Kconfig files.
  • Checkpatch provides squiggle highlighting of checkpatch errors on file saves.
  • Patchwork view, apply and search patches from the linux patchwork instance.
  • Addr2line lets users ctrl+click on addresses in backtraces and they get resolved into lines of code.
  • Git send-email facilitates sending patches or series to the list.
  • Syzlang highlights syzkaller syscall descriptions.
  • Syzkaller coverage can highlight lines covered by a running instance of syz-manager fuzzing.
  • SystemTap Assistant facilitates kernel functions or lines tracing by dynamically generating systemtap scripts and rendering logs received from these probes in a buffer.
  • SystemTap highlights systemtap scripts.
  • Microsoft C/C++ only the GDB integration of this plugin is used, every features interacting with the code is disabled in favor of Clangd which works much better.
  • Trailing spaces highlights forgotten trailing spaces.

If the pop-up didn't appear or you dismissed it:

  1. Click on the Extensions tab on the left hand side of VSCode
  2. Enter "@recommended" in the search bar
  3. Manually click the "Install" button on every extension in the "Workspace Recommendations" section

NOTE: You probably want either one of these extensions too (run the command in the Ctrl+P dialog box):

Basic usage

  • Compile the kernel using Ctrl+Shift+B (if you don't have a .config yet, it will generate a functional one automatically for you).
  • Run it with F5.
  • Debug with breakpoints by clicking on the left of a line number.
  • Open a file by name with Ctrl+P.
  • Navigate between symbol definition/declaration with F12.
  • Get clang squiggles by building the kernel once and waiting for clangd to index the code for a bit. Clang also supports code refactoring (symbol renames with F2 for example) and auto-formatting according to kernel rules with Ctrl+Shift+I.
  • Get checkpatch squiggles by saving the current file.
  • Interact with git following this demo.
  • Change the content of TARGET_ARCH in .vscode/local.sh to arm64 to transparently get an aarch64* workspace (future compilations/virtual machines will be arm64).
  • Customize per-workspace VS-Code settings the normal way (edit local .vscode/settings.json, or use Ctrl+Shift+P -> "Preferences: Open Settings (UI)"). Note that fields that exist in settings.jsonnet will get overwritten when you run the update task. Also, comments in your .vscode/settings.json will get deleted.
  • Autostart commands or codes at VM start time by modifying the content of .vscode/autostart/ (eg: always run tests that exercise the kernel subsystem you work on).
  • Find more helper tasks using Ctrl+Shift+P, search for Run task and then pick from the list (for example you can run menuconfig, create SSH sessions, update to the latest version of this setup etc).
  • Interact with your VM from an external terminal using commands such as lkv start, lkv ssh, lkv stop etc...

Make sure to check the Tips and Tricks and Interactive Playground options under Help in the menu bar to learn more about basic VS Code usage.

Commands outside of VSCode

All tasks are implemented in the tasks.sh file. This script can be run from anywhere. For example:

alias lkv=~/linux/.vscode/tasks.sh
lkv build # Equivalent to Ctrl+Shift+B
lkv start # Equivalent to F5
lkv ssh
lkv stop
lkv push ./file
lkv pull /root/file
lkv run ls /
lkv chroot

Technical documentation

If you want or need to dive into the nitty-gritty of this setup:

All the VSCode config files are maintained under this git repository. Improvement PRs can be sent to https://github.com/FlorentRevest/linux-kernel-vscode and will be easily fetchable by users thanks to the auto-update task (which updates .vscode from there).

  • .vscode/tasks.json describes per-workspace tasks to VSCode. These tasks are entries under the Ctrl+Shift+P Run task dialog box. All task basically just call tasks.sh with a different command flag.
  • .vscode/tasks.sh is a bash script with a big switch statement that implements all tasks exposed by tasks.json. They all share a common preamble customizable locally by local.sh.
  • .vscode/settings.jsonnet provides per-workspace configuration values to VSCode and its extensions. This is constructed by tasks.sh by evaluating settings.jsonnet with the existing settings as an input. The JSonnet file contains sane defaults valid for all kernel developers. For example, it specifies which files VSCode should ignore, how to handle spaces and tabs or how to generate kernel.org cgit links from a file path and line. Individual developers can then customize per-workspace settings for their kernel trees while still benefiting from the defaults in the JSonnet file.
  • .vscode/syzbot.ipynb is a reference Jupyter notebook to automate the repetitive aspects of reproducing a syzkaller bug. Every step along the way is guided.
  • .vscode/launch.json describes how to run a VM with a debugger attached to VSCode.
  • .vscode/extensions.json describes a list of recommended extensions to VSCode. These are meant to be sane defaults valid for all kernel developers. Extensions are pulled in from the VSCode Marketplace.
  • .vscode/local.sh is a local config file not updated by the auto-update task. It can be used to implement special features or override defaults for specific needs.
  • .vscode/autostart/ contains the template for a dummy task that gets run at the end of the VM's boot. Before running a VM, tasks.sh is responsible for detecting changes to these files and updating the files in the VM's rootfs.

Note: The Patchwork and Git Send Email extensions are homegrown and maintained in other git repositories. Pull-requests or bug reports are also welcome there.