From 2b8d54281507882c3a5d332c82596ab2724b51c2 Mon Sep 17 00:00:00 2001 From: Andy Ross Date: Sat, 15 Jun 2024 09:33:50 -0700 Subject: [PATCH] boards/mtk_adsp: Add a doc page Simple docs for this board family. Not a lot of complexity currently. Signed-off-by: Andy Ross --- boards/mediatek/index.rst | 166 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 boards/mediatek/index.rst diff --git a/boards/mediatek/index.rst b/boards/mediatek/index.rst new file mode 100644 index 00000000000..4c41e0b4d86 --- /dev/null +++ b/boards/mediatek/index.rst @@ -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 `__ +* `Dev-Install: Installing Developer and Test packages onto a Chrome OS device `__ + +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 <