Skip to content

docs(reference): migrate from kteam-docs #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AnneCYH merged 1 commit into from
Dec 3, 2024
Merged

docs(reference): migrate from kteam-docs #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/_images/ref-hwe-kernel-release-cycle-jammy.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
40 changes: 34 additions & 6 deletions docs/reference/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,38 @@
This page is a running list of terminology that is frequently used when talking
about kernels.

```{glossary}
````{glossary}
:sorted:

DKMS
Dynamic Kernel Module Support, or DKMS is a framework that provides support
for installing supplementary versions of kernel modules in a simplified manner.
See the dkms manpages for more information.

ABI
Application Binary Interface, or ABI defines a stable interface between user space
applications and the kernel. It ensures that the binaries of applications compiled
for one version of the kernel remain compatible with subsequent versions, as long as the
ABI remains unchanged.

DKMS
Dynamic Kernel Module Support, or DKMS is a framework that provides support
for installing supplementary versions of kernel modules in a simplified manner.
See the [dkms manpages] for more information.

edge kernel
An edge kernel is the next HWE kernel still in development with features
and/or updates that will be backported from the latest Ubuntu release (until
the next LTS).

HWE
Hardware enablement, or HWE kernels are Ubuntu kernels based on newer upstream
kernel versions (compared to the Ubuntu LTS GA release) that typically
contain newer features, improved performance and security, and support for
newer classes of hardware.
Newer kernels are usually shipped with interim and LTS releases, and will
then be enabled on the latest Ubuntu LTS release as the HWE kernel.
This provides an easier upgrade path for existing LTS users, and enables
new deployments to immediately benefit from the newer kernel version.

See {doc}`/reference/hwe-kernels` for more information.

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
Expand All @@ -36,9 +54,19 @@ linux-signed
and enhancing security in the kernel deployment process. This package works in tandem with
the linux-meta package to deliver signed kernel updates.

OEM kernel
```{include} /reuse/oem-kernels.txt
:start-after: overview-oem-kernel-start
:end-before: overview-oem-kernel-end
```

See {doc}`/reference/oem-kernels` for more information.

SRU
Stands for Stable Release Update, a process in distributions like Ubuntu used to provide important
updates to packages, including kernel packages, after the release of a stable version. SRUs deliver
fixes for critical bugs, security vulnerabilities, and hardware enablement while ensuring the stability
of the system.
```
````

[dkms manpages]: https://manpages.ubuntu.com/manpages/latest/en/man8/dkms.8.html
287 changes: 287 additions & 0 deletions docs/reference/hwe-kernels.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,287 @@
HWE kernels
===========

This document provides some reference information about Hardware Enablement
(HWE) kernels: the support lifecycle, current kernel in development, the next
planned Ubuntu base kernel version, kernel source code, and how to install the
HWE kernels for use on your machine.

Support lifecycle for HWE kernels
---------------------------------

HWE kernels are only enabled on Ubuntu long-term support (LTS) releases, and
have similar life cycles as their newer Ubuntu kernel counterparts. They will
typically get rolled off to the next HWE kernel once a new Ubuntu series is
released (until the next LTS).

.. figure:: /_images/ref-hwe-kernel-release-cycle-jammy.svg
:alt: Typical HWE kernel release cycle

Example of HWE kernel release cycle for Jammy Jellyfish

The table below summarises the support lifecycle, development and release
schedule, end-of-life (EOL) and Extended Security Maintenance (ESM) dates for
supported and upcoming HWE kernels.

.. _table-ref-HWE-kernel-lifecycle-package:

.. table:: HWE kernel lifecycle and package details
:align: center

+-----------------+------------------------+----------------+----------------------------------------------------------+
| Ubuntu series | Ubuntu version | Kernel version | Key dates |
+=================+========================+================+==========================================+===============+
| Noble Numbat | 24.04.0 LTS | 6.8 | Release | April 2024 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2029 |
+-----------------+------------------------+----------------+------------------------------------------+---------------+
| Jammy Jellyfish | *22.04.5 LTS (HWE)* | *6.8* | :ref:`Edge <ref-about-hwe-install-edge>` | *June 2024* |
| | | +------------------------------------------+---------------+
| | | | *Release* | *August 2024* |
| | | +------------------------------------------+---------------+
| | | | *EOL* | *April 2027* |
| +------------------------+----------------+------------------------------------------+---------------+
| | 22.04.4 LTS (HWE) | 6.5 | Release | February 2024 |
| | | +------------------------------------------+---------------+
| | | | EOL | August 2024 |
| +------------------------+----------------+------------------------------------------+---------------+
| | 22.04.0 LTS | 5.15 | Release | April 2022 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2027 |
| | | +------------------------------------------+---------------+
| | | | ESM | March 2032 |
+-----------------+------------------------+----------------+------------------------------------------+---------------+
| Focal Fossa | 20.04.5 LTS (HWE) | 5.15 | Release | August 2022 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2025 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2030 |
| +------------------------+----------------+------------------------------------------+---------------+
| | 20.04.0 LTS | 5.4 | Release | April 2020 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2025 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2030 |
+-----------------+------------------------+----------------+------------------------------------------+---------------+
| Bionic Beaver | 18.04.5 LTS (HWE) | 5.4 | Release | August 2020 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2023 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2028 |
| +------------------------+----------------+------------------------------------------+---------------+
| | 18.04.0 LTS | 4.15 | Release | April 2018 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2023 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2028 |
+-----------------+------------------------+----------------+------------------------------------------+---------------+
| Xenial Xerus | 16.04.5 LTS (HWE) | 4.15 | Release | August 2018 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2021 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2026 |
| +------------------------+----------------+------------------------------------------+---------------+
| | 16.04.0 LTS | 4.4 | Release | April 2016 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2021 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2026 |
+-----------------+------------------------+----------------+------------------------------------------+---------------+
| Trusty Tahr | 14.04.5 LTS (HWE) | 4.15 | Release | August 2016 |
| | | +------------------------------------------+---------------+
| | | | EOL | April 2019 |
| | | +------------------------------------------+---------------+
| | | | ESM | April 2024 |
+-----------------+------------------------+----------------+------------------------------------------+---------------+

.. note::

HWE kernels that have reached EOL and are no longer under the ESM support
phase are excluded from the table above.
See the `Ubuntu kernel release cycle`_ for information.

Installing a HWE kernel
-----------------------

.. tabs::

.. group-tab:: 24.04 LTS

*Ubuntu 24.04 LTS (Noble Numbat)*

By default, Ubuntu Desktop installations of 24.04 default to tracking the
HWE stack.
Server installations will default to the general availability (GA) kernel
and provide the HWE kernel as an option.

Desktop:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-24.04

Server:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-24.04

.. group-tab:: 22.04 LTS

*Ubuntu 22.04 LTS (Jammy Jellyfish)*

By default, Ubuntu Desktop installations of 22.04 default to tracking the
HWE stack.
Server installations will default to the GA kernel and provide the HWE
kernel as an option.

Desktop:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-22.04

Server:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-22.04

.. group-tab:: 20.04 LTS

*Ubuntu 20.04 LTS (Focal Fossa)*

By default, Ubuntu Desktop installations of 20.04 default to tracking the
HWE stack.
Server installations will default to the GA kernel and provide the HWE
kernel as an option.

Desktop:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-20.04

Server:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-20.04

.. group-tab:: 18.04 LTS

*Ubuntu 18.04 LTS (Bionic Beaver)*

By default, Ubuntu Desktop installations of 18.04.2 and newer point
releases will ship with an updated kernel and X stack.
Server installations will default to the GA kernel and provide the HWE
kernel as an option.

Desktop:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-18.04 xserver-xorg-hwe-18.04

Server:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-18.04

.. group-tab:: 16.04 LTS

*Ubuntu 16.04 LTS (Xenial Xerus)*

By default, Ubuntu Desktop installations of 16.04.2 and newer point
releases will ship with an updated kernel and X stack.
Server installations will default to the GA kernel and provide the HWE
kernel as an option.

Desktop:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-16.04 xserver-xorg-hwe-16.04

Server:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-16.04

.. group-tab:: 14.04 LTS

*Ubuntu 14.04 LTS (Trusty Tahr)*

By default, Ubuntu Desktop installations of 14.04.2 and newer point
releases will ship with an updated kernel and X stack.
Server installations will default to the GA kernel and provide the HWE
kernel as an option.

Desktop:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-lts-xenial xserver-xorg-core-lts-xenial xserver-xorg-lts-xenial xserver-xorg-video-all-lts-xenial xserver-xorg-input-all-lts-xenial libwayland-egl1-mesa-lts-xenial


Server:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-lts-xenial

.. _ref-about-hwe-install-edge:

Installing an edge HWE kernel
-----------------------------

.. note::

Edge variants of HWE kernels are considered to be in development mode and are
not supported. These edge variants may have missing components, missing
:term:`DKMS`, or contain bugs. Edge HWE kernels are not stable releases and
should not be used in a production environment.

You can get early access to the next HWE kernel - that will be shipped with a
newer kernel version - by installing the ``-edge`` variant.

To install the latest edge kernel variant for Ubuntu 22.04 LTS, run:

.. code:: shell

sudo apt-get install --install-recommends linux-generic-hwe-22.04-edge

For more information, see :term:`edge kernel` for more information.

Reporting bugs on HWE kernels
-----------------------------

There are two recommended approaches to report a bug against a HWE kernel
package.

1. Using the ``apport-bug`` command.

.. code:: bash

apport-bug linux

#. Through the "Report a bug" form for the ``linux`` package in Launchpad:
https://bugs.launchpad.net/ubuntu/+source/linux/+filebug.

Related topics
--------------

- See the `Stable Updates Cycles`_ for the dates of the last day for kernel
patches (for HWE kernels) for each stable update cycle.
- See the `Ubuntu kernel release cycle`_ for more details about the kernel
support lifecycle, including the ESM support phase.
- See the `Ubuntu kernel lifecycle and enablement stack`_ for more details about
HWE kernels and their support status.

.. LINKS

.. _Stable Updates Cycles: https://kernel.ubuntu.com/
.. _Ubuntu kernel release cycle: https://ubuntu.com/about/release-cycle#ubuntu-kernel-release-cycle
.. _Ubuntu kernel lifecycle and enablement stack: https://ubuntu.com/kernel/lifecycle
28 changes: 25 additions & 3 deletions docs/reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,32 @@
Reference material about Ubuntu kernel development processes, terminology, and
more.

<!--
.. toctree::
:maxdepth: 1
:caption: Ubuntu on Xilinx:

xilinx/index
-->

```{toctree}
:maxdepth: 1
:caption: Kernel variants

hwe-kernels
oem-kernels
```

```{toctree}
:maxdepth: 1
:caption: Kernel patch guidelines

patch_acceptance_criteria
```

```{toctree}
:titlesonly:
:maxdepth: 1
:glob:
:caption: General

*
glossary
```
Loading
Loading