diff --git a/docs/_images/ref-hwe-kernel-release-cycle-jammy.svg b/docs/_images/ref-hwe-kernel-release-cycle-jammy.svg
new file mode 100644
index 0000000..ccf4d42
--- /dev/null
+++ b/docs/_images/ref-hwe-kernel-release-cycle-jammy.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
index f0ba241..4bfb5b4 100644
--- a/docs/reference/glossary.md
+++ b/docs/reference/glossary.md
@@ -3,13 +3,9 @@
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
@@ -17,6 +13,28 @@ ABI
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
@@ -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
\ No newline at end of file
diff --git a/docs/reference/hwe-kernels.rst b/docs/reference/hwe-kernels.rst
new file mode 100644
index 0000000..256a52f
--- /dev/null
+++ b/docs/reference/hwe-kernels.rst
@@ -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 ` | *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
\ No newline at end of file
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 244cbed..34fe1da 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -3,10 +3,32 @@
Reference material about Ubuntu kernel development processes, terminology, and
more.
+
+
+```{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
```
\ No newline at end of file
diff --git a/docs/reference/oem-kernels.rst b/docs/reference/oem-kernels.rst
new file mode 100644
index 0000000..838c519
--- /dev/null
+++ b/docs/reference/oem-kernels.rst
@@ -0,0 +1,140 @@
+OEM kernels
+===========
+
+```{include} /reuse/oem-kernels.txt
+:start-after: overview-oem-kernel-start
+:end-before: overview-oem-kernel-end
+```
+
+This document provides some reference information about OEM kernels: the support
+lifecycle for rolling releases, current kernel in development, the next planned
+generic Ubuntu kernel version, kernel source code, and how to install the OEM
+kernels for use on your machine.
+
+Support lifecycle for OEM kernels
+---------------------------------
+
+OEM kernels have shorter life cycles than their generic Ubuntu kernel
+counterparts. They will typically get rolled off to the next HWE kernel once all
+the fixes have been forward-ported.
+
+The table below summarises the support lifecycle, development and stable release
+schedules, EOL dates, and kernel migration target for supported and upcoming OEM
+kernels.
+
+.. _table-ref-oem-kernel-lifecycle-package:
+
+.. table:: OEM kernel lifecycle and package details
+
+ +---------------------------+------------------------------+-------------------------+---------------------------+
+ | Kernel and Ubuntu version | Source code and meta package | Key dates | Migration target |
+ +===========================+==============================+========+================+===========================+
+ | 6.5 | s: `linux-oem-6.5`_ | Devel | July 2023 | 22.04.5 HWE kernel (6.8) |
+ | | +--------+----------------+ |
+ | 22.04 LTS (Jammy) | m: linux-oem-22.04d | Stable | August 2023 | |
+ | | +--------+----------------+ |
+ | | | EOL | July 2024 | |
+ +---------------------------+------------------------------+--------+----------------+---------------------------+
+ | 6.8 | s: `linux-oem-6.8`_ | Devel | March 2024 | 24.04.2 HWE kernel (6.11) |
+ | | +--------+----------------+ |
+ | 24.04 LTS (Noble) | m: linux-oem-24.04a | Stable | April 2024 | |
+ | | +--------+----------------+ |
+ | | | EOL | February 2025 | |
+ +---------------------------+------------------------------+--------+----------------+---------------------------+
+ | 6.11 | s: `linux-oem-6.11`_ | Devel | August 2024 | TBD |
+ | | +--------+----------------+ |
+ | 24.04 LTS (Noble) | m: linux-oem-24.04b | Stable | November 2024 | |
+ | | +--------+----------------+ |
+ | | | EOL | July 2025 | |
+ +---------------------------+------------------------------+--------+----------------+---------------------------+
+
+.. note::
+ OEM kernels that have reached end-of-life (EOL) are excluded from the table
+ above.
+
+Selection guidelines for OEM kernels
+------------------------------------
+
+In general, we need at least three OEM kernels for each Ubuntu LTS release to
+support our OEM projects.
+
+- First OEM kernel
+
+ Released early in the Ubuntu LTS cycle to meet the needs of OEM projects that
+ require the latest Ubuntu LTS release. This OEM kernel is based on the Ubuntu
+ LTS kernel, with the same kernel version. Normally, this will be migrated to
+ the \*.2 :abbr:`HWE (Hardware Enablement)` kernel.
+
+- Second OEM kernel
+
+ The second OEM kernel is typically released in the second half of the same
+ year as the Ubuntu LTS release, and it is for supporting the latest Intel and
+ AMD hardware platforms. It could be based on either the xx.10 Ubuntu kernel or
+ the upstream LTS kernel, and may later migrate to the \*.3 or \*.4 HWE kernel.
+
+- Third OEM kernel
+
+ The final OEM kernel introduced in an LTS cycle to support the latest hardware
+ near the end of the release timeline. This will be migrated to the \*.5 HWE
+ kernel.
+
+These guidelines serve as a reference only and may be adjusted as necessary
+to accommodate hardware schedules.
+Additional OEM kernels may be introduced to support cutting-edge hardware
+designs and to meet the time-to-market requirements of OEM partners.
+
+Downloading and installing OEM kernels
+--------------------------------------
+
+To view and/or download the source code for OEM kernels, go to the kernel
+repository (e.g. “s: linux-oem-6.5”) listed in the “Source code and meta
+package” column in the :ref:`table-ref-oem-kernel-lifecycle-package` table.
+
+To install an OEM kernel, use the meta-package name (e.g. “m: linux-oem-22.04d”)
+for the kernel version listed in the “Source code and meta package” column in
+the :ref:`table-ref-oem-kernel-lifecycle-package` table.
+For example, to install OEM kernel version 6.8, run:
+
+.. code:: bash
+
+ apt install linux-oem-24.04a
+
+.. tip::
+ Use the meta-package name when installing the OEM kernel to ensure that you
+ continue receiving automated updates even after the OEM kernel is rolled off
+ to the target migration kernel.
+
+Reporting bugs on OEM kernels
+-----------------------------
+
+There are two recommended approaches to report a bug against an OEM kernel
+package.
+
+1. Using the ``apport-bug`` command with the OEM kernel package name. For
+ example, to report a bug for the "linux-oem-6.8" kernel, run:
+
+ .. code:: bash
+
+ apport-bug linux-oem-6.8
+
+#. Through the "Report a bug" form in Launchpad. For example, to report a bug
+ for the "linux-oem-6.8" kernel, go to
+ https://bugs.launchpad.net/ubuntu/+source/linux-oem-6.8/+filebug.
+
+Related topics
+--------------
+
+- See the `Stable Updates Cycles`_ for the dates of the last day for kernel
+ patches (for OEM kernels) for each stable update cycle.
+- See the Gitea repositories for `jammy-linux-oem`_ and `noble-linux-oem`_ for
+ pending pull requests and details on the patches that are merged and released
+ for each OEM kernel.
+
+.. LINKS
+
+.. _linux-oem-6.5: https://kernel.ubuntu.com/gitea/kernel/jammy-linux-oem/src/branch/oem-6.5-next
+.. _linux-oem-6.8: https://kernel.ubuntu.com/gitea/kernel/noble-linux-oem/src/branch/oem-6.8-next
+.. _linux-oem-6.11: https://kernel.ubuntu.com/gitea/kernel/noble-linux-oem/src/branch/oem-6.11-next
+.. _Stable Updates Cycles: https://kernel.ubuntu.com/
+.. _jammy-linux-oem: https://kernel.ubuntu.com/gitea/kernel/jammy-linux-oem/pulls
+.. _noble-linux-oem: https://kernel.ubuntu.com/gitea/kernel/noble-linux-oem/pulls
\ No newline at end of file
diff --git a/docs/reuse/oem-kernels.txt b/docs/reuse/oem-kernels.txt
new file mode 100644
index 0000000..165d087
--- /dev/null
+++ b/docs/reuse/oem-kernels.txt
@@ -0,0 +1,6 @@
+overview-oem-kernel-start
+The OEM kernel is an optimised derivative Ubuntu kernel, designed specifically
+for use in Original Equipment Manufacturer (OEM) projects.
+OEM kernel variants are typically developed and customised for hardware that
+will be pre-installed with Ubuntu.
+overview-oem-kernel-end
\ No newline at end of file