boards: intel_adsp: unify and update docs

Unifies docs into one updated guide with stubs for each platform.

Signed-off-by: Lauren Murphy <[email protected]>

boards/xtensa/index.rst

@@ -7,4 +7,4 @@ XTENSA Boards
    :maxdepth: 1
    :glob:
 
-   **/*
+   **/index

boards/xtensa/intel_adsp_ace15_mtpm/doc/index.rst

@@ -0,0 +1,35 @@
+.. _intel_adsp_ace15:
+
+Intel ADSP ACE 1.5
+##################
+
+Overview
+********
+
+This board configuration is used to run Zephyr on the Intel ACE 1.5 Audio DSP.
+This configuration is present, for example, on Intel Meteor Lake microprocessors.
+Refer to :ref:`intel_adsp_generic` for more details on Intel ADSP ACE and CAVS.
+
+System requirements
+*******************
+
+Xtensa Toolchain
+----------------
+
+If you choose to build with the Xtensa toolchain instead of the Zephyr SDK, set
+the following environment variables specific to the board in addition to the
+Xtensa toolchain environment variables listed in :ref:`intel_adsp_generic`.
+
+.. code-block:: shell
+
+   export ZEPHYR_TOOLCHAIN_VARIANT=xt-clang
+   export TOOLCHAIN_VER=RI-2021.7-linux
+   export XTENSA_CORE=ace10_LX7HiFi4
+
+For older versions of the toolchain, set the toolchain variant to ``xcc``.
+
+Programming and Debugging
+*************************
+
+Refer to :ref:`intel_adsp_generic` for generic instructions on programming and
+debugging applicable to all CAVS and ACE platforms.

boards/xtensa/intel_adsp_cavs15/doc/index.rst

@@ -1,156 +1,34 @@
-.. _Up_Squared_Audio_DSP:
+.. _intel_adsp_cavs15:
 
-Up Squared Audio DSP
-####################
+Intel ADSP CAVS 1.5
+###################
 
-System Requirements
-*******************
-
-Prerequisites
-=============
-
-The Zephyr SDK 0.11 or higher is required.
-
-Since firmware binary signing for Audio DSP is mandatory on Intel products
-form Skylake onwards the signing tool and key are needed.
-
-``up_squared`` board is running Linux with `SOF Diagnostic Driver`_ built and
-loaded.
-
-Signing tool
-------------
+Overview
+********
 
-rimage is Audio DSP firmware image creation and signing tool. The tool is used
-by `Sound Open Firmware`_ to generate binary firmware signed images.
+This board configuration is used to run Zephyr on the Intel CAVS 1.5 Audio DSP.
+This configuration is present, for example, on Intel `Apollo Lake`_ microprocessors.
+Refer to :ref:`intel_adsp_generic` for more details on Intel ADSP ACE and CAVS.
 
-For the building instructions refer to `rimage Build Instructions`_.
-
-Signing keys
-------------
-
-The key used is Intel Open Source Technology Center (OTC) community key.
-It can be freely used by anyone and intended for firmware developers.
-Please download and store private key from the location:
-https://github.com/thesofproject/sof/blob/master/keys/otc_private_key.pem
+System requirements
+*******************
 
-For more information about keys refer to `rimage keys`_.
+Xtensa Toolchain
+----------------
 
-Setup up_squared board
-----------------------
+If you choose to build with the Xtensa toolchain instead of the Zephyr SDK, set
+the following environment variables specific to the board in addition to the
+Xtensa toolchain environment variables listed in :ref:`intel_adsp_generic`.
 
-To setup Linux on ``up_squared`` board refer to
-`Getting Started with Ubuntu Core on an UP Squared Board`_.
+.. code-block:: shell
 
-After installing Linux build and install `SOF Diagnostic Driver`_.
+   export TOOLCHAIN_VER=RG-2017.8-linux
+   export XTENSA_CORE=X4H3I16w2D48w3a_2017_8
 
 Programming and Debugging
 *************************
 
-Build Zephyr application
-========================
-
-Applications can be build in the usual way (see :ref:`build_an_application`
-for more details). The only additional step required is signing. For example,
-for building ``hello_world`` application following steps are needed.
-
-#. Building Zephyr application ``hello_world``
-
-   .. zephyr-app-commands::
-      :zephyr-app: samples/hello_world
-      :board: intel_adsp_cavs15
-      :goals: build
-
-#. Sign and create firmware image
-
-   .. code-block:: console
-
-      west sign -t rimage -- -k <path to otc_private_key.pem>
-
-Loading image to Audio DSP
-==========================
-
-`SOF Diagnostic Driver`_ provide interface for firmware loading. Python tools
-in the board support directory use the interface to load firmware to ``ADSP``.
-
-Assume that the up_squared board's host name is ``cavs15`` (It also can be an
-ip address), and the user account is ``user``. Then copy the python tool to the
-``up_squared`` board from your build environment::
-
-   $ scp boards/xtensa/intel_adsp/tools/cavstool.py user@cavs15:
-   $ scp boards/xtensa/intel_adsp/tools/remote-fw-service.py user@cavs15:
-
-
-Note that the ``/dev/hda`` device file created by the diagnostic driver must
-be readable and writable by the process.  So we simply by running the
-loader script as root:
-
-.. code-block:: console
-
-   cavs15$ sudo ./remote-fw-service.py
-
-Cavstool_server.py is a daemon which accepts a firmware image from a remote host
-and loads it into the ADSP. After successful firmware download, the daemon also
-sends any log messages or output back to the client.
-
-Running and Debugging
-=====================
-
-While the python script is running on ``up_squared`` board, you can start load
-image and run the application by:
-
-.. code-block:: console
-
-   west flash --remote-host cavs15
-
-or
-
-.. code-block:: console
-
-   west flash --remote-host 192.168.x.x --pty
-
-Then you can see the log message immediately:
-
-.. code-block:: console
-
-   Hello World! intel_adsp_cavs15
-
-
-Integration Testing With Twister
-================================
-
-The ADSP hardware also has integration for testing using the twister
-tool.  The ``cavstool_client.py`` script can be used as the
-``--device-serial-pty`` handler, and the west flash script should take
-a path to the same key file used above.
-
-.. code-block:: console
-
-    ./scripts/twister --device-testing -p intel_adsp_cavs15 \
-      --device-serial-pty $ZEPHYR_BASE/soc/xtensa/intel_adsp/tools/cavstool_client.py,myboard.local,-l \
-      --west-flash "--remote-host=myboard.local"
-
-And if you install the SOF software stack in rather than the default path,
-you also can specify the location of the rimage tool, signing key and the
-toml config, for example:
-
-.. code-block:: console
-
-    ./scripts/twister --device-testing -p intel_adsp_cavs15 \
-      --device-serial-pty $ZEPHYR_BASE/soc/xtensa/intel_adsp/tools/cavstool_client.py,myboard.local,-l \
-      --west-flash "--remote-host=myboard.local,\
-      --rimage-tool=/path/to/rimage_tool,\
-      --key=/path/to/otc_private_key.pem,\
-      --config-dir=/path/to/config_dir"
-
-
-.. target-notes::
-
-.. _Getting Started with Ubuntu Core on an UP Squared Board: https://software.intel.com/en-us/articles/getting-started-with-ubuntu-core-on-an-up-squared-board
-
-.. _SOF Diagnostic Driver: https://github.com/thesofproject/sof-diagnostic-driver
-
-.. _Sound Open Firmware: https://github.com/thesofproject/sof
-
-.. _rimage Build Instructions: https://github.com/thesofproject/rimage#building
+Refer to :ref:`intel_adsp_generic` for generic instructions on programming and
+debugging applicable to all CAVS and ACE platforms.
 
-.. _rimage keys: https://github.com/thesofproject/sof/tree/master/rimage/keys
+.. _Apollo Lake: https://www.intel.com/content/www/us/en/products/platforms/details/apollo-lake.html