Rong Tao October 28, 2021
Document modification log
| date | Modification content | Modified by | remarks |
|---|---|---|---|
| October 28, 2021 | establish | Rong Tao |
1. Introduction
2. Clone kernel
# Cloning Linux kernel from GitHub $ git clone --depth=32 https://github.com/torvalds/linux # Switch branch $ git checkout master # synchronization $ git pull upstream master
3. Create a branch
$ git checkout -b "new-branch-name"
4. Modify the source code
5. Submit for modification
# First add the modified file $ git add . # Submit modification $ git commit -s -v
After the command git commit -s -v is run, an EDITOR will open, which will start from $GIT_ Select from the EDITOR or $EDITOR environment variable.
- -The s command line parameter will add a line of signed off by at the end of the submission information according to the name of the submitter. You can see this line at the end of each submission, for example - 00cc1633. The main purpose of this line is to track who made the changes.
- -The v option displays the difference between the HEAD submission and the latest submission to be made in a consolidated format. This is not necessary, but sometimes it is useful. Let's talk about the submission information. In fact, a submission information consists of two parts:
The first part, placed on the first line, includes a short description of the changes made. This line is prefixed with [PATCH], followed by the names of subsystems, drivers or architectures, and brief information after:. For example:
[PATCH] staging/dgap: Use strpbrk() instead of dgap_sindex()
After the brief information, we usually leave a blank line and add a detailed description of this submission. In our example, the information is as follows:
The <linux/string.h> provides strpbrk() function that does the same that the dgap_sindex(). Let's use already defined function instead of writing custom.
At the end of the submission is the line sign off by. Note that each line of the submitted information cannot exceed 80 characters, and the submitted information must describe your changes in detail. Never just write a message like Custom function removed. You need to describe what you did and why you did it. Patch reviewers must know what they are reviewing. In addition, the submission information here is also very useful. Whenever you can't understand something, we can use the GIT blade command to read the description of the modification.
6. Generate patch file
After submitting the changes, it's time to generate the patch file. We can use the format patch command to complete:
$ git format-patch master 0001-staging-dgap-Use-strpbrk-instead-of-dgap_sindex.patch # perhaps $ git format-patch master --stdout > dgap-patch-1.patch
7. Send to Linux kernel mailing list
The last step is to send the patch to the Linux kernel mailing list after we generate it. Of course, you can use any mail client, but git provides a special command for this: git send email.
Before sending the patch, you need to know where to send it. Although you can send it directly to linux-kernel@vger.kernel.org This mailing list, but it's likely that your patch will be ignored because of the huge message flow. The best option is to send the patch to the maintainer of the subsystem to which your modification belongs. You can use get_maintainer.pl this script to find the names of these maintainers. All you need to do is pass the file or directory where your code is located as a parameter to the script. As shown in the following output
$ ./scripts/get_maintainer.pl include/linux/sched.h Ingo Molnar <mingo@redhat.com> (maintainer:SCHEDULER) Peter Zijlstra <peterz@infradead.org> (maintainer:SCHEDULER) Juri Lelli <juri.lelli@redhat.com> (maintainer:SCHEDULER) Vincent Guittot <vincent.guittot@linaro.org> (maintainer:SCHEDULER) Dietmar Eggemann <dietmar.eggemann@arm.com> (reviewer:SCHEDULER) Steven Rostedt <rostedt@goodmis.org> (reviewer:SCHEDULER) Ben Segall <bsegall@google.com> (reviewer:SCHEDULER) Mel Gorman <mgorman@suse.de> (reviewer:SCHEDULER) Daniel Bristot de Oliveira <bristot@redhat.com> (reviewer:SCHEDULER) Alexei Starovoitov <ast@kernel.org> (supporter:BPF (Safe dynamic programs and tools)) Daniel Borkmann <daniel@iogearbox.net> (supporter:BPF (Safe dynamic programs and tools)) Andrii Nakryiko <andrii@kernel.org> (supporter:BPF (Safe dynamic programs and tools)) Martin KaFai Lau <kafai@fb.com> (reviewer:BPF (Safe dynamic programs and tools)) Song Liu <songliubraving@fb.com> (reviewer:BPF (Safe dynamic programs and tools)) Yonghong Song <yhs@fb.com> (reviewer:BPF (Safe dynamic programs and tools)) John Fastabend <john.fastabend@gmail.com> (reviewer:BPF (Safe dynamic programs and tools)) KP Singh <kpsingh@kernel.org> (reviewer:BPF (Safe dynamic programs and tools)) linux-kernel@vger.kernel.org (open list:SCHEDULER) netdev@vger.kernel.org (open list:BPF (Safe dynamic programs and tools)) bpf@vger.kernel.org (open list:BPF (Safe dynamic programs and tools))
You will see a set of names and associated email addresses. Now you can send the patch through the following command:
$ git send-email --from "Rong Tao <rongtao@cestc.cn>" \ --to "Lidza Louina <lidza.louina@gmail.com>" \ --cc "Mark Hounschell <markh@compro.net>" \ --cc "Daeseok Youn <daeseok.youn@gmail.com>" \ --cc "Greg Kroah-Hartman <gregkh@linuxfoundation.org>" \ --cc "driverdev-devel@linuxdriverproject.org" \ --cc "devel@driverdev.osuosl.org" \ --cc "linux-kernel@vger.kernel.org"
This is the whole process. The patch has been issued. Now all you need to do is wait for the feedback from the Linux kernel developer. After you send the patch and the maintainer accepts it, you will see it in the maintainer's warehouse (such as the patch you saw earlier). After a period of time, the maintainer will send a pull request to Linus, and then you will see your patch in the mainline warehouse.
8. Some recommendations
At the end of this section, I want to give you some suggestions. Most of these suggestions are about what to do and what not to do in the development process of Linux kernel:
- Think, think, think again. Think twice before you decide to send a patch.
- After every time you change the Linux kernel source code - try compiling it. I mean, after any modification, it should be compiled continuously. No one likes those that don't even compile through modification.
- The Linux kernel has a code specification guide that you need to follow. There is a great script to help you check your changes. This script is - scripts/checkpatch.pl. Just pass the changed source file to it, and then you will see the following output:
$ ./scripts/checkpatch.pl -f drivers/staging/dgap/dgap.c
WARNING: Block comments use * on subsequent lines
#94: FILE: drivers/staging/dgap/dgap.c:94:
+/*
+ SUPPORTED PRODUCTS
CHECK: spaces preferred around that '|' (ctx:VxV)
#143: FILE: drivers/staging/dgap/dgap.c:143:
+ { PPCM, PCI_DEV_XEM_NAME, 64, (T_PCXM|T_PCLITE|T_PCIBUS) },
With the help of git diff command, you will also see some problems:
- Linus does not accept github pull requests
- If your changes consist of different and unrelated changes, you need to split the changes by splitting the submissions. The GIT format patch command will generate a patch for each submission. The title of each patch will contain a vN prefix, where N is the patch number. If you plan to send a series of patches, it may be helpful to pass the -- cover letter option to the GIT format patch command. This will generate an additional file that includes a cover letter describing the changes made to your patch set. It is also a good idea to use the -- in reply to option in the GIT send email command, which allows you to send the patch set as a reply to the cover letter. For maintainers, the structure of your patch set looks like this:
You can pass the message ID parameter to the -- in reply to option, which can be found in the output of the GIT send email command.
One very important thing is that your email must be in plain text format. Generally speaking, send email and format patch commands are very useful in kernel development, so please consult the relevant documents of these commands, and you will find many useful options, such as git send email and git format patch.
- If you don't get an immediate reply after sending the patch, please don't be surprised, because the maintainers are very busy.
- The scripts directory contains many scripts that are useful for Linux kernel development. We have seen two scripts in this directory: checkpatch.pl and get_maintainer.pl. In addition, you can also find stack usage script, which can print stack usage, extract vmlinux script can extract uncompressed endoscopic images, and many other scripts. Outside the scripts directory, you will also find many useful scripts written by Lorenzo Stoakes for kernel development.
- Subscribe to the Linux kernel mailing list. There are a lot of letters in the lkml list every day, but it is helpful to read them and learn something similar to the current development status of the Linux kernel. In addition to lkml, there are other mailing lists that correspond to different Linux kernel subsystems.
- If your patch is not accepted for the first time, you will receive feedback from Linux kernel developers. Please make some modifications and resend the patch with [PATCH vN](N is the patch version number), for example:
[PATCH v2] staging/dgap: Use strpbrk() instead of dgap_sindex()
Similarly, this patch must also include an update log to describe the changes made since the last patch. Of course, this article is not an exhaustive guide to Linux kernel development, but some of the most important things have been clarified.
Happy Hacking!