Add documentation for building and running SOF under Zephyr

SOF can be built as a Zephyr application. This document describes
the process.

Signed-off-by: Guennadi Liakhovetski <[email protected]>

getting_started/build-guide/build-with-zephyr.rst

@@ -0,0 +1,92 @@
+.. _build-with-zephyr:
+
+Build SOF with `Zephyr <https://zephyrproject.org/>`__
+#####################
+
+.. contents::
+   :local:
+   :depth: 3
+
+This guide describes the process of building and running |SOF| as a Zephyr
+application.
+
+.. note::
+
+    The example uses ``$ZEPHYR_WORKSPACE`` as the working directory.
+
+Preparation
+***********
+
+The easiest way to build Zephyr is by using its recommended toolchain. Follow
+instructions in the
+`Install a Toolchain <https://docs.zephyrproject.org/latest/getting_started/index.html#install-a-toolchain>`__
+guide for toolchain installation details.
+
+Check out and build
+*******************
+
+Zephyr uses ``west`` as a source management and building system. Follow the
+Zephyr
+`Getting Started <https://docs.zephyrproject.org/latest/getting_started/index.html#>`__
+guide for dependencies and for ``west`` installation.
+
+Initialize a new ``west`` repository
+
+.. code-block:: bash
+
+    mkdir $ZEPHYR_WORKSPACE
+    cd $ZEPHYR_WORKSPACE
+    west init
+    west update
+
+.. note::
+
+    ``west init`` with no additional parameters configures a new repository with
+    the default Zephyr repository and branch. However, at the moment the SOF
+    integration into Zephyr isn't yet complete, therefore an alternative
+    repository has to be cloned:
+
+.. code-block:: bash
+
+    west init --manifest-url https://github.com/andyross/zephyr --manifest-rev sof-rebased-22Oct20
+
+    Some additional work is also required in the SOF directory:
+
+.. code-block:: bash
+
+    pushd modules/audio/sof
+    git clone --recurse-submodules https://github.com/thesofproject/rimage.git
+    mkdir rimage/build
+    cd rimage/build
+    cmake ..
+    make
+    sudo make install
+    popd
+
+This checks out all the Zephyr sources, including SOF and rimage, builds and
+installs rimage. After that a firmware image can be built and signed:
+
+.. code-block:: bash
+
+    west build -p -d build-apl -b up_squared_adsp zephyr/samples/audio/sof/ -- -DCMAKE_C_FLAGS=-I$(pwd)/zephyr/lib/libc/minimal/include/
+    west sign -d build-apl -t rimage -- -k modules/audio/sof/keys/otc_private_key.pem
+
+.. note::
+
+    If you need a different SOF version than the one automatically checked out
+    by ``west``, you can change to ``modules/audio/sof`` and use ``git`` to
+    select your preferred version. You need at least version 1.6 to use it with
+    ``Zephyr``.
+
+Running
+*******
+
+After the above a firmware image is located at ``build-apl/zephyr/zephyr.ri``,
+as usual it can be copied to the usual location on the target systen, e.g. if
+built natively
+
+.. code-block:: bash
+
+    sudo cp build-apl/zephyr/zephyr.ri /lib/firmware/intel/sof/community/sof-cnl.ri
+
+For firmware log extraction use zephyr/boards/xtensa/up_squared_adsp/tools/logtool.py

getting_started/index.rst

@@ -19,6 +19,7 @@ is always preffered.
    build-guide/build-from-scratch
    build-guide/build-with-docker
    build-guide/build-3rd-party-toolchain
+   build-guide/build-with-zephyr
 
 Setting up SOF on hardware
 **************************