boards/mtk_adsp: Add a doc page
Simple docs for this board family. Not a lot of complexity currently. Signed-off-by: Andy Ross <andyross@google.com>
This commit is contained in:
Andy Ross
Benjamin Cabé
parent
5364783ba1
commit
2b8d542815
1 changed files with 166 additions and 0 deletions
166
boards/mediatek/index.rst
Normal file
166
boards/mediatek/index.rst
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
.. _boards-mtk_adsp:
|
||||
|
||||
Mediatek Audio DSPs
|
||||
###################
|
||||
|
||||
Zephyr can be built and run on the Audio DSPs included in various
|
||||
members of the Mediatek MT8xxx series of ARM SOCs used in Chromebooks
|
||||
from various manufacturers.
|
||||
|
||||
Two of these DSPs are in the market already, implemented via the
|
||||
MT8195 ("Kompanio 1380") and MT8186 ("Kompanio 520") SOCs.
|
||||
Development has been done on and validation performed on at least
|
||||
these devices, though more exist:
|
||||
|
||||
====== ============= =================================== =================
|
||||
SOC Product Name Example Device ChromeOS Codename
|
||||
====== ============= =================================== =================
|
||||
MT8195 Kompanio 1380 HP Chromebook x360 13b dojo
|
||||
MT8186 Kompanio 520 Lenovo 300e Yoga Chromebook Gen 4 steelix
|
||||
====== ============= =================================== =================
|
||||
|
||||
Hardware
|
||||
********
|
||||
|
||||
These devices are Xtensa DSP cores, very similar to the Intel ADSP
|
||||
series in concept (with the notable difference that these are all
|
||||
single-core devices, no parallel SMP is available, but at the same
|
||||
time there are fewer worries about the incoherent cache).
|
||||
|
||||
Their memory space is split between dedicated, fast SRAM and ~16MB of
|
||||
much slower system DRAM. Zephyr currently loads and links into the
|
||||
DRAM area, a convention it inherits from SOF (these devices have
|
||||
comparatively large caches which are used for all accesses, unlike
|
||||
with intel_adsp). SRAM is used for interrupt vectors and stacks,
|
||||
currently.
|
||||
|
||||
There is comparatively little on-device hardware. The architecture is
|
||||
that interaction with the off-chip audio hardware (e.g. I2S codecs,
|
||||
DMIC inputs, etc...) is managed by the host kernel. The DSP receives
|
||||
its data via a single array of custom DMA controllers.
|
||||
|
||||
Beyond that the Zephyr-visible hardware is limited to a bounty of
|
||||
timer devices (of which Zephyr uses two), and a "mailbox"
|
||||
bidirectional interrupt source it uses to communicate with the host
|
||||
kernel.
|
||||
|
||||
Programming and Debugging
|
||||
*************************
|
||||
|
||||
These devices work entirely in RAM, so there is no "flash" process as
|
||||
such. Their memory state is initialized by the host Linux
|
||||
environment. This process works under the control of a
|
||||
``mtk_adsp_load.py`` python script, which has no dependencies outside
|
||||
the standard library and can be run (as root, of course) on any
|
||||
reasonably compatible Linux environment with a Python 3.8 or later
|
||||
interpreter. A chromebook in development mode with the dev packages
|
||||
installed works great. See the ChromiumOS developer library for more
|
||||
detail:
|
||||
|
||||
* `Developer mode <https://www.chromium.org/chromium-os/developer-library/guides/device/developer-mode/>`__
|
||||
* `Dev-Install: Installing Developer and Test packages onto a Chrome OS device <https://www.chromium.org/chromium-os/developer-library/guides/device/install-software-on-base-images/>`__
|
||||
|
||||
Once you have the device set up, the process is as simple as copying
|
||||
the ``zephyr.img`` file from the build directory to the device
|
||||
(typically via ssh) and running it with the script. For example for
|
||||
my mt8186 device named "steelix":
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
user@dev_host:~$ west build -b mt8186//adsp samples/hello_world
|
||||
...
|
||||
... # build output
|
||||
...
|
||||
user@dev_host:~$ scp build/zephyr/zephyr.img root@steelix:
|
||||
user@dev_host:~$ scp soc/mediatek/mt8xxx/mtk_adsp_load.py root@steelix:
|
||||
user@dev_host:~$ ssh steelix
|
||||
|
||||
root@steelix:~ # ./mtk_adsp_load.py load zephyr.img
|
||||
*** Booting Zephyr OS build v3.6.0-5820-gd2a89b3c089e ***
|
||||
Hello World! mt8186_adsp/mt8186_adsp
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
Given the limited I/O facilities, debugging support remains limited on
|
||||
these platforms. Users with access to hardware-level debug and trace
|
||||
tools (e.g. from Cadence) will be able to use them as-is. Zephyr
|
||||
debugging itself is limited to printk/logging techniques at the
|
||||
moment. In theory a bidirectional console like winstream can be used
|
||||
with gdb_stub, which has support on Xtensa and via the SDK debuggers,
|
||||
but this is still unintegrated.
|
||||
|
||||
Toolchains
|
||||
**********
|
||||
|
||||
The MT8195 toolchain is already part of the Zephyr SDK, so builds for
|
||||
the ``mt8195//adsp`` board should work out of the box simply following
|
||||
the generic Zephyr build instructions in the Getting Started guide.
|
||||
|
||||
The MT8186 toolchain is not, and given the proliferation of Xtensa
|
||||
toolchains in the SDK may not be. The overlay files for the device
|
||||
are maintained by the SOF project, however, and building a toolchain
|
||||
yourself using crosstools-ng is not difficult or time-consuming. This
|
||||
script should work for most users:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
#!/bin/sh
|
||||
|
||||
TC=mtk_mt818x_adsp
|
||||
|
||||
# Grab source (these are small)
|
||||
git clone https://github.com/crosstool-ng/crosstool-ng
|
||||
git clone https://github.com/thesofproject/xtensa-overlay
|
||||
|
||||
# Build ct-ng itself
|
||||
cd crosstool-ng
|
||||
./bootstrap
|
||||
./configure --enable-local
|
||||
make -j$(nproc)
|
||||
|
||||
mkdir overlays
|
||||
(cd overlays; ln -s ../../xtensa-overlay/xtensa_mt8186.tar.gz xtensa_${TC}.tar.gz)
|
||||
|
||||
# Construct a .config file
|
||||
cat >.config <<EOF
|
||||
CT_CONFIG_VERSION="3"
|
||||
CT_EXPERIMENTAL=y
|
||||
CT_OVERLAY_LOCATION="overlays"
|
||||
CT_OVERLAY_NAME="${TC}"
|
||||
CT_ARCH_XTENSA=y
|
||||
CT_XTENSA_CUSTOM=y
|
||||
CT_TARGET_VENDOR="${TC}_zephyr"
|
||||
CT_TARGET_CFLAGS="-ftls-model=local-exec"
|
||||
CT_CC_GCC_CONFIG_TLS=n
|
||||
CT_GDB_CROSS_EXTRA_CONFIG_ARRAY="--enable-xtensa-use-target-regnum --disable-xtensa-remote-g-packet"
|
||||
EOF
|
||||
|
||||
# Build
|
||||
./ct-ng olddefconfig
|
||||
./ct-ng build.$(nproc)
|
||||
|
||||
After this completes, you will find your toolchain in ``~/x-tools``
|
||||
and can use it to build by setting it as your Zephyr cross compiler:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export CROSS_COMPILE=$HOME/x-tools/xtensa-mtk_mt818x_adsp_zephyr-elf/bin/xtensa-mtk_mt818x_adsp_zephyr-elf-
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
||||
|
||||
Closed-source Tools
|
||||
===================
|
||||
|
||||
Zephyr can also be built by the proprietary Cadence xcc and xt-clang
|
||||
toolchains. Support for those tools is beyond the scope of this
|
||||
document, but it works similarly, by specifying your toolchain and
|
||||
core identities and paths via the environment, for example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export XTENSA_TOOLS_ROOT=/path/to/XtDevTools
|
||||
export XTENSA_CORE=hifi5_7stg_I64D128
|
||||
export TOOLCHAIN_VER=RI-2021.6-linux
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=xt-clang
|
||||
export XTENSA_TOOLCHAIN_PATH=$XTENSA_TOOLS_ROOT/install/tools
|
||||
west build -b mt8186_adsp samples/hello_world
|
||||
Loading…
Add table
Add a link
Reference in a new issue