From 03b01078291e2859f7b4a4e1ae2d0b32ff223483 Mon Sep 17 00:00:00 2001 From: Kevin Putnam Date: Tue, 27 Nov 2018 10:55:03 -0800 Subject: [PATCH] Updates to titles and content --- .../guides/maintenance/kernel-modules.rst | 132 ++++++++---------- 1 file changed, 56 insertions(+), 76 deletions(-) diff --git a/source/clear-linux/guides/maintenance/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst index 92623caf..569db618 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules.rst @@ -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 \ No newline at end of file