Linux sources

Introduction

Getting Linux sources for boards used at our department requires these steps:

Getting vanilla Linux sources
Applying several patches to these sources

The reason for providing the patches separately is that for many users it is important to know which patches were applied to the kernel they are using. The maintenance of the additional patches is not an easy task as these patches evolve in time. They are either being ported to newer Linux versions or being updated for other readons.

To maintain the patches we have decided to use the tool TopGit. This page describes how this tool is used for our Linux sources.

TopGit overview

TopGit is a tool manage patches as so called topic branches in Git repositories. Every patch is represented by one branch. The history of patch evolution is tracked on that branch. As some patches might depend on other patches, TopGit also manages these dependencies.

For more information check the TopGit README.

Linux repositories

We maintain the following Linux repositories:

Shark 5200

Layout

Our Linux repositories have the following branches:

vanilla: Tracks vanilla linux sources.
patch/*: Topic branches for individual patches. These branches are managed using TopGit.
<board>/<version>: Branch with TopGit patches exported as plain git commits.
HEAD: Symbolic reference to <board>/<version> branch we consider as stable.

Managing TopGit patches

Cloning a TopGit managed repository

git clone <some-url/linux.git>
cd linux
git branch vanilla origin/vanilla
tg remote --populate origin

Updating patches

git checkout vanilla
git pull git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git tag v2.6.29-rc1
tg summary  # patches marked by 'D' must be updated
git checkout patch/...
tg update
...

Exporting patches

To make accessing kernel sources easier for users who just want the sources for the board they use, we provide branches witch all the needed patches exported from TopGit.

git checkout patch/<last patch>
tg export shark/<version>

This creates branch shark/<version> with current vanilla sources and all patches that depend on patch/<last patch> applied on it.

Porting patches to -stable linux version

Most patches are based against vanilla branch. Therefore tg update updates the patches against newer vanilla sources. Stable kernels (2.6.x.y) are maintained as separate branches and for that reason TopGit wont do the update for us.

I use the following commands to prepare a version based on 2.6.26.5 assuming that vanilla is at 2.6.26

tg export tmp
git rebase v2.6.26.5 tmp
git branch -m tmp shark/2.6.26.5

Updating branch with exported patches

When you change some patch, you may want to update the branch with exporte patches (e.g. shark/2.6.28.8). The simplest solution is to delete that branch and reexport it again. The drawback of this solution is that uses of the exported branch cannot pull your changes without manually merging it. It is therefore preferred to do the merge locally and push the result of merge.

# Prepare the new branch as in the previous section
tg export updated-patches
git rebase v2.6.28.8 updated-patches
# Merge the result to the existing branch
git checkout shark/2.6.28.8
git merge updated-patches
git branch -d updated-patches   # delete the temporary branch

Developing a new patch

Based on martin f. krafft's HOWTO-tg2quilt.

If you want to develop a new feature (or bug fix), first choose the base for it. It will be wither vanilla or patch/<something> if the patch depends on another patch.

The following are the steps required to add a feature branch/patch:

tg create patch/new-feature vanilla

- or -

tg create patch/new-stuff patch/<sometging>

Edit .topmsg and make the subject line be a short description, optionally add a longer description to the body
```
git add .topmsg && git commit
```
Edit files of your patch.

Viewing patch history

git log --first-parent

Thank to --first-parent option, only changes made to the topic branch are displayed and not the changes of merged-in branches (upstream).