Create and Submit a Patch

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.



Table of Contents

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

  1. Install Git
  2. 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

  1. Check file permissions and line endings (Use dos2unix for conversion files from Windows to Linux).
  2. The patch should not introduce any new compiler/linker warnings.
  3. 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
  4. 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.
  5. Description shouldn't be longer than 50 characters
  6. Add information about git tree/branch you have used under a marker line containing simply "---" (for example: linux-xlnx.git master branch)
  7. 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.
  1. [system]: [subsystem]: <descriptor>: [short summary]
  2. blank line
  3. Several lines: describing the specifics of the change
  4. blank line
  5. 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
  1. 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>.
  2. 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
  1. 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
  1. 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

https://www.kernel.org/doc/Documentation/SubmittingPatches
https://www.kernel.org/doc/Documentation/SubmitChecklist
https://www.kernel.org/doc/Documentation/email-clients.txt
Video tutorial by Greg Kroah-Hartman (youtube)

© Copyright 2019 - 2022 Xilinx Inc. Privacy Policy