This page describes the step-by-step process to create and submit a patch to the Xilinx open source projects. For people preferring the movie over the book, there is a video tutorial on this topic from Greg Kroah-Hartman on youtube. It's, of course, focused on mainline kernel development, but the general work flows are more or less the same for many git managed projects.

1 The Git Repository
2 Tools and Files Required
3 General Notes
4 Best Practices
5 Steps to Creating a Patch
- 5.1 1. Create a Local Branch
- 5.2 2. Edit & Save Files
- 5.3 3. Specify Email and Name once
- 5.4 4. Add Files
- 5.5 5. Review Changes
- 5.6 6. Commit Files
- 5.7 7. Review the last commit
- 5.8 8. Generate your patch
- 5.9 9. Check your patch for errors:
6 Submit your patch
7 Related Links

The Git Repository

Xilinx maintains a public Git tree at https://github.com/xilinx, for each of its open source projects. The two primary projects covered are Linux and U-Boot.

Tools and Files Required

Install Git
Fetch Sources (Clone the Linux Kernel | U-Boot source )

A detailed explanation of how to Install Git and Fetch Sources with Git, are described in detail in Using Git.

General Notes

Check file permissions and line endings (Use dos2unix for conversion files from Windows to Linux).
The patch should not introduce any new compiler/linker warnings.
If the patch is to change existing code (not a new driver or subsystem) it should be to fix a single issue rather than multiple issues and should not include other format changes
Multiple pages should be a series such that the order of applying them is clear. The git format-patch command creates a series when more than one commit is specified.
Description shouldn't be longer than 50 characters
Add information about git tree/branch you have used under a marker line containing simply "---" (for example: linux-xlnx.git master branch)
If you don't get reaction from maintainer till 3 days, ping him again trough the chat or email. Your work is done when your patches are added to git server

Best Practices

Use Out-of-tree development only for the initial phase and prototyping

You have to keep up with mainline kernel changes yourself which becomes increasingly difficult to maintain
Your patch is unlikely to be included with any linux distribution

Get your driver/patch into the kernel asap once tested

Make small, review-able changes at a time. Avoid big patches.
The driver/patch will automatically be updated for you whenever kernel APIs change.
Back-porting to a previous version is a one-time job for each older kernel
Also gives you long term support
You don't own your code when creating open source software!

Adding APIs:

Post an RFC document on the appropriate linux mailing list
Update, based on feedback, and repeat until you have consensus
Implement changes and document the changes in the main API header
There must be alteast one driver using the new API before API changes are accepted!
Feed changes upstream in small chunks and extend it over time

Feedback:

Staying focused on the technical aspects, ping people for feedback and remain open to constructive criticism
Stay away from flames and personal attacks, and be cognizant of cultural barriers
Take the time to discuss changes
Consider organizing a brainstorming session
Visit conferences such as Embedded Linux Conference, Linux Plumbers Conference
Its all about co-operation!

Steps to Creating a Patch

1. Create a Local Branch

Make a branch ( "<my_change>" in the code below) in the repository for the change you desire which is based on one of the original branches ("<branch base>" in the code below) in the repository you cloned. This command creates the branch and makes it the active branch.

git checkout -b <my_change> <branch base>

2. Edit & Save Files

Make the changes to any files or add new files and do your testing.

3. Specify Email and Name once

Set your email and your name for commit messages. Git creates a .gitconfig file in the directory specified by the HOME environment variable such that this only has to be done once.

git config --global user.email johndoe@example.com
git config --global user.name 'John Doe'

4. Add Files

Add any modified files to your patch.

git add <file>

5. Review Changes

Review the changes that will be committed on the next commit command. In case something is wrong, like adding a wrong file, git status also provides hints on how to resolve issues.

git status

6. Commit Files

Commit the files that were changed and added into your local branch of your local repository. A commit should be done when a change is ready to be put in the repository. Keep the granularity of each commit small (a single functional change) as each commit will become a separate patch.

git commit --signoff

You will be put into an editor to enter your commit message. There is a specific format that should be followed and illustrated below.

In the following text, “[ ]” denotes a required field and “< >” is an optional field.

[system]: [subsystem]: <descriptor>: [short summary]
blank line
Several lines: describing the specifics of the change
blank line
Signed-off-by: [your name] [<youremail@somewhere.com>]

Where:

system = powerpc, microblaze, arm
subsystem = zynq
descriptor = the driver name, BSP, etc…
short summary = a short text summary of the change
Signed-off-by is the person making change (commit). This line is created automatically if the --signoff option is passed to 'git commit' and uses the identity configured in your .gitconfig.

Examine other commit messages to get an idea what may be appropriate values for the commit message fields of your patch.

git log <path>

7. Review the last commit

git show

8. Generate your patch

Generate patches for each commit in your branch. A patch file, named *.patch, is generated in the current directory. The following command generates a patch for each commit your commits.

git format-patch <branch base>

9. Check your patch for errors:

Linux

If the patch is adding or altering any device tree bindings that are specific to Xilinx, the bindings should be changed/added to Documentation/devicetree/bindings/<subsystem>/<xilinx specific file>.
The perl script, checkpatch.pl, located in the scripts directory, should be run on patches. Any warnings or errors should be corrected before patch submission.

U-Boot

The perl script, checkpatch.pl, located in the tools directory, should be run on patches. Any warnings or errors should be corrected before patch submission.

Qemu

The perl script, checkpatch.pl, located in the scripts directory, should be run on patches. Any warnings or errors should be corrected before patch submission.

Submit your patch

Send the email patch to git@amd.com for review and incorporation back into the Git tree. Using Git to send the email will ensure that it’s format is not altered by email clients such as Outlook.

git send-email --to git@amd.com *.patch

Create and Submit a Patch

Table of Contents