.. _install-locally:

Install the Kernel locally

.. contents::

:local:

:depth: 3

Introduction

Make sure you have `setup your development environment <prepare_build_environment.html>`_ before following these steps. This page will guide you through the process of installing the kernel locally on your machine. It will be installed in addition to your distro's default kernel so that you can always change back to that in case something goes wrong. If you're interested in learning more about this process there's lots of online guides available, for example `Fedora's guide <https://docs.fedoraproject.org/en-US/quick-docs/kernel/build-custom-kernel/#_building_a_vanilla_upstream_kernel>`_ or `this wiki page <https://wiki.linuxquestions.org/wiki/How_to_build_and_install_your_own_Linux_kernel>`_.

Build and install the kernel

(You should be in the ``~/sof/linux`` directory you created on the setup page)

1. Load base kernel configuration

.. code-block:: bash

2. Apply SOF-specific configuration

The following scripts will update your base config so that it uses the latest SOF modules. Run only one of them depending on your needs. If it prompts you with any questions, just press <enter> to accept the default value. Note that, by default, these scripts will set the configuration to only compile modules that are currently loaded in order to lower compile times. This means that when you've booted from the custom kernel some external devices may not work if they weren't connected while running this script. If you want to compile all modules, delete the line ``make localmodconfig`` from the script you will run in this step.

.. code-block:: bash

3. Compile the kernel

.. code-block:: bash

4. Install the kernel

.. code-block:: bash

If all went well, your freshly-built kernel will be installed and available at next boot. Restart your computer, and you should have the option to pick a kernel when it turns on. Select the kernel that has "-sof" at the end of it, and your computer should boot as normal using the kernel you just built. On Ubuntu, the kernel option may be hidden behind the "Advanced options for Ubuntu" submenu.

5. Updating and rebuilding

If you need to try some new changes, you'll have to download the updated code and rebuild the kernel.

If you originally cloned the repo using git, you just need to pull the changes:

.. code-block:: bash

Now, repeat steps 3 and 4 to rebuild and reinstall the kernel. Reboot your computer, and select the kernel with -sof at the end to test it.

Unfortunately, if you downloaded via zip, the entire process has to be restarted from the "Get the kernel source" section; there's no good way to incrementally update. However, the kernel build should be faster now as part of it will be cached.

.. code-block:: bash

6. Removing the kernel

If you run into issues or no longer need the custom kernel, you can remove it.

Ubuntu:

.. code-block:: bash

Fedora:

.. code-block:: bash

After rebooting, you should be back to your old kernel with all traces of the custom kernel installation gone. If you'd like, you can also delete the ``~sof`` directory to save disk space.

.. _prepare-build-environment:

Set up a development environment to build the kernel

.. contents::

:local:

:depth: 3

Introduction

These instructions will help you set up a development environment for the SOF branch of the Linux kernel. If you have dedicated test hardware you can use ktest to install it over ssh, otherwise you can install it locally on your device in addition to your default kernel.

Prerequisites

1. Device requirements

**Development device:** PC running Fedora 35+ or Ubuntu 20.04+.

**Target device:** PC running Fedora 35+ or Ubuntu 20.04+, with secure boot disabled. If the target device is different than the development device you must be able to ssh into the target, which is typically on the same local network/VPN.

2. Create working directory

This directory can be located anywhere, simply change the ``SOF_WORKSPACE`` variable if you would like to store your sources somewhere else.

.. code-block:: bash

3. Install kernel build dependencies

Fedora (see `their guide <https://docs.fedoraproject.org/en-US/quick-docs/kernel/build-custom-kernel/#_get_the_dependencies>`_ for details):

.. code-block:: bash

Ubuntu (see `their page <https://wiki.ubuntu.com/Kernel/BuildYourOwnKernel>`_ for details):

.. code-block:: bash

4. Download the configuration scripts

.. code-block:: bash

Get the kernel source

There are two ways to get the kernel source. We strongly recommend using git as it makes updates **much** easier, but the zip download may be more successful if you have an unstable connection.

Option 1: Clone with git

.. code-block:: bash

Option 2: Download via zip

Visit the SOF Linux fork at https://github.com/thesofproject/linux. If a maintainer asks you to test a specific branch, click the dropdown with the text "topic/sof-dev" and select the branch they asked you to test. Then, click the green "Code" dropdown and select "download zip". Once it's downloaded, extract it to the directory you created in the previous step:

.. code-block:: bash

Build the kernel

Your device should now be ready to configure and build the kernel. How to proceed depends on if you are installing locally or on dedicated test hardware.

.. toctree::

:maxdepth: 1

install_locally

setup_ktest_environment