Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/FlorentRevest/linux-kernel-vscode

Reference setup for Linux kernel development in VSCode
https://github.com/FlorentRevest/linux-kernel-vscode

Last synced: 14 days ago
JSON representation

Reference setup for Linux kernel development in VSCode

Awesome Lists containing this project

README 

        
# 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](https://syzkaller.appspot.com/upstream) 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:



```shell

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.:



```shell

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:



```shell

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](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd)

    this integrates with a `compile_commands.json` file autogenerated on kernel

    builds.

*   [Git integration](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)

    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](https://marketplace.visualstudio.com/items?itemName=13xforever.language-x86-64-assembly)

    provides syntax highlighting for asm files.

*   [ARM64 Assembly](https://marketplace.visualstudio.com/items?itemName=MKornelsen.vscode-arm64)

    same, but for arm.

*   [Device Tree](https://marketplace.visualstudio.com/items?itemName=plorefice.devicetree)

    provides syntax highlighting for dts files.

*   [KConfig](https://marketplace.visualstudio.com/items?itemName=luveti.kconfig)

    provides syntax highlighting for Kconfig files.

*   [Checkpatch](https://marketplace.visualstudio.com/items?itemName=idanp.checkpatch)

    provides squiggle highlighting of checkpatch errors on file saves.

*   [Patchwork](https://marketplace.visualstudio.com/items?itemName=florent-revest.patchwork)

    view, apply and search patches from the

    [linux patchwork instance](https://patchwork.kernel.org/).

*   [Addr2line](https://marketplace.visualstudio.com/items?itemName=florent-revest.addr2line)

    lets users ctrl+click on addresses in backtraces and they get resolved into

    lines of code.

*   [Git send-email](https://marketplace.visualstudio.com/items?itemName=florent-revest.git-send-email)

    facilitates sending patches or series to the list.

*   [Syzlang](https://marketplace.visualstudio.com/items?itemName=florent-revest.vscode-syzlang)

    highlights syzkaller syscall descriptions.

*   [Syzkaller coverage](https://marketplace.visualstudio.com/items?itemName=florent-revest.syzkaller-coverage)

    can highlight lines covered by a running instance of syz-manager fuzzing.

*   [SystemTap Assistant](https://marketplace.visualstudio.com/items?itemName=florent-revest.systemtap-assistant)

    facilitates kernel functions or lines tracing by dynamically generating

    systemtap scripts and rendering logs received from these probes in a buffer.

*   [SystemTap](https://marketplace.visualstudio.com/items?itemName=nzh21.systemtap-syntax)

    highlights systemtap scripts.

*   [Microsoft C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)

    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](https://marketplace.visualstudio.com/items?itemName=shardulm94.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):



*   [Vim emulation](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim):



    ```shell

    ext install vscodevim.vim

    ```



*   [Emacs emulation](https://marketplace.visualstudio.com/items?itemName=vscodeemacs.emacs):



    ```shell

    ext install vscodeemacs.emacs

    ```



## 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](https://www.youtube.com/watch?v=UQPb73Zz9qk).

*   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:



```shell

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](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks).

    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](https://code.visualstudio.com/docs/getstarted/settings) and its

    extensions. This is constructed by `tasks.sh` by evaluating

    [`settings.jsonnet`](http://depot/company/teams/security/kernel/tools/vscode/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](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations).

*   `.vscode/extensions.json` [describes a list of recommended extensions to

    VSCode](https://code.visualstudio.com/docs/editor/extension-marketplace#_recommended-extensions).

    These are meant to be sane defaults valid for all kernel developers.

    Extensions are pulled in from

    [the VSCode Marketplace](https://marketplace.visualstudio.com/).

*   `.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](https://github.com/FlorentRevest/vscode-patchwork) and

[Git Send Email](https://github.com/FlorentRevest/vscode-git-send-email)

extensions are homegrown and maintained in other git repositories.

Pull-requests or bug reports are also welcome there.