From 7977bf560f46a220f5ed95802012e31a15bded4c Mon Sep 17 00:00:00 2001 From: Marcin Szkudlinski Date: Wed, 13 Mar 2024 13:00:52 +0100 Subject: [PATCH 1/8] rtos: io_drivers: add loopback mode description This commit adds a description of using SSP devices in loopback mode Signed-off-by: Marcin Szkudlinski --- .../rtos_layer/io_drivers/i2s/i2s_driver.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index 110bace9..87d2bc88 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -108,3 +108,18 @@ stream with already running ones. "Single" I2S links may be synchronized and aggregated by sending I2sSyncData to the I2S IO Driver. + +Loopback mode +====================================== + +I2S transmitter and receiver share data pins at IP level - the Tx pin of the transmitter +is connected to the Rx pin of the receiver. This may be used for easy creation of digital +loopbacks (LBM, loopback mode) - the receiver always does see what the sender is sending. + +Please note that + + - all the parameters of transmitter and receiver, like number of channels, data rates +and format, must match each other + - the lines are connected internally, so LBM mode may be used even if the I2S pins are not +physically available + From bbabbdf4a4eb0ea81bdd71fd9776cbd0e0d7d2f1 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 15 Apr 2024 15:08:10 +0100 Subject: [PATCH 2/8] Update architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst Co-authored-by: Deb Taylor --- .../sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index 87d2bc88..e9f411c0 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -112,7 +112,7 @@ the I2S IO Driver. Loopback mode ====================================== -I2S transmitter and receiver share data pins at IP level - the Tx pin of the transmitter +The I2S transmitter and receiver share data pins at the IP level. The Tx pin of the transmitter is connected to the Rx pin of the receiver. This may be used for easy creation of digital loopbacks (LBM, loopback mode) - the receiver always does see what the sender is sending. From 02055a2e51bc32f8293723f9f212c77b8f85e93b Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 15 Apr 2024 15:08:17 +0100 Subject: [PATCH 3/8] Update architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst Co-authored-by: Deb Taylor --- .../sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index e9f411c0..ea3c6aed 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -116,7 +116,7 @@ The I2S transmitter and receiver share data pins at the IP level. The Tx pin of is connected to the Rx pin of the receiver. This may be used for easy creation of digital loopbacks (LBM, loopback mode) - the receiver always does see what the sender is sending. -Please note that +Please note the following: - all the parameters of transmitter and receiver, like number of channels, data rates and format, must match each other From 4217dc10d77e614bdc73212368f0e29a6c256646 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 15 Apr 2024 15:08:24 +0100 Subject: [PATCH 4/8] Update architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst Co-authored-by: Deb Taylor --- .../sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index ea3c6aed..0a38996e 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -118,7 +118,7 @@ loopbacks (LBM, loopback mode) - the receiver always does see what the sender is Please note the following: - - all the parameters of transmitter and receiver, like number of channels, data rates + - all the parameters of transmitter and receiver, like number of channels, data rates, and format must match each other and format, must match each other - the lines are connected internally, so LBM mode may be used even if the I2S pins are not physically available From da759668c957dc3d018a9f22e2d63b4e296143d5 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 15 Apr 2024 15:08:31 +0100 Subject: [PATCH 5/8] Update architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst Co-authored-by: Deb Taylor --- .../firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index 0a38996e..a27ce22e 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -119,7 +119,6 @@ loopbacks (LBM, loopback mode) - the receiver always does see what the sender is Please note the following: - all the parameters of transmitter and receiver, like number of channels, data rates, and format must match each other -and format, must match each other - the lines are connected internally, so LBM mode may be used even if the I2S pins are not physically available From ef2f6815da04ebaa51e7d1e186ed3654b6bfb3f9 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 15 Apr 2024 15:08:38 +0100 Subject: [PATCH 6/8] Update architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst Co-authored-by: Deb Taylor --- .../sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index a27ce22e..109e89a3 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -119,6 +119,6 @@ loopbacks (LBM, loopback mode) - the receiver always does see what the sender is Please note the following: - all the parameters of transmitter and receiver, like number of channels, data rates, and format must match each other - - the lines are connected internally, so LBM mode may be used even if the I2S pins are not + - the lines are connected internally, so LBM mode may be used even if the I2S pins are not physically available physically available From 1c4790f29b77edf89b369ddfdc6600eefc8f0d96 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Mon, 15 Apr 2024 15:08:43 +0100 Subject: [PATCH 7/8] Update architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst Co-authored-by: Deb Taylor --- .../firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst index 109e89a3..ef17ecae 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ b/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst @@ -120,5 +120,4 @@ Please note the following: - all the parameters of transmitter and receiver, like number of channels, data rates, and format must match each other - the lines are connected internally, so LBM mode may be used even if the I2S pins are not physically available -physically available From 0671cce5bebbf089b13fac865ca96e186674ba58 Mon Sep 17 00:00:00 2001 From: Kai Vehmanen Date: Fri, 24 May 2024 14:11:27 +0300 Subject: [PATCH 8/8] developer_guides: debugability: shell: add usage documentation Add basic introduction and usage documentation on how to use Zephyr shell feature with SOF. Signed-off-by: Kai Vehmanen --- developer_guides/debugability/index.rst | 1 + developer_guides/debugability/shell/index.rst | 119 ++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 developer_guides/debugability/shell/index.rst diff --git a/developer_guides/debugability/index.rst b/developer_guides/debugability/index.rst index 02c712ef..ed686043 100644 --- a/developer_guides/debugability/index.rst +++ b/developer_guides/debugability/index.rst @@ -12,3 +12,4 @@ Debugability probes/index ri-info/index perf-counters/index + shell/index diff --git a/developer_guides/debugability/shell/index.rst b/developer_guides/debugability/shell/index.rst new file mode 100644 index 00000000..4f0b943c --- /dev/null +++ b/developer_guides/debugability/shell/index.rst @@ -0,0 +1,119 @@ +.. _dbg-zephyr-shell: + +Zephyr Shell +############ + +Zephyr provides a shell subystem for interactive debugging and a channel +to run custom test sequences. SOF supports use of the Zephyr shell. + +The Zephyr shell is documented at: +https://docs.zephyrproject.org/latest/services/shell/index.html + +Requirements +************ + +- SOF target platform must have Zephyr support. + +- At least one shell backend (DSP memory window, serial port, RTT, ...) compatible + with target platform. + +Build SOF with Shell Support +**************************** + +Shell is typically disabled by default and the firmware needs to be +rebuilt. For common SOF targets, a build overlay is provided in SOF +upstream to easily enable shell suppot in build. + + .. code-block:: bash + + # example build for Intel Tiger Lake platform + build-sh> sof/scripts/xtensa-build-zephyr.py tgl -o app/shell_overlay.conf + +Using Shell with Intel cavstool.py +********************************** + +This section covers use with SOF targets compatible with +CONFIG_SHELL_BACKEND_ADSP_MEMORY_WINDOW backend (for example Audio DSPs +on Intel Tiger Lake and Meteor Lake). + +Running the tool with "-p" to create a pseudo terminal for the shell: + + .. code-block:: bash + + dut-sh> sudo ./cavstool.py -l -p + INFO:cavs-fw:Existing driver "snd_sof_pci_intel_tgl" found + INFO:cavs-fw:Mapped PCI bar 0 of length 16384 bytes. + INFO:cavs-fw:Selected output stream 15 (GCAP = 0xffffffff) + INFO:cavs-fw:Mapped PCI bar 4 of length 1048576 bytes. + INFO:cavs-fw:Detected cAVS 1.8+ hardware + INFO:cavs-fw:Waiting forever for firmware handoff, ROM_STATUS = 0xffffffff + INFO:cavs-fw:FW alive, ROM_STATUS = 0x5 + INFO:cavs-fw:shell PTY at: /dev/pts/4 + +The Zephyr shell is now available at pseudo terminal /dev/pts/4 (see log above) +and can be attached with any terminal program: + + .. code-block:: bash + + dut-sh> sudo minicom -p /dev/pts/4 + Welcome to minicom 2.8 + + OPTIONS: I18n + Port /dev/modem + + Press CTRL-A Z for help on special keys + + ~$ kernel uptime + Uptime: 31600 ms + ~$ kernel stacks + 0x9e0a4e78 ll_thread0 (real size 8192): unused 6752 usage 1440 / 8192 (17 %) + 0x9e0a34b8 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %) + 0x9e0a3400 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %) + 0x9e0a3348 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %) + 0x9e0a3290 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %) + 0x9e0a37d0 edf_workq (real size 8192): unused 6304 usage 1888 / 8192 (23 %) + 0x9e0a3c48 sysworkq (real size 1024): unused 728 usage 296 / 1024 (28 %) + 0x9e0a3180 shell_adsp_memory_window (real size 2048): unused 760 usage 1288 / 2048 (62 %) + 0x9e0a3080 logging (real size 4096): unused 3488 usage 608 / 4096 (14 %) + 0x9e0a38b0 idle 00 (real size 1024): unused 824 usage 200 / 1024 (19 %) + 0xbe09df80 IRQ 00 (real size 2048): unused 1712 usage 336 / 2048 (16 %) + 0xbe09e780 IRQ 01 (real size 2048): unused 0 usage 2048 / 2048 (100 %) + 0xbe09ef80 IRQ 02 (real size 2048): unused 0 usage 2048 / 2048 (100 %) + 0xbe09f780 IRQ 03 (real size 2048): unused 0 usage 2048 / 2048 (100 %) + ~$ kernel threads + Scheduler: 1 since last call + Threads: + 0x9e0a4e78 ll_thread0 + options: 0x0, priority: -16 timeout: 0 + state: pending, entry: 0xbe02e060 + stack size 8192, unused 6752, usage 1440 / 8192 (17 %) + + 0x9e0a34b8 + options: 0x0, priority: -16 timeout: 0 + state: prestart, entry: 0xbe0154cc + stack size 4096, unused 4008, usage 88 / 4096 (2 %) + + [cut] + *0x9e0a3180 shell_adsp_memory_window + options: 0x0, priority: 14 timeout: 0 + state: , entry: 0xbe01969c + stack size 2048, unused 760, usage 1288 / 2048 (62 %) + + 0x9e0a3080 logging + options: 0x0, priority: 14 timeout: 0 + state: pending, entry: 0xbe016710 + stack size 4096, unused 3488, usage 608 / 4096 (14 %) + + 0x9e0a38b0 idle 00 + options: 0x1, priority: 15 timeout: 0 + state: , entry: 0xbe054298 + stack size 1024, unused 824, usage 200 / 1024 (19 %) + ~$ + +The memory window backend does not rely on IPC, so the shell is not +dependent on the IPC version implementation. The cavstool.py is also +implemented to handle cases where the DSP is suspended to lower power +state and the memory window is not accessible to host. When the DSP +is in such state, the shell terminal will appear inactive, but it will +resume immediately after DSP resumes to active state, without need +to rerun the cavstool.py script.