Skip to content

Commit 0671cce

Browse files
kv2019ilgirdwood
kv2019i
authored and
lgirdwood
committed
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 <[email protected]>
1 parent 1c4790f commit 0671cce

File tree

2 files changed

+120
-0
lines changed

2 files changed

+120
-0
lines changed

‎developer_guides/debugability/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,4 @@ Debugability
1212
probes/index
1313
ri-info/index
1414
perf-counters/index
15+
shell/index

‎developer_guides/debugability/shell/index.rst

+119
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
.. _dbg-zephyr-shell:
2+
3+
Zephyr Shell
4+
############
5+
6+
Zephyr provides a shell subystem for interactive debugging and a channel
7+
to run custom test sequences. SOF supports use of the Zephyr shell.
8+
9+
The Zephyr shell is documented at:
10+
https://docs.zephyrproject.org/latest/services/shell/index.html
11+
12+
Requirements
13+
************
14+
15+
- SOF target platform must have Zephyr support.
16+
17+
- At least one shell backend (DSP memory window, serial port, RTT, ...) compatible
18+
with target platform.
19+
20+
Build SOF with Shell Support
21+
****************************
22+
23+
Shell is typically disabled by default and the firmware needs to be
24+
rebuilt. For common SOF targets, a build overlay is provided in SOF
25+
upstream to easily enable shell suppot in build.
26+
27+
.. code-block:: bash
28+
29+
# example build for Intel Tiger Lake platform
30+
build-sh> sof/scripts/xtensa-build-zephyr.py tgl -o app/shell_overlay.conf
31+
32+
Using Shell with Intel cavstool.py
33+
**********************************
34+
35+
This section covers use with SOF targets compatible with
36+
CONFIG_SHELL_BACKEND_ADSP_MEMORY_WINDOW backend (for example Audio DSPs
37+
on Intel Tiger Lake and Meteor Lake).
38+
39+
Running the tool with "-p" to create a pseudo terminal for the shell:
40+
41+
.. code-block:: bash
42+
43+
dut-sh> sudo ./cavstool.py -l -p
44+
INFO:cavs-fw:Existing driver "snd_sof_pci_intel_tgl" found
45+
INFO:cavs-fw:Mapped PCI bar 0 of length 16384 bytes.
46+
INFO:cavs-fw:Selected output stream 15 (GCAP = 0xffffffff)
47+
INFO:cavs-fw:Mapped PCI bar 4 of length 1048576 bytes.
48+
INFO:cavs-fw:Detected cAVS 1.8+ hardware
49+
INFO:cavs-fw:Waiting forever for firmware handoff, ROM_STATUS = 0xffffffff
50+
INFO:cavs-fw:FW alive, ROM_STATUS = 0x5
51+
INFO:cavs-fw:shell PTY at: /dev/pts/4
52+
53+
The Zephyr shell is now available at pseudo terminal /dev/pts/4 (see log above)
54+
and can be attached with any terminal program:
55+
56+
.. code-block:: bash
57+
58+
dut-sh> sudo minicom -p /dev/pts/4
59+
Welcome to minicom 2.8
60+
61+
OPTIONS: I18n
62+
Port /dev/modem
63+
64+
Press CTRL-A Z for help on special keys
65+
66+
~$ kernel uptime
67+
Uptime: 31600 ms
68+
~$ kernel stacks
69+
0x9e0a4e78 ll_thread0 (real size 8192): unused 6752 usage 1440 / 8192 (17 %)
70+
0x9e0a34b8 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %)
71+
0x9e0a3400 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %)
72+
0x9e0a3348 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %)
73+
0x9e0a3290 (real size 4096): unused 4008 usage 88 / 4096 ( 2 %)
74+
0x9e0a37d0 edf_workq (real size 8192): unused 6304 usage 1888 / 8192 (23 %)
75+
0x9e0a3c48 sysworkq (real size 1024): unused 728 usage 296 / 1024 (28 %)
76+
0x9e0a3180 shell_adsp_memory_window (real size 2048): unused 760 usage 1288 / 2048 (62 %)
77+
0x9e0a3080 logging (real size 4096): unused 3488 usage 608 / 4096 (14 %)
78+
0x9e0a38b0 idle 00 (real size 1024): unused 824 usage 200 / 1024 (19 %)
79+
0xbe09df80 IRQ 00 (real size 2048): unused 1712 usage 336 / 2048 (16 %)
80+
0xbe09e780 IRQ 01 (real size 2048): unused 0 usage 2048 / 2048 (100 %)
81+
0xbe09ef80 IRQ 02 (real size 2048): unused 0 usage 2048 / 2048 (100 %)
82+
0xbe09f780 IRQ 03 (real size 2048): unused 0 usage 2048 / 2048 (100 %)
83+
~$ kernel threads
84+
Scheduler: 1 since last call
85+
Threads:
86+
0x9e0a4e78 ll_thread0
87+
options: 0x0, priority: -16 timeout: 0
88+
state: pending, entry: 0xbe02e060
89+
stack size 8192, unused 6752, usage 1440 / 8192 (17 %)
90+
91+
0x9e0a34b8
92+
options: 0x0, priority: -16 timeout: 0
93+
state: prestart, entry: 0xbe0154cc
94+
stack size 4096, unused 4008, usage 88 / 4096 (2 %)
95+
96+
[cut]
97+
*0x9e0a3180 shell_adsp_memory_window
98+
options: 0x0, priority: 14 timeout: 0
99+
state: , entry: 0xbe01969c
100+
stack size 2048, unused 760, usage 1288 / 2048 (62 %)
101+
102+
0x9e0a3080 logging
103+
options: 0x0, priority: 14 timeout: 0
104+
state: pending, entry: 0xbe016710
105+
stack size 4096, unused 3488, usage 608 / 4096 (14 %)
106+
107+
0x9e0a38b0 idle 00
108+
options: 0x1, priority: 15 timeout: 0
109+
state: , entry: 0xbe054298
110+
stack size 1024, unused 824, usage 200 / 1024 (19 %)
111+
~$
112+
113+
The memory window backend does not rely on IPC, so the shell is not
114+
dependent on the IPC version implementation. The cavstool.py is also
115+
implemented to handle cases where the DSP is suspended to lower power
116+
state and the memory window is not accessible to host. When the DSP
117+
is in such state, the shell terminal will appear inactive, but it will
118+
resume immediately after DSP resumes to active state, without need
119+
to rerun the cavstool.py script.

0 commit comments

Comments
 (0)