From OMAPpedia

Contents 1 How to submit patches 1.1 Writing clean code 1.1.1 Linux Documentation 1.1.2 Checking tools 1.1.2.1 checkpatch.pl 1.1.2.2 sparse 1.2 GIT patch creation 1.2.1 Useful links: 1.3 Build Testing 1.4 Testing 1.5 GIT setup 1.5.1 GIT commands 1.5.2 GIT useful helper script 1.6 Sending patch emails with GIT 1.6.1 Useful links 1.6.2 Note on git commit comments

[edit] How to submit patches

OMAP platform linux mailing list can be used for patch submissions and discussions. Click here to subscribe to the list or/and get more information.

We recommend the use of git-format-patch and git-send-email to generate and submit patches.

More detailed information...

Introduction: This page gathers some useful information for releasing (or proposing for release) some code into the Linux kernel.

Note that for TI folks, a presentation is available here. Also look at here

[edit] Writing clean code

[edit] Linux Documentation

The following Linux documentation must be read before anything:

• Documentation/SubmittingPatches
• Documentation/CodingStyle
• Documentation/SubmittingDrivers
• Documentation/SubmitChecklist

A few tips:

• Make sure your driver doesn't depend on any and includes.
• Drop the ARCH dependency and try to compile the driver on other architectures
• x86 architecture is very useful for compile testing because all the nice tools work there: randconfig, allmodconfig, allyesconfig
• try something like (using USB as example): make allmodconfig && make drivers/usb
• you can also build one single file. e.g. make allmodconfig && make drivers/usb/dwc3/core.o

It's important to make your driver not depend on the architecture, you make sure that we can catch compile errors with linux-next, it's easier for any maintainer to compile test your patches, you can make use of randconfig, allmodconfig and allyesconfig, and so on. There are many arguments to make every driver compilable on all architecture, but the biggest one is that it will force us to remove stupid dependencies from our drivers. It will force us to write more portable code.

[edit] Checking tools

[edit] checkpatch.pl

scripts/checkpatch.pl is a script in the kernel tree that facilitates better kernel code, and can be used to check many coding style rules.

This script applies on patch files by default, but can also process complete source files using the -f option. To get a list of options, run

checkpatch.pl -h

The attached script (File:Run-checkpatch.tar.gz) is an example used to call easily the checkpatch.pl script on a series of files (to run periodically during your development for example).

You can also set up GIT to run checkpatch automatically before each commit (and reject it on failure). You need photo recovery to copy the attached script (File:Pre-commit.tar.gz) into your GIT repository under $GIT_DIR/hooks directory (normally as .git/hooks/pre-commit). This script also runs git diff --check, plus as an added benefit it sets file permissions for common files (c, h, makefile, README) to 0644, and executables (directories, shell scripts) to 0755. This is a common issue when editing files in Windows.

If you want to bypass the check (e.g. if the failure is intended), use the -n flag for commit to ignore the checks. Just be sure that you still resolve any failures that were correct, and there really wasn’t a ginger chews better proper way to write your code without checkpatch errors. Now there is a whole set of discussion about the 80 character limit that sometime forces less understandable code (you can read about the pros/cons [1] and find a patch [2] to checkpatch to make this optional) BTW, Linus prefers [3] in many cases to ignore the 80-char-limit warnings.

But wait! You can do even more. Since you are already modifying files, why not run checkpatch on the whole file (and not just on the lines you are changing)? To see if there are any already existing checkpatch errors in the files that you modified, set up these two bash aliases that will run checkpatch on the whole files that are about to be committed (just run ‘chkp’):

alias gitd='git rev-parse --show-cdup'
alias chkp='`gitd`scripts/checkpatch.pl -f `git diff --name-only HEAD | awk -v i=$(gitd) "{print i\\$0}"`'

Note: it is always recommended to run checkpatch.pl with --strict to get better warnings.

[edit] sparse

sparse is a static code analysis tool that shall be run on all source files heading a kernel release.

Luckily, sparse is integrated into the kernel build-system and can be easily invoked.

Example for a single file:

make C=2 drivers/hsi/hsi.o

Example for a complete folder with some filtering on some error messages:

make C=2 drivers/hsi/ 2>&1 | grep -v __cold__

[edit] GIT patch creation

[edit] Useful links:

• http://linux.yyz.us/patch-format.html

Subject: [PATCH $version $n/$total] $subsystem: one-line summary

(keep the one-line summary < 50 chars)

• http://userweb.kernel.org/~akpm/stuff/tpp.txt (Patternity, do’s and don’t, ...)

• Linux Documentation/SubmittingPatches contains detailed info on signed-off, acked-by, maintainer, reviewer, ...

[edit] Build Testing

OMAP has multiple machines and processor support in mainline. One need to ensure that all the OMAP builds are happy and not broken UN-intentionally because of the patch series. - Build with omap2plus_defconfig - Customize omap2plus_defconfig to create a SOC specific .config like OMAP4 only, OMAP3 only, OMAP2 only - You can try few combinations of above as well. - Build omap1_defconfig to ensure that your series doesn't break the build. - If your series is a device driver, then ensure that it builds as a module. - For monkey kind of build testing, Linaro has few random defconfig generation scripts which can be used. - Your series must be git-bisectable. Ensure that after every patch in your series, the builds are continue to work.

[edit] Testing

- All the mentioned confgs in "Build Testing" should boot with your series. Try to test on all the platform you have and if you don't have one, RFT(request for test) on the list for the missing platform - Test your series with PM disabled. It should boot and work. - Test your series functionally and if possible some long duration test, regression test. - Check that System wide supsend continues to work with your series "echo mem > /sys/power/state" - Check the CPUIDLE continues to work with your series. - Try to get your series tested by your peers and colleges for greater confidence.

[edit] GIT setup

Before you do commits to generate patches, ensure you have the right email ID and name configured for git to use.

% git config --global user.name "My Name"
% git config --global user.email ""

Alternatively, edit ~/.gitconfig

 [user]
   name = My Name
   email = 

Also, in order to have a nice thread format:

% git config sendemail.chainreplyto false

if you modify files with windows, samba may change the permission mode of the file. if you want git not to take this into account you can use:

% git config core.filemode false

[edit] GIT commands

Patch files are generated from commits (1 patch per commit).

A typical command for generating patch files looks like this:

git format-patch  master~4..master~2 --cover-letter --numbered -s -o patch-folder/

=> This will generate the diff patches between master~4 and master~2 version (2 patches), plus add some diff information (--cover-letter), add the patch number] in the subject (1/2, 2/2), and output the patch files to the 'patch-folder' folder. Note that a patch 0/0 file will also be created to host a summary of the changes.

scripts/checkpatch.pl can be run on the files in the patch-folder to check (last chance!) that the format is correct.

The patch files must be hand-edited to replace some fields.

[edit] GIT useful helper script

• kmake - useful script to do static build check for common errors prior to posting

[edit] Sending patch emails with GIT

Sending emails can be done through any email client, but it's much easier to do it from git, and it avoids any garbage generated by the email client.

This is supported by git-send-mail module. It can be installed this way:

sudo apt-get install git-email

To follow-up on the above example, here is how to send the previously generated patches:

git send-email --from "My Name <>" --envelope-sender "My Name <>" --to  patch-folder

--from ensures that the email comes from the right person, the --envelope-sender is usually needed for many opensource mailing lists to accept emails(emails bounce/never get distributed otherwise)

NOTE: using an alias is a better option when using this every time:

alias gsend='git send-email --from "My Name <>" --envelope-sender "My Name <>" '

[edit] Useful links

setting-up email forwarding

Documentation/email-clients.txt

GIT send-emails tricks (email threading, cc-cmd, ...)

[edit] Note on git commit comments

You must have seen that the git comments are used to populate the patch file header in the format-patch phase:

• The 1st comment list is used as the patch subject
• The rest of the comment is copied in the patch file comment area

... but pay attention that the comment will be integrated to the email sent by git-send-email only if there is a blank (empty) line between the 1st line comment (used as subject) and the rest of the comment lines.

Example of a commit comment:

This is the 1st line, that will be used as patch subject


This is the 3rd line of comment (intentionally left 2nd line empty so that this part of comments are integrated into the emails).

Suggestions for Commit messages: Commit messages are informative information for reviewers and maintainers. Remember: the patch once submitted has a long way to go through various maintainers and mailing list members before reaching kernel.org. You need to put yourself in the shoes of maintainers and reviewers who may or may not be familiar with all the internal details after a few months of time, but still need to understand the motivation for a change.

A commit message is structured:

1. What is the problem this patch is trying to solve - e.g. why is the existing code not correct
2. The strategy by which this patch attempts to solve the issue - remember people can read code, so giving "introducing variable x solves issue" - instead describe the gist of how you solved the issue
3. What is the impact of the change when there are dependent modules - e.g. if you change an function entry which may be used by others modules you may want to document it here, rather than get the other person discover it when he/she builds their module
4. Optionally, you may state what testing you may have done to ensure the issue is solved.

Some of the above points might be self evident and could be skipped.. but it is usually a good idea to be descriptive enough.Again, it is a fine balance between informative and going overboard, community members and maintainers are usually kind enough to help guide a patch in.

Read this and this for more detailed rationale.