diff --git a/docs/conf.py b/docs/conf.py index aac9423..e5a82ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -201,6 +201,7 @@ r"https://github\.com/.*", r"https://ubuntu.com/about/release-cycle", r"https://snapcraft.io/docs/", + r"https://canonical-kteam-docs.readthedocs-hosted.com/en/latest/how-to/new_starter/newstarter.html", ] @@ -214,7 +215,10 @@ # NOTE: By default, the following MyST extensions are enabled: # substitution, deflist, linkify -# myst_enable_extensions = set() +myst_enable_extensions = { + "colon_fence", + "substitution", +} # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html diff --git a/docs/how-to/cranking/set-up-cranky-environment.md b/docs/how-to/cranking/set-up-cranky-environment.md new file mode 100644 index 0000000..9d44f4e --- /dev/null +++ b/docs/how-to/cranking/set-up-cranky-environment.md @@ -0,0 +1,71 @@ +# How to set up cranky environment + +This guide describes the one-off process to configure your build environment to +crank Ubuntu kernels using `cranky`. + +## Install dependencies + +First, you will need to install the required packages. + +### Debian packages + +Use apt to install the following debian packages: + +```{code-block} text +sudo apt install \ + bash-completion \ + build-essential \ + ccache \ + debhelper \ + devscripts \ + docbook-utils \ + fakeroot \ + gawk \ + git \ + git-email \ + kernel-wedge \ + libncurses5-dev \ + makedumpfile \ + python3-git \ + python3-launchpadlib \ + python3-requests \ + python3-ruamel.yaml \ + schroot \ + sharutils \ + transfig \ + ubuntu-dev-tools \ + wget \ + xmlto +``` + +### Snapcraft package + +Install snapcraft according to the Ubuntu release running on your build machine. + +```{tip} +You can check your release of Ubuntu by running `lsb_release -a`. +``` + +`````{tab-set} +````{tab-item} 24.04 LTS (Noble Numbat) or later + +Install `snapcraft` using snap: + +```{code-block} text +snap install snapcraft --classic +``` +```` + +````{tab-item} 22.04 LTS (Jammy Jellyfish) or earlier + +Install `snapcraft` using apt: + +```{code-block} text +sudo apt install snapcraft +``` +```` + +````` + + + diff --git a/docs/how-to/index.md b/docs/how-to/index.md index ba070ef..bf5c944 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -10,6 +10,7 @@ kernel packages and components. Source code access and management Development and customization +Set up cranky environment Test kernels in -proposed Contribute to kernel docs ``` @@ -22,6 +23,14 @@ tree to build custom kernel modules, and more. - [Obtain kernel source for an Ubuntu release using Git](/how-to/source-code/obtain-kernel-source-git) +## Cranking kernels + +In Canonical, "kernel cranking" refers to the process of applying patches and +updates to an Ubuntu kernel, packaging it, and getting it ready for testing -- +all done using the `cranky` toolchain. + +- [Set up cranky environment](/how-to/cranking/set-up-cranky-environment) + ## Development and customization The steps to build a kernel is similar but may have slightly difference diff --git a/docs/index.md b/docs/index.md index 672507a..4f8c8c8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,10 +25,10 @@ processes for customization and maintenance. ````{grid} 1 1 2 2 -```{grid-item-card} [Tutorials](index) +```{grid-item-card} [Tutorials](/tutorial/index) **Start here**: a hands-on introduction to Ubuntu Linux kernel development for -new users +new users. ``` ```{grid-item-card} [How-to guides](/how-to/index) @@ -73,6 +73,7 @@ fixes and constructive feedback. :hidden: :maxdepth: 2 +/tutorial/index /how-to/index /reference/index /explanation/index diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 8d06c18..86ed161 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -38,8 +38,7 @@ HWE linux-meta Refers to a set of meta-packages in Linux distributions like Ubuntu. These meta-packages do not contain the kernel binaries or source code themselves but - instead define dependencies that point - to the latest kernel packages. + instead define dependencies that point to the latest kernel packages. By installing a linux-meta package (e.g. linux-generic), users can ensure they always receive the latest version of a specific kernel series through updates. In the kernel development and {term}`SRU` life cycle, linux-meta acts as a @@ -47,7 +46,7 @@ linux-meta When a new kernel version is released and marked stable, the linux-meta package is updated to reference the new version, allowing automatic upgrades. -linux-signed +linux-signed Refers to kernel packages that are cryptographically signed to ensure their integrity and authenticity. These signatures are crucial for secure boot environments, as they enable the diff --git a/docs/tutorial/crank-your-first-kernel.md b/docs/tutorial/crank-your-first-kernel.md new file mode 100644 index 0000000..6bd441f --- /dev/null +++ b/docs/tutorial/crank-your-first-kernel.md @@ -0,0 +1,554 @@ +# Tutorial: Crank your first kernel + +Cranking an Ubuntu kernel is the process of applying patches and updates to an existing Ubuntu kernel, packaging it, and preparing it for testing. +All this is done using the [cranky](https://kernel.ubuntu.com/gitea/kernel/kteam-tools/src/branch/master/cranky) toolchain. + +In this tutorial, we will crank a 24.04 LTS (Noble Numbat) (codename `noble`) Google cloud kernel (codename `linux-gke`) from the "s2024.12.02" cycle. + +```{tip} + Keep these codenames and cycle name handy for future commands. +``` + +## Prerequisites + +You will need to complete the prerequisite setup below before proceeding with the tutorial: + +- {doc}`Set up your cranky environment ` +- Set up your [VPN connection] +- Get access to [Kernel team build resources] + +## Set up and update build environment + +First, we will prepare our build environment and tooling needed for cranking a kernel. + +### Update kteam-tools repository + +Update your local clone of `kteam-tools` to the latest commit on the `master` branch: + +```{warning} +If your `kteam-tools` tree isn't clean, be sure to save your work before running the commands as this step will modify the repository. +Git should warn you if any destructive actions might occur. +``` + +```bash +cd ~/canonical/kteam-tools/ +git switch master +git pull +``` + +Once the command completes successfully, you've got the latest version of cranky. + +### Update chroot environment - `cranky chroot` + +We use [chroot](https://en.wikipedia.org/wiki/Chroot) environments to isolate different sets of tools when doing kernel cranking. +`cranky` helps us set up and manage these chroot jails. + +Creating the chroot jail is done in two steps. First, create the chroot base: + +```bash +cranky chroot create-base noble:linux-gke +``` + +This can take several minutes to complete. +If successful, you should observe the various packages being installed and set up in the terminal output. + +Next, create the chroot session: + +```bash +cranky chroot create-session noble:linux-gke +``` + +This step uses APT to install various packages needed for the crank and may take several minutes to complete. + +## Download kernel sources - `cranky checkout` + +You're now ready to clone the `linux-gke` kernel for the given cycle (e.g. "s2024.12.02"). + +```bash +cranky checkout noble:linux-gke --cycle s2024.12.02 +``` + +This command can take several minutes to complete. + +If the command completes successfully, you should see the following new directory: `~/canonical/kernel/ubuntu/noble/linux-gke/`. + +Inside, there should be three git repositories cloned: `linux-main`, `linux-meta`, and `linux-signed`. + +For more information, see {term}`linux-meta` and {term}`linux-signed` in the glossary. + +## Apply updates from upstream kernel + +The upstream kernel will possibly have changes that should be propagated down to this kernel. + +### Fix helper scripts - `cranky fix` + +Update the local (in-tree) helper scripts cranky uses to the latest version: + +```bash +cd ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main/ +cranky fix +``` + +You should see that cranky executed several scripts and go through the updating process for various scripts in the output terminal. + +### Rebase on top of parent kernel - `cranky rebase` + +As `linux-gke` is a derivative kernel, we need to apply updates from its parent, the generic kernel in Noble. + +First, add the parent repository as a remote: + +```bash +git remote add parent "git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/noble" +``` + +Pull the tag for the kernel version we want to rebase on: + +```bash +git fetch parent --no-tags tag Ubuntu-6.8.0-53.55 +``` + +Then rebase to inherit the changes from a specific version of the parent kernel: + +```bash +cranky rebase -l Ubuntu-6.8.0-53.55 +``` + +```{tip} +For non-derivative kernels (e.g., `noble:linux`), this step is not required. +``` + +You should observe something similar in the output terminal: + +```{terminal} +:input: cranky rebase -l Ubuntu-6.8.0-53.55 +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +Rebase still needed between Ubuntu-6.8.0-52.53 and Ubuntu-6.8.0-53.55. +II: record=/home/annecyh/canonical/kernel/ubuntu/noble/linux-gke/linux-main/.git/REBASE-SELECTOR +Successfully rebased and updated refs/heads/cranky/master-next-s2024.12.02. +``` + +### Fix helper scripts (again) - `cranky fix` + +Sometimes after a `cranky rebase`, the helper scripts get updated. +It's good practice to always re-run: + +```bash +cranky fix +``` + +## Commit and review updates + +Now that we've pulled in all the upstream changes, we are ready to review and apply the commits to the `linux-gke` kernel. + +### Add starting commit - `cranky open` + +Create a commit that signifies the start of a new release. +This new commit will contain {term}`ABI` changes and any customization required by backport kernels. + +```bash +cranky open +``` + +You should observe something similar in the output terminal: + +```{terminal} +:input: cranky open +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +[...] +/home/kernel-engineer/canonical/kteam-tools/cranky/cranky startnewrelease --commit +Creating new changelog set for 6.8.0-1018.22... +[cranky/master-next-s2024.12.02 911b0ad106e9] UBUNTU: Start new release + 1 file changed, 8 insertions(+) + + +***** Now please inspect the commit before pushing ***** +``` + +Run `git show` to verify that this new commit starts with "UBUNTU: Start new release" and shows an update to {file}`./debian.gke/changelog`. + +```{terminal} +:input: git show +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +Author: kernel-engineer +Date: Mon Jan 20 16:55:52 2025 +0800 + + UBUNTU: Start new release + + Ignore: yes + Signed-off-by: kernel-engineer + +diff --git a/debian.gke/changelog b/debian.gke/changelog +[...] +``` + +### Review rebased changes - `cranky review-master-changes` + +Sometimes the rebase doesn't get all the changes. +So we need to run this command to manually review any outstanding changes: + +```bash +cranky review-master-changes +``` + +This command will output any outstanding changes in a list with their commit hashes and descriptions. +Use `git show ` to view the changes. + +```{terminal} +:input: cranky review-master-changes +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +Listing changes in "debian.master/" since 9f8080a647a9e2c8c9a52b3e471b3f22d4dc0c67... + +f31315007228 UBUNTU: [Packaging] debian.master/dkms-versions -- update from kernel-versions (main/2025.01.13) +3a8a3b4039e7 UBUNTU: [Packaging] do not attempt to generate BTF header on armhf +59e4c08ecd84 UBUNTU: Upstream stable to v6.6.55, v6.10.14 +fadfbbcc2798 UBUNTU: [Config] updateconfigs for MICROSOFT_MANA +b5bd2549a589 UBUNTU: [Config] updateconfigs for deprecated CONFIG_Z3FOLD +1878fd662392 UBUNTU: [Config] updateconfigs to set ILLEGAL_POINTER_VALUE for riscv64 +267522e21042 UBUNTU: [Config] updateconfigs to select PROC_MEM_ALWAYS_FORCE +366c11c3240e UBUNTU: [Packaging] Add list of used source files to buildinfo package +6b86533cc3d1 UBUNTU: [Packaging] Sort build dependencies alphabetically +52051394e234 UBUNTU: Upstream stable to v6.6.54, v6.10.13 +763dd57e5520 UBUNTU: [Config] update configs for CONFIG_CRYPTO_AES_GCM_P10 +db4045cf4e9a UBUNTU: Upstream stable to v6.6.53, v6.10.12 +``` + + +Since there are commits that have kernel config changes (e.g. commits with the "UBUNTU: [Config]" prefix), this will require an additional commit from our side. +We will address this in the `cranky close` step a little later. + +### Link to Launchpad bug tracker - `cranky link-tb` + +Run the following command to update the corresponding Launchpad tracking bug to this new kernel version being created. + +```{warning} +Use `--dry-run` unless you are actually cranking a kernel. +Otherwise, this will overwrite Launchpad and might make destructive changes! +``` + +```bash +cranky link-tb --dry-run +``` + +```{tip} +If you are running `cranky link-tb` for the first time, you will be directed to the "Authorize application to access Launchpad on your behalf" page. +Choose your preferred option before continuing. +``` + +This step should update the Launchpad tracking bug -- which, among other things, will be used as an input for subsequent steps -- and create a git commit. + +But since we used the `--dry-run` option for this tutorial, no changes are made to the local tree and no commit is created. + +```{terminal} +:input: cranky link-tb --dry-run +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +(This is a dry-run) +LP: #2097956 (noble/linux-gke: -proposed tracker) s2025.01.13-1 +Dry Run -- no changes made +``` + +### Update DKMS packages - `cranky update-dkms-versions` + +The `debian.master/dkms-versions` file specifies dkms modules to be packaged with its kernel. +This command updates the package versions in `debian.gke/dkms-versions` to match the ones expected for the SRU cycle. + +```bash +cranky update-dkms-versions +``` + +Since no changes are needed at this time, you should observe the following output: + +```{terminal} +:input: cranky update-dkms-versions +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +[...] + +debian.gke/dkms-versions: No changes from kernel-versions +``` + +```{tip} +In most cases, no changes are expected as the up-to-date DKMS versions should have been committed on the generic kernel and picked up by the derivative or backport on rebase. +``` + +### Add closing commit - `cranky close` + +We will now create one final commit before preparing a release by running: + +```bash +cranky close +``` + +This command, among several other things, closes the changelog, verifies changes are handled properly, +and makes a new commit signifying the cranked kernel. + +Since there are config-related changes, `cranky close` is expected fail at this point. +You should observe a similar error in the terminal output stating that there were changes in `debian.gke/config/annotations`. + +```{terminal} +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) +:input: cranky close +:user: kernel-engineer +:host: ubuntu-machine + +[...] + +* Run config-check for arm64-gke ... +check-config: loading annotations from debian.gke/config/annotations +check-config: CONFIG_NVME_KEYRING changed from m to y: policy<{'amd64': 'm', 'arm64': 'm', 'armhf': 'm', 'ppc64el': 'm', 'riscv64': 'm', 's390x': 'm'}>) +check-config: 1 config options have been changed, review them with `git diff` +ERROR: 2 config-check failures detected + +Importing all configurations ... + +* Import configs for amd64-gke ... +* Import configs for arm64-gke ... +make: *** [debian/rules.d/1-maintainer.mk:31: updateconfigs] Error 1 +Script failed +ERROR: Command failed: chroot (args=['run', '--', 'fakeroot', 'debian/rules', 'clean', 'updateconfigs']) +ERROR: Command failed: fdr (args=['clean', 'updateconfigs']) +ERROR: Command failed: close (args=[]) +``` + +```{note} +If there were no unreviewed changes, skip ahead to the next section. +``` + +We will need to manually review and commit these changes with a descriptive +message of the updated config: + +```bash +git add debian.gke/config/annotations +git commit -m "UBUNTU [Config] gke: Update configs from 6.8.0-53.55" -m "Ignore: yes" -s +``` + +Finally, re-run `cranky close`. + +```bash +cranky close +``` + +If successful, you should see a new commit when you run `git show`: + +```diff +commit 6c9a5055b22f4c30aa3ba0c9df306762edb29197 (HEAD -> cranky/master-next-s2024.12.02) +Author: Kernel Engineer +Date: Wed Feb 12 13:49:40 2025 +0800 + + UBUNTU: Ubuntu-gke-6.8.0-1018.22 + + Signed-off-by: Kernel Engineer + +diff --git a/debian.gke/changelog b/debian.gke/changelog +index fd056a9e15cc..fd8c8d9cd8fb 100644 +--- a/debian.gke/changelog ++++ b/debian.gke/changelog +@@ -1,10 +1,1229 @@ +-linux-gke (6.8.0-1018.22) UNRELEASED; urgency=medium ++linux-gke (6.8.0-1018.22) noble; urgency=medium + +- CHANGELOG: Do not edit directly. Autogenerated at release. +- CHANGELOG: Use the printchanges target to see the curent changes. +- CHANGELOG: Use the insertchanges target to create the final log. ++ [ Ubuntu: 6.8.0-53.55 ] + +- -- Kernel Engineer Wed, 12 Feb 2025 12:43:08 +0800 ++ * noble/linux: 6.8.0-53.55 -proposed tracker (LP: #2093677) ++ * Packaging resync (LP: #1786013) ++ - [Packaging] debian.master/dkms-versions -- update from kernel-versions ++ (main/2025.01.13) +[...] + ++ -- Kernel Engineer Wed, 12 Feb 2025 13:49:40 +0800 + + linux-gke (6.8.0-1017.21) noble; urgency=medium +``` + +## Verify the kernel builds successfully + +Now that our local `linux-gke` kernel source tree has been updated, we should test that it builds successfully. + +### Build kernel in CBD + +For Canonical users, we can use the cloud builder system (CBD) for this purpose. + +Connect to the Canonical VPN and run: + +```bash +git remote add cbd cbd.kernel:noble.git +git push cbd +``` + +The output will initially look like this: + +```{code-block} +:emphasize-lines: 4 + +Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 +remote: *** kernel-cbd ********************************************************* +remote: * Queueing builds (your 'cranky/master-next'); ok to interrupt +remote: * For results: ssh cbd ls kernelengineer-noble-6c9a5055b22f-szkb +``` + +At this point you can interrupt the command with {kbd}`Ctrl-C` and periodically check the build status with the `ssh` command it printed. For example: + +```bash +ssh cbd ls kernelengineer-noble-6c9a5055b22f-szkb +``` + +You should see the build progress for each architecture with either `BUILDING` or `BUILD-OK` status. + +```{terminal} +:input: ssh cbd ls kernelengineer-noble-6c9a5055b22f-szkb +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +2025-01-24 04:38:50 0 amd64/BUILDING +2025-01-24 04:38:51 0 arm64/BUILDING +``` + +For the `linux-gke` kernel, this shows us the builds are still in progress for the amd64 and arm64 architectures. + +Once all the architectures return the `BUILD-OK` status, we know the kernel built successfully. + +### Build kernel locally + +Since we have the chroot environment set up already, we can choose to build the kernel locally. + +Clean up any temporary build files and reset the source tree: + +```bash +cranky chroot run noble:linux-gke -- fakeroot debian/rules clean +``` + +Then build and compile the different kernel packages: + +```bash +cranky chroot run noble:linux-gke -- fakeroot debian/rules binary-headers binary-generic binary-perarch +``` + +If the build is successful, you should find several .deb binary package files in the directory above the build root directory. + +```{terminal} +:input: ls ../ +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +TBD +``` + +## Package the kernel for release - `cranky update-dependents` + +To update all dependent packages in this `linux-gke` tree set (e.g. `linux-meta`, `linux-signed`, `linux-lrm`), run: + +```bash +cranky update-dependents +``` + +If successful, you should see the "SUCCESS: update complete" message in the output. + +### Tag commit - `cranky tags` + +The last step is to tag your commit with the appropriate version tag. + +```{caution} +Once a tag is pushed to the repository it cannot be modified. +So be sure to tag your commit only after verifying that your kernel source tree has been updated correctly and builds successfully. +``` + +```bash +cranky tags +``` + +You see should something similar returned in the terminal output: + +```{terminal} +:input: cranky tags +:user: kernel-engineer +:host: ubuntu-machine +:dir: ~/canonical/kernel/ubuntu/noble/linux-gke/linux-main (cranky/master-next-s2024.12.02) + +Tagging with: + git tag -f -s -m Ubuntu-gke-6.8.0-1018.22 Ubuntu-gke-6.8.0-1018.22 +``` + +### Verify preparation - `cranky verify-release-ready` + +Perform one last sanity check on the git trees to screen out any issues with the kernel preparation by running: + +```bash +cranky verify-release-ready +``` + +```{note} +The "tag pushed: warning" is an expected warning if you do not have commit rights. +``` + +### Pull sources + +```bash +cd .. +# CWD == ~/canonical/kernel/noble/linux-gke/ + +cranky pull-sources noble:linux-gke --latest +``` + +### Build sources +```bash +cd linux-main/ +cranky build-sources +``` + +## Review +```bash +cd .. +# CWD == ~/canonical/kernel/noble/linux-gke/ +cranky review *.changes +``` + +This will generate several `.debdiff` files, which show the difference between this deb package and the last one. +You should review these files in a text editor (using a command like `vim *.debdiff`) to ensure there are no unexpected changes. +However, for the sake of this tutorial, we can assume the diffs are all correct. + +## Upload + + + +Normally, at this point a cranker with upload rights would publish the newly-cranked kernel to its PPA, which automatically kicks off boot testing. +However, without upload rights, we can request someone with rights to review our work, and publish the kernel on our behalf. + +We can push the created files to a server that is accessible to the reviewer, like `kathleen`. + + +```bash +cd linux-main/ +cranky push-review -s 2024.10.08 kathleen +``` + +## Related topics + +Learn more about Ubuntu releases and derivative kernels [here]. + + + +[VPN connection]: https://canonical-kteam-docs.readthedocs-hosted.com/en/latest/how-to/new_starter/newstarter.html#setup-vpn +[Kernel team build resources]: https://canonical-kteam-docs.readthedocs-hosted.com/en/latest/how-to/new_starter/newstarter.html#build-resources +[Kernel SRU dashboard]: https://kernel.ubuntu.com/reports/kernel-stable-board/ \ No newline at end of file diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md new file mode 100644 index 0000000..ab9ded5 --- /dev/null +++ b/docs/tutorial/index.md @@ -0,0 +1,12 @@ +# Tutorials + +The following section will present you with different tutorials that address +key concepts, tools, processes, and operations relevant to the kernel team. + + +```{toctree} +:titlesonly: +:maxdepth: 1 + +Crank your first kernel +```