mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-07-09 22:25:58 +00:00
Updates to titles and content
This commit is contained in:
Kevin Putnam
@@ -1,105 +1,94 @@
|
||||
.. _kernel-modules:
|
||||
|
||||
Kernel Modules
|
||||
##############
|
||||
Add Kernel Modules
|
||||
##################
|
||||
|
||||
Kernel modules are additional pieces of software capable of being inserted
|
||||
into the Linux kernel to add functionality, such as a hardware driver.
|
||||
Kernel modules may already be part of the Linux source tree (in-tree) or may
|
||||
come from an external source, such as a directly from vendor (out-of-tree).
|
||||
|
||||
In many cases kernel modules are already available through |CL-ATTR|.
|
||||
In other cases, a kernel module may not exist but can be requested to be
|
||||
enabled in the |CL| kernel. Finally, a situation may call for manually
|
||||
building and loading out-of-tree kernel modules.
|
||||
The document will describe evaluating each of these scenarios.
|
||||
|
||||
|
||||
In cases where drivers beyond those enabled by default in |CL-ATTR| are
|
||||
needed it may be necessary to:
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 2
|
||||
:depth: 1
|
||||
:backlinks: top
|
||||
|
||||
Check if the module is available through |CL|
|
||||
=============================================
|
||||
|
||||
|
||||
Adding a kernel module to a Clear Linux system
|
||||
**********************************************
|
||||
Using an existing module is significantly easier to maintain and retains
|
||||
signature verification of the |CL| kernel. For more information on |CL|
|
||||
security practices, see the :ref:`security` page.
|
||||
|
||||
|
||||
Check if the module is already available through Clear Linux
|
||||
============================================================
|
||||
|CL| comes with many upstream kernel modules available for use. If
|
||||
you require a kernel module, be sure to check whether it is already available in |CL| first.
|
||||
|
||||
|
||||
You can search for kernel module file names, which end with the :file:`.ko`
|
||||
file extension, using the :command:`swupd search` command. For example:
|
||||
:command:`sudo swupd search ${module_name}.ko`.
|
||||
See :ref:`swupd-search` for more information.
|
||||
|
||||
Request the module be added to |CL|
|
||||
===================================
|
||||
|
||||
Consider requesting the module be added to |CL|
|
||||
===============================================
|
||||
If the kernel module you're needing is already already open source
|
||||
If the kernel module you need is already already open source
|
||||
(e.g. in the Linux upstream) and likely to be useful to others,
|
||||
consider submitting a request to add or enable to the |CL| kernel.
|
||||
consider submitting a request to add or enable in the |CL| kernel.
|
||||
|
||||
You can make enhancement requests to the |CL| distribution `on GitHub`_ .
|
||||
Make enhancement requests to the |CL| distribution `on GitHub`_ .
|
||||
|
||||
Build and load an out-of-tree module
|
||||
====================================
|
||||
|
||||
In some cases you may need an out-of-tree kernel module that is not
|
||||
available through |CL|.
|
||||
|
||||
Building and loading out-of-tree modules
|
||||
========================================
|
||||
In some cases you may need an out-of-tree kernel module that is not able
|
||||
to be made available through |CL|.
|
||||
You can build and load out-of-tree kernel modules, however secure boot
|
||||
must be disabled, kernel module integrity checking must be disabled, and
|
||||
you are responsible for building the module against new versions of the
|
||||
Linux kernel.
|
||||
|
||||
.. note::
|
||||
|
||||
You can build and load out-of-tree kernel modules however secure boot must be
|
||||
disabled, kernel module integrity checking must be disabled, and you are
|
||||
responsible for building the module against new versions of the Linux kernel.
|
||||
|
||||
Any time the kernel is upgraded on your Clear Linux system, you will
|
||||
need to rebuild your out-of-tree modules.
|
||||
|
||||
|
||||
This approach works well for individual development or testing.
|
||||
For a more scalable and customizable approach, consider using the
|
||||
`mixer tool`_ to provide a custom kernel and updates.
|
||||
|
||||
|
||||
Building kernel modules
|
||||
-----------------------
|
||||
Build kernel module
|
||||
-------------------
|
||||
|
||||
#. From a |CL| system, ensure you are running the *native* kernel.
|
||||
Currently only the native kernel is enabled to build and load
|
||||
out-of-tree modules.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
$ uname -r
|
||||
4.XX.YY-ZZZZ.native
|
||||
|
||||
Ensure *.native* is in the kernel name
|
||||
$ uname -r
|
||||
4.XX.YY-ZZZZ.native
|
||||
# Ensure *.native* is in the kernel name
|
||||
|
||||
#. Install the `linux-dev` bundle to obtain the kernel headers, which are
|
||||
required for compiling kernel modules
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add linux-dev
|
||||
sudo swupd bundle-add linux-dev
|
||||
|
||||
#. Follow instructions from the kernel module source code to compile the
|
||||
kernel module
|
||||
|
||||
|
||||
Loading kernel modules
|
||||
----------------------
|
||||
Load kernel module
|
||||
------------------
|
||||
|
||||
#. Disable Secure Boot in your system's UEFI settings, if you have enabled it.
|
||||
The loading of new out-of-tree modules modifies the signatures Secure Boot
|
||||
relies on for trust.
|
||||
#. Disable Secure Boot in your system's UEFI settings, if you have enabled
|
||||
it. The loading of new out-of-tree modules modifies the signatures Secure
|
||||
Boot relies on for trust.
|
||||
|
||||
|
||||
#. Disable signature checking for the kernel by modifying the kernel boot
|
||||
@@ -109,45 +98,46 @@ Loading kernel modules
|
||||
However, out-of-tree modules break this chain of trust so this mechanism
|
||||
needs to be disabled.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir -p /etc/kernel/cmdline.d
|
||||
echo "module.sig_unenforce" | sudo tee /etc/kernel/cmdline.d/allow-unsigned-modules.conf
|
||||
sudo mkdir -p /etc/kernel/cmdline.d
|
||||
echo "module.sig_unenforce" | sudo tee /etc/kernel/cmdline.d/allow-unsigned-modules.conf
|
||||
|
||||
#. Update the boot manager and reboot the system to implement the changed
|
||||
kernel parameters.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo clr-boot-manager update
|
||||
sudo reboot
|
||||
|
||||
.. note::
|
||||
The :command:`clr-boot-manager update` command does not return any console output if success.
|
||||
.. note::
|
||||
|
||||
:command:`clr-boot-manager update` does not return any
|
||||
console output if successful.
|
||||
|
||||
|
||||
#. After rebooting, out-of-tree modules can be manually loaded with
|
||||
:command:`insmod` command.
|
||||
:command:`insmod`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo insmod ${path_to_module}
|
||||
.. code-block:: bash
|
||||
|
||||
sudo insmod ${path_to_module}
|
||||
|
||||
|
||||
Optional: Use `modprobe` to specify module options and aliases
|
||||
--------------------------------------------------------------
|
||||
|
||||
The :command:`modprobe` command can be used to load a module and set options.
|
||||
Use :command:`modprobe` to load a module and set options.
|
||||
|
||||
Because :command:`modprobe` can add or remove more than one module, due to
|
||||
modules having dependencies, a method of specifying what options are
|
||||
to be used with individual modules is useful. This can be done with
|
||||
configuration files under the :file:`/etc/modprobe.d` directory.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /etc/modprobe.d
|
||||
sudo mkdir /etc/modprobe.d
|
||||
|
||||
All files underneath the :file:`/etc/modprobe.d` directory
|
||||
which end with the :file:`.conf` extension specify module options to use when
|
||||
@@ -157,11 +147,9 @@ special requirements.
|
||||
|
||||
You can find more info on module loading in the modprobe.d manual page:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
man modprobe.d
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
man modprobe.d
|
||||
|
||||
Optional: Configure kernel modules to load at boot
|
||||
--------------------------------------------------
|
||||
@@ -169,27 +157,19 @@ Optional: Configure kernel modules to load at boot
|
||||
The :file:`/etc/modules-load.d` configuration directory can be used to
|
||||
specify kernel modules that should be automatically loaded at boot.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /etc/modules-load.d
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /etc/modules-load.d
|
||||
|
||||
All files underneath the :file:`/etc/modules-load.d` directory
|
||||
which end with the :file:`.conf` extension contain a list of module names
|
||||
of aliases (one per line) to load at boot.
|
||||
|
||||
|
||||
You can find more info on module loading in the modules-load.d manual page:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
man modules-load.d
|
||||
|
||||
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
man modules-load.d
|
||||
|
||||
.. _`on GitHub`: https://github.com/clearlinux/distribution
|
||||
.. _`mixer tool`: https://clearlinux.org/features/mixer-tool
|
||||
|
||||
.. _`mixer tool`: https://clearlinux.org/features/mixer-tool
|
||||
Reference in New Issue
Block a user