From 35045cdb6b456262baa552a7e967e2fc8f1c0724 Mon Sep 17 00:00:00 2001 From: Rolf Neugebauer Date: Wed, 26 Apr 2017 17:54:30 +0100 Subject: [PATCH] docs: Update kernel documentation Signed-off-by: Rolf Neugebauer --- docs/kernels.md | 50 ++++++++++++++++++++++++++++++++++-------------- kernel/README.md | 11 ++--------- 2 files changed, 38 insertions(+), 23 deletions(-) diff --git a/docs/kernels.md b/docs/kernels.md index eb4bb77c3..09136e9ef 100644 --- a/docs/kernels.md +++ b/docs/kernels.md @@ -1,4 +1,22 @@ -# Working with Linux kernel patches for LinuxKit +# LinuxKit kernels + +Currently, LinuxKit supports a number of kernels. These kernels are +typically based on the latest stable releases and are updated +frequently to include bug and security fixes. For some kernels we do +carry some additional patches, which are mostly back-ported fixes from +newer kernels. The full kernel source with patches is on +[github](https://github.com/linuxkit/linux). + +The kernel images are stored on Hub under +[linuxkit/kernel](https://hub.docker.com/r/linuxkit/kernel/). Each +kernel image is tagged with the full kernel version plus the hash of +the files it was created from (git tree hash of the `./kernel` +directory). For convenience, the latest kernel of each stable series +is also available under the a shorthand tag, +e.g. `linuxkit/kernel:4.9.x` for the latest `4.9` kernel. + + +## Working with Linux kernel patches for LinuxKit We may apply patches to the Linux kernel used in LinuxKit, primarily to cherry-pick some upstream patches or to add some additional @@ -12,10 +30,13 @@ Patches are located in `kernel/patches-` and should follow these which they are applied. - If patches are cherry-picked, they *must* be cherry-picked with `-x` to contain the original commit ID. +- If patches are from a different git tree (other than the stable + tree), or from a mailing list posting they should contain an + `Origin:` line with a link to the source. This document outlines the recommended procedure to handle patches. The general process is to apply them to a branch of the -[Linux stable tree](https://kernel.googlesource.com/pub/scm/linux/kernel/git/stable/linux-stable/) +[Linux stable tree](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/) and then export them with `git format-patch`. If you want to add or remove patches currently used, please also ping @@ -24,12 +45,13 @@ ensure that patches are carried forward if we update the kernel in the future. -# Preparation +### Preparation Patches are applied to point releases of the linux stable tree. You need an up-to-date copy of that tree: ```sh git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git ``` +Add it as a remote to a clone of the [LinuxKit clone](https://github.com/linuxkit/linux). We use the following variables: - `KITSRC`: Base directory of LinuxKit repository @@ -42,7 +64,7 @@ LINUXSRC=~/src/linuxkit/linux to refer to the location of the LinuxKit and Linux kernel trees. -# Updating the patches to a new kernel version +### Updating the patches to a new kernel version There are different ways to do this, but we recommend applying the patches to the current version and then rebase to the new version. We define the following variables to refer to the current base tag and the new tag you want to rebase the patches to: ```sh @@ -53,24 +75,24 @@ NEWTAG=v4.9.15 If you don't already have a branch, it's best to import the current patch set and then rebase: ```sh cd $LINUXSRC -git checkout -b ${NEWTAG}-moby ${CURTAG} +git checkout -b ${NEWTAG}-linuxkit ${CURTAG} git am ${KITSRC}/kernel/patches/*.patch -git rebase ${NEWTAG}-moby ${NEWTAG} +git rebase ${NEWTAG}-linuxkit ${NEWTAG} ``` The `git am` should not have any conflicts and if the rebase has conflicts resolve them, then `git add ` and `git rebase --continue`. -If you already have linux tree with a `${CURTAG}-moby` branch, you can rebase by creating a new branch from the current branch and then rebase: +If you already have linux tree with a `${CURTAG}-linuxkit` branch, you can rebase by creating a new branch from the current branch and then rebase: ```sh cd $LINUXSRC -git checkout ${CURTAG}-moby -git branch ${NEWTAG}-moby ${CURTAG}-moby -git rebase --onto ${NEWTAG} ${NEWTAG} ${NEWTAG}-moby +git checkout ${CURTAG}-linuxkit +git branch ${NEWTAG}-linuxkit ${CURTAG}-linuxkit +git rebase --onto ${NEWTAG} ${NEWTAG} ${NEWTAG}-linuxkit ``` Again, resolve any conflicts as described above. -# Adding/Removing patches +### Adding/Removing patches If you want to add or remove patches make sure you have an up-to-date branch with the currently applied patches (see above). Then either any normal means (`git cherry-pick -x`, `git am`, or `git commit`, etc) to add new patches. For cherry-picked patches also please add a `Origin:` line after the DCO lines with a reference the git tree the patch was cherry-picked from. @@ -82,13 +104,13 @@ DCO lines, e.g.: Origin: https://patchwork.ozlabs.org/patch/622404/ ``` -# Export patches to LinuxKit +### Export patches to LinuxKit To export patches to LinuxKit, you should use `git format-patch` from the Linux tree, e.g., something along these lines: ```sh cd $LINUXSRC -rm $KITSRC/kernel/patches-4.9/* -git format-patch -o $KITSRC/kernel/patches-4.9 v4.9.15..HEAD +rm $KITSRC/kernel/patches-4.9.x/* +git format-patch -o $KITSRC/kernel/patches-4.9.x v4.9.15..HEAD ``` The, create a PR for LinuxKit. diff --git a/kernel/README.md b/kernel/README.md index a40429e96..cc2cb080d 100644 --- a/kernel/README.md +++ b/kernel/README.md @@ -1,12 +1,5 @@ -Linux kernel builds, based on mostly-vanilla upstream Linux kernels. -See [../docs/kernel-patches.md](../docs/kernel-patches.md) for how the local patches in `patches-*` -are maintained. - -The build is mostly silent. A local build can be run via `make`. To view -the output use `docker log -f `. The build creates multiple -containers, so multiple invocations may be necessary. To view the full build -output one may also invoke `docker build .` and then copy the build artefacts -from the image afterwards. +See [../docs/kernel-patches.md](../docs/kernels.md) for more +information on kernel builds. To build with various debug options enabled, build the kernel with `make DEBUG=1`. The options enabled are listed in `kernel_config.debug`.