Kernel Patch Validation and Maintainer Identification

The Maintainer's Perspective: Why These Tools are Crucial

Kernel maintainers are volunteers who review and integrate hundreds of patches, often on top of their own development work. Their time is their most valuable resource. Submitting a patch with simple coding style errors or sending it to the wrong person wastes that time and is a common reason for patches to be ignored or rejected.

The kernel community has developed scripts to automate these checks, empowering contributors to fix issues before submission. Let's start with a look at why this is so important.

As you can see, using these tools isn't just a suggestion; it's a core part of the expected workflow. Let's dive into the first script.

Step 1: Validating Your Patch with checkpatch.pl

checkpatch.pl is a Perl script located in the scripts/ directory of the kernel source tree. Its purpose is to scan your code changes for violations of the Linux kernel coding style and other common errors.

Running checkpatch.pl

You run checkpatch.pl on the change you've just made. Assuming your change is the latest commit on your branch, you can pipe the output of git show directly into the script:

git show HEAD | scripts/checkpatch.pl

This command shows the full commit (log message and diff) and pipes it to checkpatch.pl for validation. You should aim to fix all ERRORs and WARNINGs unless you have a very strong, justifiable reason to leave them.

Now, let's see this in action.

Step 2: Identifying Recipients with get_maintainer.pl

Once your patch is clean, you need to know who to send it to. The Linux kernel is divided into hundreds of subsystems, each with its own maintainers and mailing lists. Sending a patch to the wrong destination is a guarantee it will be lost.

get_maintainer.pl is another script in the scripts/ directory that automates this process. It inspects the files your patch modifies, consults the MAINTAINERS file, and analyzes the git history to produce a list of the most relevant people and mailing lists.

Running get_maintainer.pl

You can run this script on the patch file itself or directly on the list of files you have changed. To get the list of files from your last commit and pipe them to the script, you can use:

git show --pretty="" --name-only HEAD | scripts/get_maintainer.pl

This command prints only the names of the files changed in the HEAD commit and uses that as input for get_maintainer.pl. The output will be a list of email addresses. Typically, you will put the individual maintainers in the To: field of your email and the mailing lists in the Cc: field.

Let's see this in action as well.

A Practical Walkthrough

Let's solidify this with a scenario. Imagine you have made a change to the file drivers/tty/serial/sh-sci.c and have just committed it. Now you need to perform your pre-flight checks.

The following image shows the output of running both scripts on a hypothetical change to that file.

Your Task:

1. Analyze the checkpatch.pl output.

   • What command would you have run to generate this output for your last commit?
   • The script reports 0 errors, 1 warning. What is the warning about?
   • What should your next action be regarding this warning?
   Click for answers

   • Command: git show HEAD | scripts/checkpatch.pl
   • Warning: CHECK: "SCI_SYSC_SCSMR2_DEFAULT" seems to be a pre-existing invalid syscall nr. This indicates that a macro might be defined in a way that resembles a system call number, which could be problematic.
   • Action: Investigate the warning. Is this a false positive, or does it point to a real, albeit pre-existing, issue in the code? Since checkpatch flagged it as a CHECK, it requires thought. You would examine the definition of SCI_SYSC_SCSMR2_DEFAULT and the context of its use. If it's a false positive, you can proceed, but if it's a genuine, subtle bug, you might have discovered an opportunity for another patch!

2. Analyze the get_maintainer.pl output.

   • What command would you have run to generate this output?
   • Based on the output, who should receive your patch? How would you structure the To: and Cc: fields of your email?
   Click for answers

   • Command: git show --pretty="" --name-only HEAD | scripts/get_maintainer.pl
   • Recipients: You should send the patch To: Greg Kroah-Hartman (gregkh@linuxfoundation.org) as he is listed as the maintainer for the serial core. You should Cc: the linux-serial@vger.kernel.org and linux-kernel@vger.kernel.org mailing lists. Other individuals listed are likely past contributors; including them in Cc: is often a good idea but the maintainer and primary list are the most important.

Conclusion

You now know how to perform the two most important validation steps before submitting a kernel patch. This workflow is fundamental to being a productive and respected member of the kernel development community.

Key Takeaways:

• Always validate your changes with scripts/checkpatch.pl before submission. Aim for zero errors and zero warnings.
• Use scripts/get_maintainer.pl to find the correct maintainers and mailing lists for your patch.
• Running these scripts demonstrates your competence and respect for the community's process, significantly increasing your chances of a successful contribution.

Preview of the Next Lesson:

Your change is now committed, validated, and you know who to send it to. The final step before sending is to package your commit(s) into the standard email format. In the next lesson, you will learn how to generate and format a patch series using git-format-patch, preparing it for submission to the mailing lists.