How to contribute to Linux kernel
We will introduce how to contribute to Linux kernel in this post. This post mainly includes two parts: how to set up a development environment and how to create and submit a patch.
Build the development environment for kernel
You can just clone and build the kernel, or if you want to try the compiled kernel, it is recommended to try in a VM.
While there are multiple kinds of VMs (e.g., Vmware, VirtualBox, qemu, firecrackers), I would like to introduce Vagrant and make it work on top of qemu/kvm by libvirt.
The reason we start with Vagrant is that it is easy and convenient to manage and begin with. For most of the requirements, Vagrant is enough. You can achieve similar work or more specific requirements by using command-line qemu-system-x86_64 or virsh provided by libvirt.
Install Vagrant with libvirt
Before we begin to install Vagrant, we should check if the CPU supports virtualization. You can use the command grep -E 'vmx|svm' /proc/cpuinfo to check if the CPU supports virtualization. If the output is 0, it means your processor is not capable of running KVM. In this case, you should enable the virtualization in BIOS.
Then check if your system can use KVM acceleration. You can just type kvm-ok to see the result. If the output is KVM acceleration can be used, it means your system can use KVM acceleration.
As we mentioned, it is convenient as there is a bash script for installation (install.bash) provided by vagrant-libvirt. It will help you install libvirt and Vagrant:
curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
chmod +x ./install.bash
./install.bash
Besides, you should grant the privilege for user:
sudo usermod -aG kvm "$USER"
sudo usermod -aG libvirt "$USER"
Please exit and re-login your account to make the privilege take effect.
You can also install some plugins with the command vagrant plugin install <your_plugin>. For example, if you would like to use rsync to sync your files between VM and your host machine, you may want the plugin vagrant-rsync-back.
Then you should write a Vagrantfile to indicate how to build your VM. You can run vagrant up to bring your VM up and vagrant ssh to connect to your VM. If you would like to use vscode for remote development, vagrant ssh-config would help you set up your ssh configuration.
You can use virsh -c qemu:///system list to show all the VMs brought up by qemu/libvirt.
Create and Submit the Patch
Find Where to Begin
First you should find the correct place to develop. It is recommended to use the MAINTAINERS file, which will tell about the maintainers, reviewers and the source tree of subsystems. Most subsystem maintainers run their own trees and want to see patches prepared against those trees.
Here is an example of BPF subsystem:
BPF [GENERAL] (Safe Dynamic Programs and Tools)
M: Alexei Starovoitov <ast@kernel.org>
M: Daniel Borkmann <daniel@iogearbox.net>
M: Andrii Nakryiko <andrii@kernel.org>
R: Martin KaFai Lau <martin.lau@linux.dev>
R: Song Liu <song@kernel.org>
R: Yonghong Song <yhs@fb.com>
R: John Fastabend <john.fastabend@gmail.com>
R: KP Singh <kpsingh@kernel.org>
R: Stanislav Fomichev <sdf@google.com>
R: Hao Luo <haoluo@google.com>
R: Jiri Olsa <jolsa@kernel.org>
L: bpf@vger.kernel.org
S: Supported
W: https://bpf.io/
Q: https://patchwork.kernel.org/project/netdevbpf/list/?delegate=121173
T: git git://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf.git
T: git git://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git
F: Documentation/bpf/
F: Documentation/networking/filter.rst
F: Documentation/userspace-api/ebpf/
F: arch/*/net/*
F: include/linux/bpf*
F: include/linux/btf*
F: include/linux/filter.h
F: include/trace/events/xdp.h
F: include/uapi/linux/bpf*
F: include/uapi/linux/btf*
F: include/uapi/linux/filter.h
F: kernel/bpf/
F: kernel/trace/bpf_trace.c
F: lib/test_bpf.c
F: net/bpf/
F: net/core/filter.c
F: net/sched/act_bpf.c
F: net/sched/cls_bpf.c
F: samples/bpf/
F: scripts/bpf_doc.py
F: scripts/pahole-flags.sh
F: scripts/pahole-version.sh
F: tools/bpf/
F: tools/lib/bpf/
F: tools/testing/selftests/bpf/
We can develop our patch based on the bpf-next tree.
Configure Email Client
As the patches are all submitted with email in plain text, you should configure a email client to send the patch. It is recommended to use git-email.
Install it on Ubuntu:
sudo apt-get install git-email
Then add the following part to your .gitconfig file to enable email sending:
[sendemail]
smtpencryption=tls
smtpserver=smtp.gmail.com
smtpuser=<youraccount>@gmail.com
smtpserverport=587
[credential]
helper = store
Create a Patch
For single patch:
git format-patch --subject-prefix='PATCH' -i HEAD~
For patch series:
git format-patch --cover-letter --subject-prefix='PATCH' -N # N is the number of patches
This will generate N+1 patch. There will be a patch beginning with 0000 which indicates itself as the cover-letter patch. It would be like:
[...]
Subject: [PATCH 0/2] *** SUBJECT HERE ***
*** BLURB HERE ***
[...]
You should use one line to summary what this series is about to replace *** SUBJECT HERE *** and clearly describe what you do in the main body to replace *** BLURB HERE ***.
Often, your patch will be requested to modify and re-submit. Then you have to mark the version of your patch series in the subject and states the difference between every version in your main body of the cover letter. Also there would sometimes have to add a tag pointing to relevant source tree in the subject. This would be like:
[...]
Subject: [PATCH v3 bpf-next 0/2] *** SUBJECT HERE ***
*** BLURB HERE ***
v3:
- xxxx
- yyyy
v2:
- zzzz
[...]
Before Submit
You should do some more checks before submitting your patches.
First of all, the patches must be compiled successfully and pass all the tests of subsystem.
Secondly, style-check your changes. Check your patch for basic style violations. Kernel provide a checker scripts/checkpatch.pl. Simply run ./scripts/checkpatch.pl 00*.patch
The checker reports at three levels:
- ERROR: things that are very likely to be wrong.
- WARNING: things requiring careful review.
- CHECK: things requiring thought.
Often, you should fix all the ERRORs and check carefully about all the WARNINGs.
Send the Patch
Last step is to send the patch through emails. You can see who to send by the scripts provided by kernel: ./scripts/get_maintainer.pl 00*.patch
"David S. Miller" <davem@davemloft.net> (maintainer:NETWORKING [IPv4/IPv6])
David Ahern <dsahern@kernel.org> (maintainer:NETWORKING [IPv4/IPv6])
Eric Dumazet <edumazet@google.com> (maintainer:NETWORKING [GENERAL])
Jakub Kicinski <kuba@kernel.org> (maintainer:NETWORKING [GENERAL])
Paolo Abeni <pabeni@redhat.com> (maintainer:NETWORKING [GENERAL])
Andrii Nakryiko <andrii@kernel.org> (maintainer:BPF [SELFTESTS] (Test Runners & Infrastructure))
Mykola Lysenko <mykolal@fb.com> (reviewer:BPF [SELFTESTS] (Test Runners & Infrastructure))
Alexei Starovoitov <ast@kernel.org> (supporter:BPF [GENERAL] (Safe Dynamic Programs and Tools),commit_signer:1/2=50%)
Daniel Borkmann <daniel@iogearbox.net> (supporter:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Martin KaFai Lau <martin.lau@linux.dev> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Song Liu <song@kernel.org> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Yonghong Song <yhs@fb.com> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
John Fastabend <john.fastabend@gmail.com> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
KP Singh <kpsingh@kernel.org> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Stanislav Fomichev <sdf@google.com> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Hao Luo <haoluo@google.com> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Jiri Olsa <jolsa@kernel.org> (reviewer:BPF [GENERAL] (Safe Dynamic Programs and Tools))
Shuah Khan <shuah@kernel.org> (maintainer:KERNEL SELFTEST FRAMEWORK)
"Jörn-Thorben Hinz" <jthinz@mailbox.tu-berlin.de> (commit_signer:1/2=50%,authored:1/2=50%,added_lines:60/72=83%)
Yixin Shen <bobankhshen@gmail.com> (commit_signer:1/2=50%,authored:1/2=50%,added_lines:12/72=17%,removed_lines:1/1=100%)
netdev@vger.kernel.org (open list:NETWORKING [IPv4/IPv6])
linux-kernel@vger.kernel.org (open list)
bpf@vger.kernel.org (open list:BPF [SELFTESTS] (Test Runners & Infrastructure))
linux-kselftest@vger.kernel.org (open list:KERNEL SELFTEST FRAMEWORK)
You should send to the mailing-list of the subsystem (e.g., bpf@vger.kernel.org in BPF subsystem) and cc some of the maintainers and reviewers. You can send to your own email address before sending the patch to mailing-list for another check.
git send-email --to <a@example.com> --cc <b@example.com> 00*.patch
After sending you patch, you can just wait for the response and see if more things should be done.
Here is my patch which is applied to bpf-next.
And there is an awesome patch which can be seen as a template. It covers the background, motivation, detailed design and implementation, evaluations with analysis, future work, discussion and a conclusion. Just as someone commented in reddit:
“Just give me 1 month to write a thesis for this patch…”
Conclusion
Hopefully this post has provided a helpful understanding of how you can participate in the process of contributing to the kernel. Remember that any open source project is no more than the sum of what its contributors put into it.