Go to file
2024-01-09 19:48:24 +00:00
_constraints commit f5aa89b3e95322c79e43c459f5b6862dec51fc5f 2023-08-27 08:21:25 +00:00
.gitattributes OBS-URL: https://build.opensuse.org/package/show/openSUSE:Factory/kernel-source?expand=0&rev=1 2008-07-18 10:15:21 +00:00
.gitignore OBS-URL: https://build.opensuse.org/package/show/openSUSE:Factory/kernel-source?expand=0&rev=1 2008-07-18 10:15:21 +00:00
apply-patches commit 1b516a551287446ce1222d51c63d4f9be6e5c95f 2017-05-02 07:07:06 +00:00
arch-symbols commit 52afe42897bb4127e61108c53d49476af05401f7 2022-03-19 08:12:03 +00:00
check-for-config-changes commit 4f13ec51319e762ffa04ccc667011324ae8a98f1 2023-11-15 07:09:12 +00:00
check-module-license commit 501d1f1488a209b1e29dabfc9d93e92396082ea9 2021-09-03 05:05:56 +00:00
compress-vmlinux.sh commit 8fc81d38d8b63789858468f74d67d86ddb96d14e 2014-08-22 06:03:45 +00:00
compute-PATCHVERSION.sh commit 83948c1558f87eeaca00110c09cc1f26805fe4b0 2016-01-12 07:05:55 +00:00
config.addon.tar.bz2 commit 582208c4334d0b2b1e605a44a2c5183927d6d315 2012-10-02 06:02:44 +00:00
config.conf commit 786e0d6a09099507d4d0227b55ca112f2f488afa 2023-09-14 08:50:25 +00:00
config.sh commit 218b73fcd12a30a515ced5a7188e20039f135dc4 2023-10-31 07:08:48 +00:00
config.tar.bz2 commit b5b393f4565a2d949b93e118228f456dc77e79a9 2024-01-08 07:21:58 +00:00
constraints.in commit f5aa89b3e95322c79e43c459f5b6862dec51fc5f 2023-08-27 08:21:25 +00:00
dtb-aarch64.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-aarch64.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-armv6l.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-armv6l.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-armv7l.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-armv7l.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-riscv64.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb-riscv64.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
dtb.spec.in.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
group-source-files.pl commit cbe8816d8485dc46f97a209f94053ff0a01979ba 2023-03-30 08:11:27 +00:00
guards commit 52afe42897bb4127e61108c53d49476af05401f7 2022-03-19 08:12:03 +00:00
host-memcpy-hack.h GIT Revision: 1cba112c43d2060ed8e070fbb8dd525b70a3509b 2011-10-25 05:02:09 +00:00
kabi.pl commit 4de111142ddf0e3ba42e23d5c7fe663483c91f92 2020-03-30 10:55:35 +00:00
kabi.tar.bz2 commit d4bcf2abd85a8d69da9d3f3e4e5dc57c556bca61 2016-06-26 14:47:43 +00:00
kernel-64kb.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-64kb.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-binary-conflicts commit 0df701dd2c208f4843cf219b4b26b533ada9bd34 2023-06-22 03:56:22 +00:00
kernel-binary.spec.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
kernel-cert-subpackage commit 25f042898924612664b5481f189d4ee28d87f337 2023-03-16 08:16:47 +00:00
kernel-debug.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-debug.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-default-base.spec.txt commit 6df6ad55b8b45a304b216be8e4387d3715400106 2021-08-03 08:04:33 +00:00
kernel-default.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-default.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-docs.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-docs.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-docs.spec.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
kernel-kvmsmall.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-kvmsmall.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-lpae.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-lpae.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-module-subpackage commit 42a5ff729bd08a3a07c0f26ab37a09c05eb4f725 2023-04-18 08:10:13 +00:00
kernel-obs-build.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-obs-build.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-obs-build.spec.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
kernel-obs-qa.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-obs-qa.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-obs-qa.spec.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
kernel-pae.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-pae.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-source.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-source.rpmlintrc commit 4b9b43c3573f81802c32ace9a4b8711fb79ee86c 2023-01-09 11:38:41 +00:00
kernel-source.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-source.spec.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
kernel-spec-macros commit e2dafc920ea2cf26e4ad16cb348123b53e4550e3 2023-07-10 05:18:42 +00:00
kernel-subpackage-build commit 0530e5c5395a3084d21ac5dc604220c134990e31 2021-12-15 09:02:26 +00:00
kernel-subpackage-spec commit 5fb85fd92a28bb834224cc814e2280c91e4afb4c 2021-11-16 08:04:47 +00:00
kernel-syms.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-syms.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-syms.spec.in commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
kernel-vanilla.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-vanilla.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-zfcpdump.changes commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
kernel-zfcpdump.spec commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
klp-symbols commit bc8e2ff1e2f5ee924834ff6318e98fa55e413359 2021-06-14 08:03:53 +00:00
linux-6.6.tar.sign commit 218b73fcd12a30a515ced5a7188e20039f135dc4 2023-10-31 07:08:48 +00:00
linux-6.6.tar.xz commit 218b73fcd12a30a515ced5a7188e20039f135dc4 2023-10-31 07:08:48 +00:00
linux.keyring commit d9b2122e2a3f78da96f62fc36d96f192623bddbe 2022-09-02 08:17:13 +00:00
log.sh commit ce190a85abde11c16b0a12f65d7820e251373e48 2015-08-02 06:02:28 +00:00
macros.kernel-source commit 10046187131527c2cbbe96b69afa2f1a3458e8fe 2022-12-02 08:18:13 +00:00
mergedep commit 501d1f1488a209b1e29dabfc9d93e92396082ea9 2021-09-03 05:05:56 +00:00
mkspec commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
mkspec-dtb commit e06075703b042f287c2fdd60ae1d790405249a46 2023-10-13 08:18:13 +00:00
moddep commit 4c06520b7c1e9ac2f5d9f4bf0d78cb5cbfb998e3 2019-02-15 09:39:41 +00:00
modflist commit 501d1f1488a209b1e29dabfc9d93e92396082ea9 2021-09-03 05:05:56 +00:00
modules.fips commit 72aabc280320ed44ba5be658a4e67057167ed825 2021-07-13 06:23:02 +00:00
modversions GIT Revision: 191d3dbd15aa8c06c1b5c9192193aa6b799b2f79 2011-08-07 05:03:32 +00:00
obsolete-kmps commit 0df701dd2c208f4843cf219b4b26b533ada9bd34 2023-06-22 03:56:22 +00:00
old-flavors commit f5aa89b3e95322c79e43c459f5b6862dec51fc5f 2023-08-25 18:05:52 +00:00
package-descriptions commit 4de111142ddf0e3ba42e23d5c7fe663483c91f92 2020-03-30 10:55:35 +00:00
patches.addon.tar.bz2 commit 582208c4334d0b2b1e605a44a2c5183927d6d315 2012-10-02 06:02:44 +00:00
patches.apparmor.tar.bz2 commit ab9e909366a779cb698d37c4b1afdcd867494342 2017-11-13 21:08:43 +00:00
patches.arch.tar.bz2 commit ab9e909366a779cb698d37c4b1afdcd867494342 2017-11-13 21:08:43 +00:00
patches.drivers.tar.bz2 commit 9c5b7d658b0cffa5ee18d5f9a823f849e8c9d29b 2017-11-21 09:50:52 +00:00
patches.drm.tar.bz2 commit 0df701dd2c208f4843cf219b4b26b533ada9bd34 2023-06-22 03:56:22 +00:00
patches.fixes.tar.bz2 commit 76565adce85883f18e59d682675ed1bb87bac432 2020-01-04 08:05:41 +00:00
patches.kabi.tar.bz2 commit d4bcf2abd85a8d69da9d3f3e4e5dc57c556bca61 2016-06-26 14:47:43 +00:00
patches.kernel.org.tar.bz2 commit b5b393f4565a2d949b93e118228f456dc77e79a9 2024-01-08 07:21:58 +00:00
patches.rpmify.tar.bz2 commit bdc5d1204f313b232039d5fb2d9ba69b19e01760 2023-11-07 07:08:42 +00:00
patches.rt.tar.bz2 commit 582208c4334d0b2b1e605a44a2c5183927d6d315 2012-10-02 06:02:44 +00:00
patches.suse.tar.bz2 commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
README.KSYMS OBS-URL: https://build.opensuse.org/package/show/openSUSE:Factory/kernel-source?expand=0&rev=54 2009-05-20 08:59:36 +00:00
README.PATCH-POLICY.SUSE commit eafb2e8a46d36841e6e8eb210b0ce428a4fe4481 2023-12-04 07:06:44 +00:00
README.SUSE commit ebe37ffb869ed80338256438e9605f4d3cf0b52a 2024-01-06 07:08:15 +00:00
release-projects commit 4c06520b7c1e9ac2f5d9f4bf0d78cb5cbfb998e3 2019-02-15 09:39:41 +00:00
series.conf commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
source-timestamp commit e04388ed79f6d15fba9ab58fb2ba0ac47fc955f9 2024-01-08 08:59:48 +00:00
split-modules commit 6b9975ed199835e6b9c21a0a33ed5f88f5f7a543 2021-09-14 08:05:39 +00:00
splitflist commit 33df9c651d0aa37cce1275bd9528ea5cb9196022 2021-08-21 08:03:17 +00:00
supported.conf commit cba3fa8e8d8b0d648cbbd43f27d828b3ed0f1511 2023-08-02 08:11:42 +00:00
sysctl.tar.bz2 commit 786e0d6a09099507d4d0227b55ca112f2f488afa 2023-09-14 08:50:25 +00:00
try-disable-staging-driver commit 52afe42897bb4127e61108c53d49476af05401f7 2022-03-19 08:12:03 +00:00

Working with the SUSE Kernel Sources
====================================

This document gives an overview of how SUSE Linux kernels are created, and
describes tasks like building individual kernels and creating external kernel
modules.


Overview
--------

The SUSE kernels are generated from the upstream Linux kernel sources found at
<https://kernel.org/>, on top of which a number of patches are applied. The
expanded kernel source tree is configured and built, resulting in a binary
kernel.

The add-on patches and configuration files are maintained in a Git repository at
<https://github.com/SUSE/kernel-source>, with an alternative mirror at
<https://github.com/openSUSE/kernel-source>.

A script named `scripts/tar-up.sh` packs up the files in the repository in a
form suitable for rpmbuild. When building the RPM packages, the following
binary packages get created:

* kernel-source

  The kernel source tree, generated by unpacking the vanilla kernel sources and
  applying the patches. The kernel sources are used by a number of other
  packages. They can also be used for compiling additional kernel modules.

* kernel-devel

  A complement of the kernel-source package that is needed to build external
  modules.

* kernel-`$FLAVOR`

  A number of binary kernels, for example, kernel-default for standard use,
  kernel-debug with extra debugging features, etc. These packages are all
  generated from the same kernel sources, and differ in the kernel
  configurations used.

* kernel-`$FLAVOR`-base

  A subset of kernel-`$FLAVOR`, for use in virtualized guests that only require
  a few device and filesystem drivers.

* kernel-`$FLAVOR`-devel

  The files used for generating kernel module packages for use with
  kernel-`$FLAVOR`.

* kernel-syms

  A meta package that pulls in the relevant kernel-`$FLAVOR`-devel packages for
  a given architecture.

The repository contains configuration files (`.config`) for all SUSE kernel
flavors. All configuration files are included in the dependencies of the
kernel-syms package, see [Where to find configuration
files](#where-to-find-configuration-files) below.

In the installed system, the kernel-source package installs files in the
following directories:

* `/usr/src/linux-$VERSION-$RELEASE/`

  The kernel sources.

* `/usr/src/linux`

  A symbolic link to `/usr/src/linux-$VERSION-$RELEASE/`.

* `/usr/share/doc/packages/kernel-source-$VERSION-$RELEASE/`

  This document.

The kernel-`$FLAVOR`-devel packages install the following files:

* `/usr/src/linux-$VERSION-$RELEASE-obj/$ARCH/$FLAVOR/`

  Kernel build object files for one kernel flavor. These files are used for
  compiling additional kernel modules.

* `/usr/src/linux-obj/$ARCH/$FLAVOR`

  A symbolic link to `/usr/src/linux-$VERSION-$RELEASE-obj/$ARCH/$FLAVOR/`.


Compiling your own kernel
-------------------------

The kernel sources are found in the kernel-source package. A binary kernel can
be built from these sources as follows:

1. Install the kernel-source package.

2. Create a build directory for use in configuring and building the kernel.
   Using `/usr/src/linux/` directly requires root privileges and will cause
   problems if you need to build kernel modules for other installed kernels.

3. Configure the kernel, see [How to configure the kernel
   sources](#how-to-configure-the-kernel-sources). For example,
   `make -C /usr/src/linux O=$PWD oldconfig`.

4. Build the kernel and all its modules by invoking `make`.

5. Make sure that `/etc/modprobe.d/10-unsupported-modules.conf` contains

       allow_unsupported_modules 1

   otherwise modprobe will refuse to load any modules.

6. Install the modules and kernel: `make modules_install`, followed by
   `make install`. This automatically creates an initrd for the new kernel and
   adds an entry to the GRUB boot menu.

Instead of building binary kernels by hand, you can also build one of the
kernel-`$FLAVOR` packages using RPM.


Building additional (external) modules
--------------------------------------

A single binary kernel module generally only works for a specific version of the
kernel source tree, for a specific architecture and configuration. This means
that for each binary kernel that SUSE ships, a custom module must be built. This
requirement is to some extent relaxed by the modversion mechanism: modversions
attach a checksum to each symbol (function or variable) exported to modules by
the kernel. This allows to use kernel modules that have been built for a kernel
with a different version or release number in many cases, as long as none of the
symbols the module uses have changed between the two kernel versions.

When releasing maintenance or security update kernels for a specific product, we
carefully try to keep the kernel ABI stable. Despite this, we sometimes have no
choice but to break binary compatibility. In this case, those kernel modules
must be rebuilt.

Additional kernel modules for one of the SUSE kernel flavors can be built in the
following ways:

1. by doing an ad-hoc module build, using one of the standard configurations in
   `/usr/src/linux-obj/$ARCH/$FLAVOR`, or

2. by creating a Kernel Module Package (KMP) as described in the Kernel Module
   Packages Manual,
   <https://documentation.suse.com/sbp/all/html/SBP-KMP-Manual-SLE12SP2/index.html>.

The first method involves the following steps:

1. Install the kernel-devel package.

2. Install the kernel-`$FLAVOR`-devel package. This is necessary for symbol
   version information (`CONFIG_MODVERSIONS`).

3. Compile the module(s) by changing into the module source directory and typing
   `make -C /usr/src/linux-obj/$ARCH/$FLAVOR M=$PWD`. Substitute `$ARCH` and
   `$FLAVOR` with the architecture and flavor for which to build the module(s).

   If the installed kernel sources match the running kernel, you can build
   modules for the running kernel by using the path
   `/lib/modules/$(uname -r)/build` as the `-C` option in the above command.
   (`build` is a symlink to `/usr/src/linux-obj/$ARCH/$FLAVOR`.)

4. Install the module(s) with
   `make -C /usr/src/linux-obj/$ARCH/$FLAVOR M=$PWD modules_install`.

Whenever building modules, please use the kernel build infrastructure as much as
possible, and do not try to circumvent it. The `Documentation/kbuild` directory
in the kernel sources documents kbuild makefiles.


Supported vs. unsupported modules
---------------------------------

As an extension to the mainline kernel, modules can be tagged as supported
(directly by SUSE, or indirectly by a third party) or unsupported. Modules which
are known to be flakey or for which SUSE does not have the necessary expertise
are marked as unsupported. Modules for which SUSE has third-party support
agreements are marked as externally supported. Modules for which SUSE provides
direct support are marked as supported.

The support status of a module can be queried with the modinfo tool. Modinfo
will report one of the following:

* direct support by SUSE: "supported: yes",
* third-party support: "supported: external",
* unsupported modules: no supported tag.

At runtime, the setting of the "unsupported" kernel command line parameter and
`/proc/sys/kernel/unsupported` determines whether unsupported modules can be
loaded or not, and whether or not loading an unsupported module causes a warning
in the system log:

* 0 = only allow supported modules,
* 1 = warn when loading unsupported modules,
* 2 = don't warn.

Irrespective of this setting, loading an externally supported or unsupported
module both set a kernel taint flag. The taint flags are included in Oopses. The
taint status of the kernel can be inspected in `/proc/sys/kernel/tainted`.
Relevant bits have the following meaning:

| Bit | Log |     Number | Reason that got the kernel tainted                 |
|----:|----:|-----------:|----------------------------------------------------|
|   0 | G/P |          1 | proprietary module was loaded                      |
|  12 | ␣/O |       4096 | externally-built ("out-of-tree") module was loaded |
|  13 | ␣/E |       8192 | unsigned module was loaded                         |
|  16 | ␣/X |      65536 | module with third-party support was loaded         |
|  31 | ␣/N | 2147483648 | unsupported module was loaded                      |

Bits 16 and 31 are specific to the SUSE kernels.

Out-of-tree modules do not have the supported flag set by default; that
is, they are marked as unsupported. For building externally supported
modules, please get in touch with the Solid Driver Program team, led by
Scott Bahling, at <mailto:soliddriver@suse.com>.


Patch selection mechanism
-------------------------

The SUSE kernels consist of the upstream kernel sources on top of which a number
of patches is applied. The file `series.conf` determines which patches are
applied and which are excluded. A script named `guards` converts `series.conf`
into a plain list of patch files to be applied. Guards decides which patches to
include and exclude based on a list of symbols. From the kernel-source.src.rpm
package, a fully patched kernel source tree can be generated from vanilla
sources + patches like this:

1. Install the package:

       # rpm -i kernel-source-$RPMVERSION-$RPMRELEASE.src.rpm

2. Unpack the patches and the kernel sources:

       # cd /usr/src/packages/SOURCES/
       # for f in patches.*.tar.bz2; do \
           tar -xjf "$f" || break; \
         done
       # tar -xJf linux-$SRCVERSION.tar.xz

3. Apply the patches

       # for p in $(./guards < series.conf); do \
           patch -d linux-$SRCVERSION -p1 < $p || break; \
         done

The configuration script `config.conf` which is similar to `series.conf` is
used for configuration file selection, see the section [Where to find
configuration files](#where-to-find-configuration-files).

The file format of `series.conf` and `config.conf` should be apparent from the
comments in `series.conf` and from the guards(1) manual page. You can generate
this page by running `pod2man` on the `guards` script.


Where to find configuration files
---------------------------------

Kernel configuration files are stored in the kernel Git repository. When packing
up the repository, they end up in `config.tar.bz2`.

The kernel-`$FLAVOR` packages are based on `config/$ARCH/$FLAVOR`, for instance,
kernel-default is based on `config/$ARCH/default`. The kernel-`$FLAVOR` packages
install their configuration files as `/boot/config-$VERSION-$RELEASE-$FLAVOR`.
The config is also packaged in the kernel-`$FLAVOR`-devel package as
`/usr/src/linux-obj/$ARCH/$FLAVOR/.config`.

In addition, the running kernel exposes a gzip compressed version of its
configuration file as `/proc/config.gz`.


How to configure the kernel sources
-----------------------------------

Before a binary kernel is built or an additional loadable module for an existing
kernel is created, the kernel must be configured.

In order for a loadable module to work with an existing kernel, it must be
created with a configuration that is identical to the kernel's configuration, or
at least very close to that. Each configuration is contained in a single file.
The kernel-syms package installs configurations for all standard SUSE kernel
variants, so for building only external kernel modules it is not necessary to
configure the kernel sources.

Configuring the kernel sources for a specific configuration is straightforward:

* Locate the configuration file you want to use, see [Where to find
  configuration files](#where-to-find-configuration-files) above.

* Copy the configuration to the file `.config` in your build directory.

* Run the following commands in sequence to apply the configuration, generate
  version information files, etc.:

      $ make -C /usr/src/linux O=$PWD clean
      $ make -C /usr/src/linux O=$PWD oldconfig

  If the kernel sources do not match the configuration file exactly,
  `make oldconfig` will prompt for settings that are undefined. When no
  `.config` file is initially copied to the target build directory, the command
  automatically uses `/boot/config-$(uname -r)` as the starting configuration.
  Alternatively to `make oldconfig`, you can also use `make menuconfig` for
  a text menu oriented user interface.

  Once this step is completed, a `Makefile` will have been created that
  eliminates the need to specify the locations of the kernel source and the
  build directory.

* Update the configuration appropriately for the target use.

  Configuration files for SUSE kernels include settings to integrate with
  signing support provided by the Open Build Service. When using such a
  configuration file directly, the build might fail due to missing files needed
  for signing kernel modules.

  The minimal steps to enable module signing and have the kernel build
  automatically generate a new key pair are as follows:

      $ ./source/scripts/config --enable CONFIG_MODULE_SIG \
          --enable CONFIG_MODULE_SIG_ALL --undefine CONFIG_MODULE_SIG_KEY
      $ make olddefconfig

  Please refer to the upstream documentation located at
  `/usr/src/linux/Documentation/admin-guide/module-signing.rst` for complete
  information on how to configure module signing.


How to add custom patches
-------------------------

Patches are typically added to the `patches.suse/` directory and an appropriate
place in `series.conf`. When the kernel-source package is exported from the Git
repository, the patch will be automatically added to the matching patch tarball.

If your goal is to create a kernel with only a few additional patches and you
don't want to be bothered with using the Git repository, there is an easier way.

The kernel-source SRPM ships with two empty archives that can be filled and
automatically expanded when building the kernel. You can use these to add your
own patches and config options without disturbing the rest of the kernel
package. This is useful if you are using the openSUSE Build Service and link to
the main kernel-source project instead of creating your own branch. The
advantage to this is that your project will automatically receive all the
changes that go into the main project without any further effort.

To add a patch using this mechanism, just add it to the `patches.addon.tar.bz2`
archive and add an entry to a `series` file inside the archive. The archive will
be expanded automatically after the other kernel patches when the source tree is
constructed.

Some patches may add new Kconfig options. The `config.addon.tar.bz2` archive
contains the same hierarchy as `config.tar.bz2`, but is under `config.addon/`.
You can add your new config options to files named after their `config/`
counterparts.

For example, the file used to configure the x86_64 default kernel is named
`config/x86_64/default`. To add config options to that kernel, you would create
a new file called `config.addon/x86_64/default` with the options as formatted in
a normal Linux kernel `.config` file. This is important because the kernel build
is non-interactive and will fail if it encounters new config options without
entries in the config file.


Module load paths
-----------------

Modules that belong to a specific kernel release are installed in
`/lib/modules/$VERSION-$RELEASE-$FLAVOR/`. Modules from KMPs must be installed
below `/lib/modules/$VERSION-$RELEASE-$FLAVOR/updates/` and similar: modules
below `updates/` have priority over other modules.

When KMPs contain modules that are compatible between multiple installed
kernels, symlinks are used to make those modules available to those compatible
kernels like this:

`/lib/modules/$VERSION-$OTHER_RELEASE-$FLAVOR/weak-updates/foo.ko` →
  `/lib/modules/$VERSION-$RELEASE-$FLAVOR/updates/foo.ko`

Modules in the `weak-updates/` directory have lower priority than modules in
`/lib/modules/$VERSION-$OTHER_RELEASE-$FLAVOR/updates/`, and higher priority
than other modules in `/lib/modules/$VERSION-$OTHER_RELEASE-$FLAVOR/`.


Driver update disks
-------------------

A Driver Update Disk (DUD) is an update archive which makes it possible to use
new device drivers to run installation of an (open)SUSE distribution. It allows
to install the distribution on devices that were not supported at the time the
distribution was created and be able to boot the installed system afterwards
without having to manually install the new device drivers after the
installation.

For information how to create such an update, refer to the mkdud and mksusecd
tools, and their documentation:

* <https://github.com/openSUSE/mkdud>,
* <https://github.com/openSUSE/mksusecd>.


References
----------

General:

* Documentation in the kernel source tree,
* LWN.net (Linux Weekly News), <https://lwn.net/>,
* Kernel newbies, <https://kernelnewbies.org/>.

Loadable kernel modules:

* Peter Jay Salzman, Michael Burian, Ori Pomerantz: The Linux Kernel Module
  Programming Guide, Version 2.6,
  <https://tldp.org/LDP/lkmpg/2.6/html/index.html>.

Kernel module packages:

* Kernel Module Packages Manual, SUSE Linux Enterprise 12 SP2 or later and SUSE
  Linux Enterprise 15,
  <https://documentation.suse.com/sbp/all/html/SBP-KMP-Manual-SLE12SP2/index.html>,
* SUSE SolidDriver Program, <https://drivers.suse.com/doc/SolidDriver/>.