feat(getting_started): update organization and instructions

- Change the organization of the getting started section to make it
easier to determine which guide to follow.
- Add instructions for building a custom kernel with SOF config so that
it can be booted on that same device. This is useful for people
without dedicated test hardware who just want to try out the latest
code, such as when they are running into issues with new hardware.
- Revamp the ktest setup documentation. This was very out of date and
had tons of errors, especially for using Fedora. It has now been validated
to work on both Fedora and Ubuntu target devices, from a Ubuntu dev
machine (but Fedora should work just fine too).

Signed-off-by: Noah Klayman <[email protected]>

getting_started/index.rst

@@ -21,18 +21,36 @@ current distro release is always preferred.
    build-guide/build-3rd-party-toolchain
    build-guide/build-with-zephyr
 
-Set up SOF on hardware
-**********************
+Set up SOF on a Linux machine
+*****************************
 
-SOF runs on a variety of devices with varying audio capabilities so
-instructions may differ between devices.
+You can build the Linux kernel with the latest SOF code and install it locally or remotely with ktest. 
+
+Do this first:
+
+.. toctree::
+   :maxdepth: 1
+
+   setup_linux/prepare_build_environment
+
+Then proceed based on if you are installing locally or through ktest:
+
+.. toctree::
+   :maxdepth: 1
+
+   setup_linux/install_locally
+   setup_linux/setup_ktest_environment
+
+Set up SOF on a special device
+******************************
+
+SOF also runs on the MinnowBoard Turbot and the Up Squared board with Hifiberry Dac+.
 
 .. toctree::
    :maxdepth: 1
 
-   setup/setup_minnowboard_turbot
-   setup/setup_up_2_board
-   setup/setup_ktest_environment
+   setup_special_device/setup_minnowboard_turbot
+   setup_special_device/setup_up_2_board
 
 Debug Audio issues on Intel platforms
 *************************************

getting_started/setup_linux/install_locally.rst

@@ -0,0 +1,109 @@
+.. _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
+
+   # This will copy the booted kernel's configuration so that it will be used as a base
+   cp /boot/config-$(uname -r)* .config
+
+
+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
+
+   # For most users
+   ../kconfig/kconfig-distro-sof-update.sh
+   # For additional logging and experimental device support
+   ../kconfig/kconfig-distro-sof-dev-update.sh
+
+3. Compile the kernel
+---------------------
+
+.. code-block:: bash
+
+   # The first time you run this it can take a while (over 30 minutes on some machines),
+   # so grab a coffee or take an exercise break while it runs
+   make -j$(nproc --all)
+
+4. Install the kernel
+---------------------
+
+.. code-block:: bash
+
+   sudo make modules_install
+   sudo make install
+
+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
+
+   git pull
+   # You should run this after switching branches or configuration or any other major code change
+   # If you just pulled some minor updates, it's likely unnecessary and will increase your build time
+   make clean
+
+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
+
+   cd ..
+   # Delete the old folder before starting over
+   rm -rf linux
+
+6. Removing the kernel
+----------------------
+
+If you run into issues or no longer need the custom kernel, you can remove it.
+
+Ubuntu:
+
+.. code-block:: bash
+
+   cd ~/sof/linux
+   sudo rm /boot/*-$(make kernelversion)
+   sudo rm -rf /lib/modules/$(make kernelversion)
+   sudo update-grub
+
+Fedora:
+
+.. code-block:: bash
+
+   cd ~/sof/linux
+   sudo rm /boot/*-$(make kernelversion)*
+   sudo rm -rf /lib/modules/$(make kernelversion)
+   sudo grubby --remove-kernel=/boot/vmlinuz-$(make kernelversion)
+
+
+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.

getting_started/setup_linux/prepare_build_environment.rst

@@ -0,0 +1,102 @@
+.. _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
+
+   export SOF_WORKSPACE=~/work/sof
+   mkdir -p $SOF_WORKSPACE
+   cd $SOF_WORKSPACE
+
+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
+
+   sudo dnf install fedpkg
+   fedpkg clone -a kernel
+   cd kernel
+   sudo dnf builddep kernel.spec
+   sudo dnf install ccache
+   cd ..
+
+Ubuntu (see `their page <https://wiki.ubuntu.com/Kernel/BuildYourOwnKernel>`_ for details):
+
+.. code-block:: bash
+
+   sudo apt update
+   sudo apt install git libncurses-dev gawk flex bison openssl libssl-dev dkms libelf-dev libudev-dev libpci-dev libiberty-dev autoconf dwarves zstd
+
+4. Download the configuration scripts
+-------------------------------------
+
+.. code-block:: bash
+
+   git clone https://github.com/thesofproject/kconfig.git
+
+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
+
+   # If a maintainer requests that you check out a different branch
+   # to test a bug fix, add -b [branch]
+   # to the end of this command, where [branch] is the branch name
+   git clone https://github.com/thesofproject/linux.git --depth=1
+   cd linux
+
+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
+
+   cd ~/Downloads
+   unzip linux-*.zip -d $SOF_WORKSPACE
+   cd $SOF_WORKSPACE
+   mv linux-* linux
+   cd linux
+
+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