1.. _intel_adsp_generic: 2 3Intel ADSP cAVS and ACE 4####################### 5 6Intel's Audio and Digital Signal Processing (ADSP) hardware offerings 7include the Converged Audio Voice Speech (cAVS) series and its successor, 8the Audio and Context Engine (ACE). These Xtensa-based ADSPs can be integrated 9into a variety of Intel products. The below table lists (some of) the Intel 10microprocessor(s) that each version of the Intel ADSP is compatible with. 11 12+----------+-----------------------------+ 13| ADSP | Microprocessor | 14+==========+=============================+ 15| cAVS 1.5 | Apollo Lake | 16+----------+-----------------------------+ 17| cAVS 1.8 | Whiskey Lake | 18+----------+-----------------------------+ 19| cAVS 2.5 | Tiger Lake | 20+----------+-----------------------------+ 21| ACE 1.5 | Meteor Lake | 22+----------+-----------------------------+ 23 24Intel open-sources firmware for its ADSP hardware under the Sound Open Firmware 25(`SOF`_) project. SOF can be built with either Zephyr or Cadence's proprietary 26Xtensa OS (XTOS) and run on a variety of Intel and non-Intel platforms. 27 28The Intel `UP Xtreme`_ product line has the publicly 29available reference boards for Zephyr's Intel ADSP support. This guide uses the 30`UP Xtreme i11-0001 series`_ (:ref:`intel_adsp_cavs25`) board as an example. 31However, the instructions are generic and will work on other boards unless 32otherwise stated. You will be referred to the documentation for your specific 33board in these cases. 34 35System requirements 36******************* 37 38Setting Up Target Board 39----------------------- 40 41You can only flash Zephyr to the ADSP by using Zephyr's Python tool in a Linux 42host running on the board's main CPU. It is possible (and recommended) for users 43to build the binary locally on their development machine and flash remotely, 44but the board itself must be capable of running the Python script that receives 45the binary sent over the network by West and flashes it. You should install a 46version of Linux that supports or comes with the current version of Python that 47Zephyr requires. Consider using Ubuntu 20.04, which comes with Python 3.8 48installed. 49 50Note that if you plan to use SOF on your board, you will need to build and 51install the modified Linux SOF kernel instead of the default kernel. It is 52recommended you follow the `SOF instructions`_ to build and run SOF on Zephyr. 53 54UP Xtreme users can refer to the `UP Community wiki`_ for help installing a 55Linux operating system on their board. 56 57Signing Tool 58------------ 59 60As firmware binary signing is mandatory on Intel products from Skylake onwards, 61you will also need to set up the SOF rimage signing tool and key. 62 63.. code-block:: shell 64 65 cd zephyrproject 66 west config manifest.project-filter -- +sof 67 west update 68 cd modules/audio/sof/tools/rimage 69 70Follow the instructions in the rimage :file:`README.md` to build the tool on 71your system. You can either copy the executable to a directory in your PATH or 72use ``west config rimage.path /path/to/rimage-build/rimage``; see more details 73in the output of ``west sign -h``. Running directly from the build directory 74makes you less likely to use an obsolete rimage version by mistake. 75 76Platform-specific configuration files are located in the ``rimage/config/`` 77subdirectory. For a different configuration directory you can use: 78``west config build.cmake-args -- -DRIMAGE_CONFIG_PATH=/path/to/my/rimage/config``. 79 80 81Xtensa Toolchain (Optional) 82--------------------------- 83 84The Zephyr SDK provides GCC-based toolchains necessary to build Zephyr for 85the cAVS and ACE boards. However, users seeking greater levels of optimization 86may desire to build with the proprietary Xtensa toolchain distributed by 87`Cadence`_ instead. The following instructions assume you have purchased and 88installed the toolchain(s) and core(s) for your board following their 89instructions. 90 91First, make sure to set the ``$HOME/.flexlmrc`` file or 92``XTENSAD_LICENSE_FILE`` variable as instructed by Cadence. 93Next, set the following environment variables: 94 95.. code-block:: shell 96 97 export XTENSA_TOOLCHAIN_PATH=$HOME/xtensa/XtDevTools/install/tools 98 export XTENSA_BUILDS_DIR=$XTENSA_TOOLCHAIN_PATH/../builds 99 export ZEPHYR_TOOLCHAIN_VARIANT=xcc 100 export TOOLCHAIN_VER=RG-2017.8-linux 101 export XTENSA_CORE=cavs2x_LX6HiFi3_2017_8 102 103The bottom three variables are specific to each version of cAVS / ACE; refer to 104your board's documentation for their values. 105 106Programming and Debugging 107************************* 108 109Building 110-------- 111 112Build as usual. 113 114.. zephyr-app-commands:: 115 :zephyr-app: samples/hello_world 116 :board: intel_adsp/cavs25 117 :goals: build 118 119Signing 120------- 121 122``west build`` tries to sign the binary at the end of the build. If you need 123to sign the binary yourself, you can invoke ``west sign`` directly. Read the 124``west`` logs to find the ``west sign`` invocation; you can copy and modify 125the command logged for your own purposes. Run ``west sign -h`` for more 126details. 127 128The build tries to provide as many default rimage parameters are possible. If 129needed, there are several ways to override them depending on your specific 130situation and use case. They're often not mutually exclusive but to avoid 131undocumented rimage precedence rules it's best to use only one way at a time. 132 133- For local, interactive use prefer ``rimage.extra-args`` in west config, see 134 ``west sign -h``. The WEST_CONFIG_LOCAL environment variable can point at a 135 different west configuration file if needed. 136 137- You can add or overwrite a ``$platform.toml`` file(s) in your 138 ``rimage/config/`` directory 139 140- For board-specific needs you can define WEST_SIGN_OPTS in 141 ``boards/my/board/board.cmake``, see example in 142 ``soc/intel/adsp/common/CMakeLists.txt`` 143 144Starting with Zephyr 3.6.0, ``west flash`` does not invoke ``west sign`` 145anymore and you cannot pass rimage parameters to ``west flash`` anymore. To 146see an up-to-date list of all arguments to the Intel ADSP runner, run the 147following after you have built the binary: 148 149.. code-block:: console 150 151 west flash --context 152 153Remote Flashing to cAVS-based ADSP 154---------------------------------- 155 156As mentioned previously, the recommended way to run and monitor the output of 157Zephyr on cAVS boards is remotely. The Linux host on the main CPU may freeze up 158and need to be restarted if a flash or runtime error occurs on the ADSP. From 159this point onward, we will refer to the board as the "remote host" and your 160development machine as the "local host". 161 162Copy the below scripts to the cAVS board. 163:zephyr_file:`soc/intel/intel_adsp/tools/remote-fw-service.py` will receive 164the binary sent over the network by West and invoke 165:zephyr_file:`soc/intel/intel_adsp/tools/cavstool.py` (referred to as the 166"cAVS tool"), which performs the flash and captures the log. Start 167:file:`remote-fw-service.py`. 168 169.. code-block:: console 170 171 scp -r $ZEPHYR_BASE/soc/intel/intel_adsp/tools/cavstool.py username@remotehostname 172 scp -r $ZEPHYR_BASE/soc/intel/intel_adsp/tools/remote-fw-service.py username@remotehostname 173 ssh username@remotehostname 174 sudo ./remote-fw-service.py 175 176:file:`remote-fw-service.py` uses ports 9999 and 10000 on the remote host to 177communicate. It forwards logs collected by :file:`cavstool.py` on port 9999 178(referred to as its "log port") and services requests on port 10000 179(its "requests port"). When you run West or Twister on your local host, 180it sends requests using the :zephyr_file:`soc/intel/intel_adsp/tools/cavstool_client.py` 181script (referred to as "cAVS tool client"). It also uses ports 9999 and 10000 on 182your local host, so be sure those ports are free. 183 184Flashing with West is simple. 185 186.. code-block:: console 187 188 west flash --remote-host remotehostname --pty remotehostname 189 190Running tests with Twister is slightly more complicated. 191 192.. code-block:: console 193 194 twister -p intel_adsp/cavs25 --device-testing --device-serial-pty="$ZEPHYR_BASE/soc/intel/intel_adsp/tools/cavstool_client.py,-s,remotehostname,-l" --west-flash="--remote-host=remotehostname" -T samples/hello_world 195 196If your network is set up such that the TCP connection from 197:file:`cavstool_client.py` to :file:`remote-fw-service.py` is forwarded through 198an intermediate host, you may need to tell :file:`cavstool_client.py` to connect 199to different ports as well as a different hostname. You can do this by appending 200the port numbers to the intermediate host name. 201 202.. code-block:: console 203 204 west flash --remote-host intermediatehost:reqport --pty remotehostname:logport 205 twister -p intel_adsp/cavs25 --device-testing --device-serial-pty="$ZEPHYR_BASE/soc/intel/intel_adsp/tools/cavstool_client.py,-s,remotehostname:logport,-l" --west-flash="--remote-host=remotehostname:reqport" -T samples/hello_world 206 207You can also save this information to a hardware map file and pass that to 208Twister. 209 210.. code-block:: console 211 212 twister -p intel_adsp/cavs25 --hardware-map cavs.map --device-testing -T samples/hello_world 213 214Here's a sample ``cavs.map``: 215 216.. code-block:: console 217 218 - connected: true 219 id: None 220 platform: intel_adsp/cavs25 221 product: None 222 runner: intel_adsp 223 serial_pty: "/home/zephyrus/zephyrproject/zephyr/soc/intel/intel_adsp/tools/cavstool_client.py,-s,remotehostname:logport,-l" 224 runner_params: 225 - --remote-host=remotehostname:reqport 226 227Any of the arguments you would pass to Twister or West, you can pass with the 228hardware map. As mentioned previously, you can see the Intel ADSP runner 229arguments by passing the ``--context`` flag while flashing with West. 230 231Refer to :ref:`twister_script` for more information on hardware maps. 232 233Local Flashing to cAVS-based ADSP 234--------------------------------- 235 236You can also directly flash the signed binary with the cAVS tool on the board. 237This may be useful for debugging. 238 239.. code-block:: console 240 241 sudo ./cavstool.py zephyr.ri 242 243You should see the following at the end of the log if you are successful: 244 245.. code-block:: console 246 247 ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx ***** 248 Hello World! intel_adsp 249 250Flashing to ACE-based ADSP 251-------------------------- 252 253Flashing is not yet supported for platforms with ACE-based ADSP, as these 254platforms are not yet publicly available. 255 256Debugging 257--------- 258 259As Zephyr doesn't (yet) support GDB for the Intel ADSP platforms, users are 260recommended to take advantage of Zephyr's built-in :ref:`coredump` and 261:ref:`logging_api` features. 262 263Troubleshooting 264*************** 265 266You can pass verbose flags directly to the Intel ADSP scripts: 267 268.. code-block:: console 269 270 sudo ./remote-fw-service.py -v 271 sudo ./cavstool.py zephyr.ri -v 272 273To see a list of their arguments: 274 275.. code-block:: console 276 277 sudo ./remote-fw-service.py --help 278 sudo ./cavstool.py --help 279 280If flashing fails at ``west sign`` with errors related to unparsed keys, try 281reinstalling the latest version of the signing tool. For example: 282 283.. code-block:: shell 284 285 error: 1 unparsed keys left in 'adsp' 286 error: 1 unparsed arrays left in 'adsp' 287 288If you get an "Address already in use" error when starting 289:file:`remote-fw-service.py` on the board, you may have another instance of the 290script running. Kill it. 291 292.. code-block:: console 293 294 $ sudo netstat -peanut | grep 9999 295 tcp 0 0 0.0.0.0:9999 0.0.0.0:* LISTEN 0 289788 14795/python3 296 $ sudo kill 14795 297 298If West or Twister successfully sign and establish TCP connections 299with :file:`remote-fw-service.py` but hang with no output afterwards, 300there are two possibilities: either :file:`remote-fw-service.py` failed 301to communicate, or :file:`cavstool.py` failed to flash. Log into 302the remote host and check the output of :file:`remote-fw-service.py`. 303 304If a message about "incorrect communication" appears, you mixed up the port 305numbers for logging and requests in your command or hardware map. Switch them 306and try again. 307 308.. code-block:: shell 309 310 ERROR:remote-fw:incorrect monitor communication! 311 312If a "load failed" message appears, that means the flash failed. Examine the 313log of ``west flash`` and carefully check that the arguments to ``west sign`` 314are correct. 315 316.. code-block:: console 317 318 WARNING:cavs-fw:Load failed? FW_STATUS = 0x81000012 319 INFO:cavs-fw:cAVS firmware load complete 320 -- 321 322Sometimes a flash failure or network miscommunication corrupts the state of 323the ADSP or :file:`remote-fw-service.py`. If you are unable to identify a 324cause of repeated failures, try restarting the scripts and / or power cycling 325your board to reset the state. 326 327Users - particularly, users of the Xtensa toolchain - should also consider 328clearing their Zephyr cache, as caching issues can occur from time to time. 329Delete the cache as well as any applicable build directories and start from 330scratch. You can try using the "pristine" option of West first, if you like. 331 332.. code-block:: console 333 334 rm -rf build twister-out* 335 rm -rf ~/.ccache ~/.cache/zephyr 336 337Xtensa toolchain users can get more detailed logs from the license server by 338exporting ``FLEXLM_DIAGNOSTICS=3``. 339 340.. _SOF: https://thesofproject.github.io/latest/index.html 341 342.. _Chromebooks: https://www.hp.com/us-en/shop/pdp/hp-chromebook-x360-14c-cc0047nr 343 344.. _UP Xtreme: https://up-board.org/up-xtreme/ 345 346.. _UP Xtreme i11-0001 series: https://up-shop.org/up-xtreme-i11-boards-0001-series.html 347 348.. _SOF instructions: https://thesofproject.github.io/latest/getting_started/build-guide/build-with-zephyr.html 349 350.. _UP Community wiki: https://github.com/up-board/up-community/wiki/Ubuntu 351 352.. _Cadence: https://www.cadence.com/en_US/home/tools/ip/tensilica-ip.html 353
