mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-22 03:22:45 +00:00
Merge pull request #313 from puneetse/add/ps-custom-kernel-modules
Add kernel modules documentation
This commit is contained in:
@@ -0,0 +1,176 @@
|
||||
.. _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 directly from a vendor (out-of-tree).
|
||||
|
||||
In cases where drivers beyond those enabled by default in |CL-ATTR| are
|
||||
needed it may be necessary to:
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 1
|
||||
:backlinks: top
|
||||
|
||||
Check if the module is available through |CL|
|
||||
=============================================
|
||||
|
||||
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.
|
||||
|
||||
|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|
|
||||
===================================
|
||||
|
||||
If the kernel module you need is already open source
|
||||
(e.g. in the Linux upstream) and likely to be useful to others,
|
||||
consider submitting a request to add or enable in the |CL| kernel.
|
||||
|
||||
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|.
|
||||
|
||||
You can build and load out-of-tree kernel modules, however you must:
|
||||
|
||||
* disable secure boot
|
||||
* disable kernel module integrity checking
|
||||
* build the module against new versions of the Linux kernel
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
$ 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
|
||||
|
||||
sudo swupd bundle-add linux-dev
|
||||
|
||||
#. Follow instructions from the kernel module source code to compile the
|
||||
kernel module.
|
||||
|
||||
|
||||
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 signature checking for the kernel by modifying the kernel boot
|
||||
parameters and reboot the system.
|
||||
|
||||
All kernel modules from |CL| have been signed to enforce kernel security.
|
||||
However, out-of-tree modules break this chain of trust so this mechanism
|
||||
needs to be disabled.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
|
||||
sudo clr-boot-manager update
|
||||
sudo reboot
|
||||
|
||||
.. 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`.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo insmod ${path_to_module}
|
||||
|
||||
|
||||
Optional: Use `modprobe` to specify module options and aliases
|
||||
--------------------------------------------------------------
|
||||
|
||||
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
|
||||
|
||||
sudo mkdir /etc/modprobe.d
|
||||
|
||||
All files underneath the :file:`/etc/modprobe.d` directory
|
||||
that end with the :file:`.conf` extension specify module options to use when
|
||||
loading. This can also be used to create convenient aliases for modules or
|
||||
they can override the normal loading behavior altogether for those with
|
||||
special requirements.
|
||||
|
||||
You can find more info on module loading in the modprobe.d manual page:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
man modprobe.d
|
||||
|
||||
Optional: Configure kernel modules to load at boot
|
||||
--------------------------------------------------
|
||||
|
||||
Use the :file:`/etc/modules-load.d` configuration directory to
|
||||
specify kernel modules to load automatically at boot.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /etc/modules-load.d
|
||||
|
||||
All files underneath the :file:`/etc/modules-load.d` directory
|
||||
that 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
|
||||
|
||||
.. _`on GitHub`: https://github.com/clearlinux/distribution
|
||||
.. _`mixer tool`: https://clearlinux.org/features/mixer-tool
|
||||
@@ -15,6 +15,7 @@ completed.
|
||||
enable-user-space
|
||||
swupd-guide
|
||||
bulk-provision
|
||||
kernel-modules
|
||||
mixer
|
||||
mixin
|
||||
validate-signatures
|
||||
|
||||
Reference in New Issue
Block a user