Describe Touch/BluetoothEnablement/NewBackportsPatch here.

How to backport the kernel side Bluetooth stack to an older kernel

This document describes the steps necessary for backporting the BlueZ from the recent kernel into an older one as used by Ubuntu Touch devices.

The best way to do it is to use the Kernel Backports project https://backports.wiki.kernel.org/index.php/Main_Page which almost automatically takes care of all the effort leaving a single commit at the end that contains all the required changes. It is important to know, however, that this project is developed on a slower pace and as for now [June 2016] it fully supports kernel 4.2, has a limited support for kernel 4.6 and there is no support for kernel 4.7-rc3. This means that manual tweaks are needed in order to backport anything which is newer than v4.2

The backports project know-how

The backports project offers a set of scripts that together provide a complete solution. The result of their execution is the complete commit which contains all of the backported code in it. This means that for the standard use cases the backports project is super easy to use.

This, for example may look like:

./backports/gentree.py --copy-list ./backports/copy-list --integrate --clean --git-revision v4.6 kernel/linux-upstream /home/konrad/work/m10-src-code/kernel-3.10

The mentioned scripts are:

Now, in order to limit the amount of the code which is backported one should edit the copy-list script and tweak it to the needs and requirements.

Using the backports project with Ubuntu Touch devices tree

The Ubuntu Touch devices kernel trees such as the BQ Aquaris tablet tree do have already a backported code in place. Also we do not want to backport anything else than the Bluetooth part of the newer kernels. These are the constraints and requirements on our side and in order to fulfill them the backports project itself has to be slightly modified.

There are three patches to the backports project that shall be applied in order to reflect Ubuntu Touch needs. These do change the backports integration code a bit and also alter the copy-list script dropping the pieces that are not wanted to be backported.

[TODO: LINK TO THE PATCHES]

It is also important to know that if the target tree has a backported code in it already it will be hard overwritten by the gentree.py script and lost. Moreover, the gentree.py script will double edit the top-level Kconfig file adding the 2nd sourcing of the backports/Kconfig there. These issues will have to be addressed as otherwise it will not be possible to build successfully.

Detailed steps

Prerequisite

1. Checkout the backports repository git://git.kernel.org/pub/scm/linux/kernel/git/backports/backports.git

2. Clone the Linux kernel upstream and checkout the tag that shall be used as a source in the backporting operation.

3. Checkout the device tree that is going to be updated. It is a good idea [however not necessary] to create a separate branch for the backporting work in the device’s kernel repo. Make sure that the branch is clean, i.e. git status returns nothing.

Backporting to device tree

This is a list of steps that are required in order to complete the backporting operation. These do assume that the target tree [the Ubuntu Touch device kernel tree] has already a backported code in it. This means that for the trees without backported code in them some of the steps will not be valid and there will be less conflicts.

4. Apply the patches to the backports repository. It is best to do using 3-way-merge so that there is an easy way of resolving merge conflicts if any.

5. Perform the backporting using the ./gentree.py script. Note that there might be conflicts or errors and such will have to be addressed manually. For the kernel v4.6 the merge conflict appears on the last stage for the top-level Makefile and can be ignored as all of the necessary code is already there, however the gentree.py is interrupted and the commit will have to be done manually - not yet thouhg.

6. Edit the top-level Kconfig and remove the double lines, namely the sourcing of the backports/Kconfig.

7. Add the untracked and modified files [make sure to remove the Makefile.rej that has been created for a merge conflict in step 5-th - it is not needed anymore] to the repository and make a commit. Now, this huge blob contains the whole backport.

8. Importing code from a newer kernel version introduces additional kernel config options, namely the option that tell which backported version shall be used. There are two major places where these has to be added which can be found by running a clever find such as: $ find -type f -exec grep BACKPORT_KERNEL_4_ {} +

• In short this is:
  1. Default kernel configs located in arch/arm64/config need CONFIG_BACKPORT_KERNEL_4_6=y line.
  2. The backports/Kconfig needs config BACKPORT_KERNEL_4_6 “switch” case to be added.
  3. Update the BACKPORT_VERSION and BACKPORT_KERNEL_VERSION in each of the kernel configs located in arch/arm64/config directory. The correct new version tag can be fetched from backports/Kconfig file.

9. The next step is to make sure that any of the changes that has been previously made to the stuff under backports directory are not lost with the importing the new backport operation. This is done by reordering commits using the git interactive rebase feature. Simply put the commit from 7-th step just after the previous backports commit so that any other commit that happen in between is applied after it.

Example

• ./backports/gentree.py --copy-list ./backports/copy-list --integrate --clean --git-revision v4.6 kernel/linux-upstream /home/konrad/work/m10-src-code/kernel-3.10