This page describe how to use Git rebase patch branches for Xilinx open source components such as Linux, U-Boot, Xen, and QEMU.

Table of Contents

Understanding How Git Manages Commits

The primary reason that software engineers use a source code management system such as Git is to track changes over time and, specifically, to be able to track those changes and understand how each individual patch impacts the codebase.

In code managed with Git, there are two fundamental ways of tracking a commit history.

1. Merge - In this method, a central code history is established over time with changes occurring in branches and then merged back into the central code history at the point of the branch. The effects of the merge are represented as a result of both the main trunk as well as the branches. When looking at the history of the commits in the repository, one must take into account changes that happened prior to C6 in both the branch as well as the main trunk. The merge point (C6 in the figure below) is a special type of event in that it points to both C4 and C5 as its ancestors. This process uses the git merge command.

   Open

   

    

2. Rebase - In this method, a central code history is established over time with changes occurring in branches and then applied to the central code history in such a way that the commit history appears continuous. In the example below, the commits which happen in C4 are replayed or “rebased” directly onto C3 producing a new inline commit C4'. Then, the pointer for master is moved forward in time to align with experiment/C4'.
   
   

   Open

   

   The net effect of merging versus rebasing is equivalent. The code is functionally the same and builds in the same way. The primary reason to choose the rebase strategy over a merge strategy is as follows:

• To simplify the review of the code commit history.

• To facilitate importing code developed outside of the primary development tree but making it appear “native” to the commit history.

How Xilinx Publishes Code

Xilinx publishes the code for all open source projects such as Linux, U-Boot, QEMU, and Xen Hypervisor as standard merge-based repositories on the public Xilinx GitHub located at https://github.com/xilinx .

Note that some repositories – such as Linux – provide the rebase-optimized code as a separate branch and others – such as Xen – optimize the code for rebase in the master branch.

Usage Models for the Xilinx Rebase Patches

Common scenarios where it might be preferable to use the Xilinx rebase patches rather than the standard merge-based tree are:

1. Your organization already maintains a private development tree and you only need Xilinx-specific patches

2. Your organization has a policy in which content is cloned directly from the open source upstream location and you need to apply vendor-specific patches

How to Use the Xilinx Rebase Patches

To get started, first clone a copy of the Xilinx repository. In this example, use the Xilinx Linux tree.

git clone

This will clone all of the Xilinx Linux repository, including all branches. The standard repository is a standard merge-based repository that interleaves Xilinx commits in the same commit history with commits that come from upstream contributors.

In order to extract only the Xilinx commits for the release, use the appropriate rebase branch for the release you are interested in.

For example, to switch to the xlnx_rebase_v5.4 branch use the command

git checkout -b xlnx_rebase_v5.4

After switching to the rebase branch, all of the Xilinx-generated commits will appear at the top of the commit history for the version in question (in this example, v5.4). This is done on purpose to make it easy to locate them all. Look through the Git commit history inside the appropriate rebase branch using the git log command and locate the first non-Xilinx commit (rather than just the first non-Xilinx author). It’s important to note that there may be several pages of history to go through. This process can be expedited by using special formatting with the git log command to limit the amount of output.

Next, fetch the tags from the upstream Linux kernel source tree (eg, Linus Torvalds' tree).

git fetch --tags https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

This will download only the tags that correspond to the differences between the upstream tree and the Xilinx branch.

Generating Rebase Patch Files

One option for utilizing the rebase patches – especially if they need to be archived or audited – is to generate the patch files directly.

This can be done by using the git format-patch command.

git format-patch <upstream-linux-version>

For example, if you are generating patches for the Linux v5.4 kernel to apply against the Xilinx xlnx_rebase_v5.4 branch, the syntax is:

git format-patch v5.4

If you require generation of patch files only for a specific range of commits, the syntax is similar but requires specifying both the start and end commits in the range.

git format-patch <older_commit>..<newer_commit>

Note the use of the .. syntax as it is required to properly specify the range of commits to include.

Applying the Rebase Patches Directly

Alternatively, if you wish to apply the Git rebase patches directly into the Linux tree, you can use the Git rebase command to rebase the patches. This method aligns with a traditional rebase process and requires more interaction from the patch integrator. That is, it is possible that there may be conflicts between some commits and the upstream state of the source code repository. The interactive rebase process requires that the developer performing the integrating take an active role in determining which patches are and are not appropriate.

To use this method, use the command git rebase to get started:

git rebase -i <upstream_linux_version>

For example, if you are generating patches for the Linux v5.4 kernel to apply against the Xilinx xlnx_rebase_v5.4 branch, the syntax is:

git rebase -i v5.4

In some cases, certain patches may not integrate easily with your existing code base and will require modification/adaptation before they can be utilized. In these cases, the git rebase command can be used with the --continue or --abort flags to control how to handle these situations. For more information on these scenarios, please consult the official Git documentation at https://git-scm.com/docs/git-rebase.

Related Links

• Official Git SCM Documentation - Basic Branching and Merging - https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merging

• Official Git SCM Rebasing - https://git-scm.com/book/en/v2/Git-Branching-Rebasing

• Some original source images adapted from Git-SCM.com Pro Git book, used under the Creative Commons CC-BY-NC-SA license. (https://creativecommons.org/licenses/by-nc-sa/3.0/)