1.. _boards-mtk_adsp:
2
3Mediatek Audio DSPs
4###################
5
6Zephyr can be built and run on the Audio DSPs included in various
7members of the Mediatek MT8xxx series of ARM SOCs used in Chromebooks
8from various manufacturers.
9
10Two of these DSPs are in the market already, implemented via the
11MT8195 ("Kompanio 1380") and MT8186 ("Kompanio 520") SOCs.
12Development has been done on and validation performed on at least
13these devices, though more exist:
14
15  ======  =============  ===================================  =================
16  SOC     Product Name   Example Device                       ChromeOS Codename
17  ======  =============  ===================================  =================
18  MT8195  Kompanio 1380  HP Chromebook x360 13b               dojo
19  MT8186  Kompanio 520   Lenovo 300e Yoga Chromebook Gen 4    steelix
20  ======  =============  ===================================  =================
21
22Hardware
23********
24
25These devices are Xtensa DSP cores, very similar to the Intel ADSP
26series in concept (with the notable difference that these are all
27single-core devices, no parallel SMP is available, but at the same
28time there are fewer worries about the incoherent cache).
29
30Their memory space is split between dedicated, fast SRAM and ~16MB of
31much slower system DRAM.  Zephyr currently loads and links into the
32DRAM area, a convention it inherits from SOF (these devices have
33comparatively large caches which are used for all accesses, unlike
34with intel_adsp).  SRAM is used for interrupt vectors and stacks,
35currently.
36
37There is comparatively little on-device hardware.  The architecture is
38that interaction with the off-chip audio hardware (e.g. I2S codecs,
39DMIC inputs, etc...) is managed by the host kernel.  The DSP receives
40its data via a single array of custom DMA controllers.
41
42Beyond that the Zephyr-visible hardware is limited to a bounty of
43timer devices (of which Zephyr uses two), and a "mailbox"
44bidirectional interrupt source it uses to communicate with the host
45kernel.
46
47Programming and Debugging
48*************************
49
50These devices work entirely in RAM, so there is no "flash" process as
51such.  Their memory state is initialized by the host Linux
52environment.  This process works under the control of a
53``mtk_adsp_load.py`` python script, which has no dependencies outside
54the standard library and can be run (as root, of course) on any
55reasonably compatible Linux environment with a Python 3.8 or later
56interpreter.  A chromebook in development mode with the dev packages
57installed works great.  See the ChromiumOS developer library for more
58detail:
59
60* `Developer mode <https://www.chromium.org/chromium-os/developer-library/guides/device/developer-mode/>`__
61* `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/>`__
62
63Once you have the device set up, the process is as simple as copying
64the ``zephyr.img`` file from the build directory to the device
65(typically via ssh) and running it with the script.  For example for
66my mt8186 device named "steelix":
67
68.. code-block:: console
69
70   user@dev_host:~$ west build -b mt8186//adsp samples/hello_world
71   ...
72   ... # build output
73   ...
74   user@dev_host:~$ scp build/zephyr/zephyr.img root@steelix:
75   user@dev_host:~$ scp soc/mediatek/mt8xxx/mtk_adsp_load.py root@steelix:
76   user@dev_host:~$ ssh steelix
77
78   root@steelix:~ # ./mtk_adsp_load.py load zephyr.img
79   *** Booting Zephyr OS build v3.6.0-5820-gd2a89b3c089e ***
80   Hello World! mt8186_adsp/mt8186_adsp
81
82Debugging
83=========
84
85Given the limited I/O facilities, debugging support remains limited on
86these platforms.  Users with access to hardware-level debug and trace
87tools (e.g. from Cadence) will be able to use them as-is.  Zephyr
88debugging itself is limited to printk/logging techniques at the
89moment.  In theory a bidirectional console like winstream can be used
90with gdb_stub, which has support on Xtensa and via the SDK debuggers,
91but this is still unintegrated.
92
93Toolchains
94**********
95
96The MT8195 toolchain is already part of the Zephyr SDK, so builds for
97the ``mt8195//adsp`` board should work out of the box simply following
98the generic Zephyr build instructions in the Getting Started guide.
99
100The MT8186 toolchain is not, and given the proliferation of Xtensa
101toolchains in the SDK may not be.  The overlay files for the device
102are maintained by the SOF project, however, and building a toolchain
103yourself using crosstools-ng is not difficult or time-consuming.  This
104script should work for most users:
105
106.. code-block:: shell
107
108   #!/bin/sh
109
110   TC=mtk_mt818x_adsp
111
112   # Grab source (these are small)
113   git clone https://github.com/crosstool-ng/crosstool-ng
114   git clone https://github.com/thesofproject/xtensa-overlay
115
116   # Build ct-ng itself
117   cd crosstool-ng
118   ./bootstrap
119   ./configure --enable-local
120   make -j$(nproc)
121
122   mkdir overlays
123   (cd overlays; ln -s ../../xtensa-overlay/xtensa_mt8186.tar.gz xtensa_${TC}.tar.gz)
124
125   # Construct a .config file
126   cat >.config <<EOF
127   CT_CONFIG_VERSION="3"
128   CT_EXPERIMENTAL=y
129   CT_OVERLAY_LOCATION="overlays"
130   CT_OVERLAY_NAME="${TC}"
131   CT_ARCH_XTENSA=y
132   CT_XTENSA_CUSTOM=y
133   CT_TARGET_VENDOR="${TC}_zephyr"
134   CT_TARGET_CFLAGS="-ftls-model=local-exec"
135   CT_CC_GCC_CONFIG_TLS=n
136   CT_GDB_CROSS_EXTRA_CONFIG_ARRAY="--enable-xtensa-use-target-regnum --disable-xtensa-remote-g-packet"
137   EOF
138
139   # Build
140   ./ct-ng olddefconfig
141   ./ct-ng build.$(nproc)
142
143After this completes, you will find your toolchain in ``~/x-tools``
144and can use it to build by setting it as your Zephyr cross compiler:
145
146.. code-block:: shell
147
148   export CROSS_COMPILE=$HOME/x-tools/xtensa-mtk_mt818x_adsp_zephyr-elf/bin/xtensa-mtk_mt818x_adsp_zephyr-elf-
149   export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
150
151Closed-source Tools
152===================
153
154Zephyr can also be built by the proprietary Cadence xcc and xt-clang
155toolchains.  Support for those tools is beyond the scope of this
156document, but it works similarly, by specifying your toolchain and
157core identities and paths via the environment, for example:
158
159.. code-block:: shell
160
161   export XTENSA_TOOLS_ROOT=/path/to/XtDevTools
162   export XTENSA_CORE=hifi5_7stg_I64D128
163   export TOOLCHAIN_VER=RI-2021.6-linux
164   export ZEPHYR_TOOLCHAIN_VARIANT=xt-clang
165   export XTENSA_TOOLCHAIN_PATH=$XTENSA_TOOLS_ROOT/install/tools
166   west build -b mt8186_adsp samples/hello_world
167