Skip to content

Commit edeefbd

Browse files
lrgirdwolrgirdwo
committed
zephyr/shell: document all missing shell commands in shell.md
Add entries for 21 commands not previously covered: Status commands: pipeline_status, module_status, core_status, core_on, core_off, sram_status, clock_status MMU/TLB debug commands: mmu_status, tlb_dump, tlb_lookup (MTL/ARL TLB MMIO) rasid, page_info (PTL Xtensa MMU) llext commands: llext_load, llext_list, llext_purge IPC4 pipeline construction commands: ppl_create, ppl_delete, ppl_state, mod_init, mod_delete, mod_bind, mod_unbind Also: - Expand the Enabling Shell Commands section with all Kconfig guards. - Update Task 1 ipc_stats note to reflect dedicated g_ipc_stats_lock (replacing ipc->lock which caused IPC timeout on MTL). - Add four new task-level sections at the end of the file for the above command groups.
1 parent 65c211c commit edeefbd

1 file changed

Lines changed: 238 additions & 2 deletions

File tree

‎zephyr/shell.md‎

Lines changed: 238 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,13 +50,143 @@ uart:~$ sof <command> [arguments]
5050
- **Arguments**: `usec` (optional, default 1500) - microseconds to block the domain.
5151
- **Warning**: Not reliable on SMP systems without explicit cross-core support.
5252

53+
### 8. `sof pipeline_status`
54+
- **Description**: Lists all active IPC4 pipelines with state, priority, period and core.
55+
- **Usage**: `sof pipeline_status`
56+
- **Output**: `ppl_id core priority period_us status state`
57+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_STATUS=y`.
58+
59+
### 9. `sof module_status`
60+
- **Description**: Lists all instantiated IPC4 components with pipeline, core and state.
61+
- **Usage**: `sof module_status`
62+
- **Output**: `comp_id module ppl_id core state`
63+
- **Dependency**: Requires `CONFIG_SOF_SHELL_MODULE_STATUS=y`.
64+
65+
### 10. `sof core_status`
66+
- **Description**: Reports the enabled/active state of each DSP core.
67+
- **Usage**: `sof core_status`
68+
- **Output**: Per-core enabled flag and which core is currently executing.
69+
- **Dependency**: Requires `CONFIG_SOF_SHELL_CORE_STATUS=y`.
70+
71+
### 11. `sof core_on`
72+
- **Description**: Powers on a secondary DSP core.
73+
- **Usage**: `sof core_on <core_id>`
74+
- **Arguments**: `core_id` — 1 to `CONFIG_CORE_COUNT-1` (core 0 is always on).
75+
- **Dependency**: Requires `CONFIG_SOF_SHELL_CORE_POWER=y`.
76+
77+
### 12. `sof core_off`
78+
- **Description**: Powers off a secondary DSP core.
79+
- **Usage**: `sof core_off <core_id>`
80+
- **Arguments**: `core_id` — 1 to `CONFIG_CORE_COUNT-1`.
81+
- **Dependency**: Requires `CONFIG_SOF_SHELL_CORE_POWER=y`.
82+
83+
### 13. `sof sram_status`
84+
- **Description**: Reports HPSRAM heap allocated, free, and peak-allocated bytes.
85+
- **Usage**: `sof sram_status`
86+
- **Dependency**: Requires `CONFIG_SOF_SHELL_SRAM_STATUS=y` and `CONFIG_SYS_HEAP_RUNTIME_STATS=y`.
87+
88+
### 14. `sof clock_status`
89+
- **Description**: Prints the current CPU clock frequency for each DSP core.
90+
- **Usage**: `sof clock_status`
91+
- **Output**: `clock freq_hz freq_mhz` per core.
92+
- **Dependency**: Requires `CONFIG_SOF_SHELL_CLOCK_STATUS=y` and `!CONFIG_SOF_ZEPHYR_NO_SOF_CLOCK`.
93+
94+
### 15. `sof mmu_status`
95+
- **Description**: Prints Intel ADSP MTL TLB / virtual memory status including VM base, page count, mapped/free pages, TLB MMIO base, and the `sys_mm_drv` mapped memory region list.
96+
- **Usage**: `sof mmu_status`
97+
- **Dependency**: Requires `CONFIG_MM_DRV_INTEL_ADSP_MTL_TLB=y`.
98+
99+
### 16. `sof tlb_dump`
100+
- **Description**: Dumps all active TLB entries showing virtual address, physical address, RWX flags and raw 16-bit entry value.
101+
- **Usage**: `sof tlb_dump`
102+
- **Dependency**: Requires `CONFIG_MM_DRV_INTEL_ADSP_MTL_TLB=y`.
103+
104+
### 17. `sof tlb_lookup`
105+
- **Description**: Queries the TLB for a single page or a VA range.
106+
- **Usage**: `sof tlb_lookup <vaddr> [end_vaddr]`
107+
- **Output**: Per-page: virtual address, physical address, mapped flag, RWX flags, bank index, raw entry.
108+
- **Dependency**: Requires `CONFIG_MM_DRV_INTEL_ADSP_MTL_TLB=y`.
109+
110+
### 18. `sof rasid`
111+
- **Description**: Decodes the Xtensa RASID hardware register showing the ring→ASID mapping.
112+
- **Usage**: `sof rasid`
113+
- **Output**: Raw RASID value plus per-ring (kernel/unused/user/shared) ASID byte.
114+
- **Dependency**: Requires `CONFIG_XTENSA_MMU=y`.
115+
116+
### 19. `sof page_info`
117+
- **Description**: Probes the Xtensa DTLB for a page or address range and reports physical address, ring, ASID, cache mode (WB/WT/uncached/illegal) and RWX permissions.
118+
- **Usage**: `sof page_info <vaddr> [end_vaddr]`
119+
- **Dependency**: Requires `CONFIG_XTENSA_MMU=y`.
120+
121+
### 20. `sof llext_load`
122+
- **Description**: Initiates an interactive llext module load from the host via the ADSP debug-window DMA slot. Sets up the handshake then waits (up to 120 s) for the host to DMA the `.ri` file.
123+
- **Usage**: `sof llext_load <name> [lib_id=1]`
124+
- **Host side**: `dd if=<module.ri> of=/sys/kernel/debug/sof/llext_load bs=$(stat -c%s <module.ri>) count=1`
125+
- **Dependency**: Requires `CONFIG_SOF_SHELL_LLEXT_LOAD=y` and `CONFIG_LIBRARY_MANAGER=y`.
126+
127+
### 21. `sof llext_list`
128+
- **Description**: Lists all llext libraries currently held in IMR/DRAM. For each library shows base address, storage size, number of module files, and per-file DRAM/SRAM mapping state, use count and dependency count.
129+
- **Usage**: `sof llext_list`
130+
- **Dependency**: Requires `CONFIG_SOF_SHELL_LLEXT_LIST=y` and `CONFIG_LIBRARY_MANAGER=y`.
131+
132+
### 22. `sof llext_purge`
133+
- **Description**: Removes a loadable llext library from IMR/DRAM and frees its memory. Fails with `-EBUSY` if any module file is still mapped in SRAM.
134+
- **Usage**: `sof llext_purge <lib_id>`
135+
- **Dependency**: Requires `CONFIG_SOF_SHELL_LLEXT_PURGE=y` and `CONFIG_LIBRARY_MANAGER=y`.
136+
137+
### 23. `sof ppl_create`
138+
- **Description**: Creates a new IPC4 pipeline instance. Intended for bring-up and debug use only.
139+
- **Usage**: `sof ppl_create <ppl_id> [priority=0] [pages=2] [core=0] [lp=0]`
140+
- **Arguments**: `ppl_id` (0–255), `priority` (0–7), `pages` (1–2047), `core` (0–7), `lp` (0/1 — low-power mode).
141+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
142+
143+
### 24. `sof ppl_delete`
144+
- **Description**: Deletes a pipeline and all its module instances.
145+
- **Usage**: `sof ppl_delete <ppl_id>`
146+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
147+
148+
### 25. `sof ppl_state`
149+
- **Description**: Transitions a pipeline to a new IPC4 state.
150+
- **Usage**: `sof ppl_state <ppl_id> <running|paused|reset>`
151+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
152+
153+
### 26. `sof mod_init`
154+
- **Description**: Instantiates a module into a pipeline. Module ID can be given as a decimal/hex number or as the 8-char manifest name. No init-data blob is sent; only modules with a working zero-parameter default config will succeed.
155+
- **Usage**: `sof mod_init <mod_name|mod_id> <inst_id> <ppl_id> [core=0] [dp=0]`
156+
- **Output**: Prints `module NAME(0xID) inst N created in pipeline P comp_id=0x...` on success.
157+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
158+
159+
### 27. `sof mod_delete`
160+
- **Description**: Deletes a module instance.
161+
- **Usage**: `sof mod_delete <mod_name|mod_id> <inst_id>`
162+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
163+
164+
### 28. `sof mod_bind`
165+
- **Description**: Binds (connects) the output queue of a source module to the input queue of a destination module.
166+
- **Usage**: `sof mod_bind <src_name|src_id> <src_inst> <dst_name|dst_id> <dst_inst> [src_queue=0] [dst_queue=0]`
167+
- **Output**: `bound NAME(0xID):INST[qN] -> NAME(0xID):INST[qN]`
168+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
169+
170+
### 29. `sof mod_unbind`
171+
- **Description**: Disconnects two previously bound module instances.
172+
- **Usage**: `sof mod_unbind <src_name|src_id> <src_inst> <dst_name|dst_id> <dst_inst> [src_queue=0] [dst_queue=0]`
173+
- **Output**: `unbound NAME(0xID):INST[qN] -/- NAME(0xID):INST[qN]`
174+
- **Dependency**: Requires `CONFIG_SOF_SHELL_PIPELINE_OPS=y`.
175+
53176
---
54177

55178
## Enabling Shell Commands
56179

57180
Ensure the following Kconfig symbols are enabled in your build configuration:
58181
- `CONFIG_SHELL=y`
59-
- `CONFIG_SOF_VREGIONS=y` (for `vpage` and `vregion` commands)
182+
- `CONFIG_SOF_VREGIONS=y` (for `vpage_status` and `vregion_status`)
183+
- `CONFIG_SOF_SHELL_PIPELINE_STATUS=y` / `CONFIG_SOF_SHELL_MODULE_STATUS=y`
184+
- `CONFIG_SOF_SHELL_CORE_STATUS=y` / `CONFIG_SOF_SHELL_CORE_POWER=y`
185+
- `CONFIG_SOF_SHELL_SRAM_STATUS=y` + `CONFIG_SYS_HEAP_RUNTIME_STATS=y`
186+
- `CONFIG_SOF_SHELL_CLOCK_STATUS=y` (skipped when `CONFIG_SOF_ZEPHYR_NO_SOF_CLOCK=y`)
187+
- `CONFIG_SOF_SHELL_MMU_DBG=y` (for `mmu_status`, `tlb_dump`, `tlb_lookup` on MTL/ARL; `rasid`, `page_info` on PTL Xtensa MMU platforms)
188+
- `CONFIG_SOF_SHELL_LLEXT_LOAD=y` / `CONFIG_SOF_SHELL_LLEXT_LIST=y` / `CONFIG_SOF_SHELL_LLEXT_PURGE=y` (need `CONFIG_LIBRARY_MANAGER=y`)
189+
- `CONFIG_SOF_SHELL_PIPELINE_OPS=y` (for `ppl_create/delete/state`, `mod_init/delete/bind/unbind`; default `n`, depends `IPC_MAJOR_4`)
60190

61191
---
62192

@@ -139,7 +269,8 @@ debug or testing. Items get ticked off as commands land on `topic/shell`.
139269
- `ipc_stats_inc_rx_error()`
140270
- `ipc_stats_get(out)` / `ipc_stats_reset()`
141271
- Storage and locking in `src/ipc/ipc-common.c` (single global, protected by
142-
`ipc->lock`, IPC-version agnostic).
272+
a dedicated `g_ipc_stats_lock` spinlock; using ipc->lock was avoided to
273+
prevent lock recursion in the IPC hot path).
143274
- RX hook: `ipc_platform_do_cmd()` in `src/ipc/ipc-zephyr.c`, just before
144275
dispatch &mdash; captures the IPC3/IPC4 `pri`/`ext` words.
145276
- TX hooks: `ipc_platform_send_msg()` and `ipc_platform_send_msg_direct()` in
@@ -429,3 +560,108 @@ debug or testing. Items get ticked off as commands land on `topic/shell`.
429560
commands should follow the same pattern: small, read-only,
430561
Kconfig-gated, and complementary to (not a replacement for) the
431562
host control plane.
563+
564+
---
565+
566+
## DSP Status Commands (`pipeline_status`, `module_status`, `core_status/on/off`, `sram_status`, `clock_status`)
567+
568+
These commands provide a read-only snapshot of the firmware runtime state.
569+
570+
| Command | Kconfig | Description |
571+
|---|---|---|
572+
| `sof pipeline_status` | `SOF_SHELL_PIPELINE_STATUS` | IPC4 pipeline list: id, core, priority, period_us, numeric status, decoded state string. |
573+
| `sof module_status` | `SOF_SHELL_MODULE_STATUS` | IPC4 component list: comp_id, module name + id, ppl_id, core, state. |
574+
| `sof core_status` | `SOF_SHELL_CORE_STATUS` | Per-core enabled flag and current-core marker. |
575+
| `sof core_on <id>` | `SOF_SHELL_CORE_POWER` | Power on secondary core via `cpu_enable_core()`. |
576+
| `sof core_off <id>` | `SOF_SHELL_CORE_POWER` | Power off secondary core via `cpu_disable_core()`. |
577+
| `sof sram_status` | `SOF_SHELL_SRAM_STATUS` | HPSRAM `sys_heap` stats (allocated / free / max_allocated). Needs `SYS_HEAP_RUNTIME_STATS=y`. |
578+
| `sof clock_status` | `SOF_SHELL_CLOCK_STATUS` | Clock frequency per DSP core from `clocks_get()`. Skipped when `SOF_ZEPHYR_NO_SOF_CLOCK=y`. |
579+
580+
Shell commands in [zephyr/sof_shell.c](zephyr/sof_shell.c).
581+
582+
---
583+
584+
## MMU / TLB Debug Commands (`mmu_status`, `tlb_dump`, `tlb_lookup`, `rasid`, `page_info`)
585+
586+
Gated by `CONFIG_SOF_SHELL_MMU_DBG`. The available sub-set depends on the
587+
platform MMU driver selected:
588+
589+
| Command | Platform | Kconfig guard |
590+
|---|---|---|
591+
| `sof mmu_status` | Intel ADSP MTL/ARL (TLB MMIO) | `MM_DRV_INTEL_ADSP_MTL_TLB` |
592+
| `sof tlb_dump` | Intel ADSP MTL/ARL | `MM_DRV_INTEL_ADSP_MTL_TLB` |
593+
| `sof tlb_lookup <va> [end_va]` | Intel ADSP MTL/ARL | `MM_DRV_INTEL_ADSP_MTL_TLB` |
594+
| `sof rasid` | PTL / Xtensa MMU | `XTENSA_MMU` |
595+
| `sof page_info <va> [end_va]` | PTL / Xtensa MMU | `XTENSA_MMU` |
596+
597+
On PTL both sets of commands are available (platform has both the TLB MMIO and
598+
the Xtensa hardware MMU).
599+
600+
### Implementation notes
601+
602+
- `mmu_status` / `tlb_dump` / `tlb_lookup` read the 16-bit MMIO TLB table
603+
directly via the `mm-drv-intel-adsp` device-tree node; no `sys_mm_drv` calls
604+
are needed.
605+
- `rasid` uses the `rsr rasid` Xtensa instruction; `page_info` uses `pdtlb` /
606+
`rdtlb0` / `rdtlb1` inline assembly to probe the hardware DTLB.
607+
- All commands are purely read-only — they do not modify TLB entries or RASID.
608+
609+
---
610+
611+
## llext Commands (`llext_load`, `llext_list`, `llext_purge`)
612+
613+
These commands manage loadable extension (llext) firmware libraries.
614+
615+
| Command | Kconfig | Description |
616+
|---|---|---|
617+
| `sof llext_load <name> [lib_id]` | `SOF_SHELL_LLEXT_LOAD` | Interactive DMA-based load from host. Signals the host via a debug-window slot then waits up to 120 s. |
618+
| `sof llext_list` | `SOF_SHELL_LLEXT_LIST` | List all libraries in IMR/DRAM with DRAM/SRAM mapping state, use count and dependency count. |
619+
| `sof llext_purge <lib_id>` | `SOF_SHELL_LLEXT_PURGE` | Free a library from IMR/DRAM. Fails with `-EBUSY` if any module is still mapped. |
620+
621+
All three require `CONFIG_LIBRARY_MANAGER=y`.
622+
623+
### Host-side usage for `llext_load`
624+
625+
```sh
626+
# Build and sign your library, then:
627+
dd if=my_module.ri \
628+
of=/sys/kernel/debug/sof/llext_load \
629+
bs=$(stat -c%s my_module.ri) count=1
630+
```
631+
632+
The firmware prints the result (bytes transferred or error code) on the shell
633+
when the DMA completes.
634+
635+
---
636+
637+
## IPC4 Pipeline Construction Commands (`ppl_create`, `ppl_delete`, `ppl_state`, `mod_init`, `mod_delete`, `mod_bind`, `mod_unbind`)
638+
639+
Gated by `CONFIG_SOF_SHELL_PIPELINE_OPS=y` (default `n`; depends `IPC_MAJOR_4`).
640+
**Intended for bring-up and debug only.** These commands send real IPC4 messages
641+
to the firmware and modify live state; use with care.
642+
643+
| Command | Description |
644+
|---|---|
645+
| `sof ppl_create <id> [prio] [pages] [core] [lp]` | Create an IPC4 pipeline. |
646+
| `sof ppl_delete <id>` | Delete a pipeline and all its module instances. |
647+
| `sof ppl_state <id> <running\|paused\|reset>` | Transition pipeline state. |
648+
| `sof mod_init <mod\|id> <inst> <ppl> [core] [dp]` | Instantiate a module (no init-data blob). |
649+
| `sof mod_delete <mod\|id> <inst>` | Delete a module instance. |
650+
| `sof mod_bind <src\|id> <si> <dst\|id> <di> [sq] [dq]` | Bind src output queue to dst input queue. |
651+
| `sof mod_unbind <src\|id> <si> <dst\|id> <di> [sq] [dq]` | Disconnect two bound modules. |
652+
653+
`mod_init` / `mod_bind` / `mod_unbind` accept the 8-char manifest name (e.g.
654+
`GAIN`) or a numeric `module_id` (decimal or `0x` hex) interchangeably.
655+
Output includes the resolved module name alongside the numeric ID in the format
656+
`NAME(0xID)`.
657+
658+
### Notes
659+
660+
- No IPC4 `init_data` blob is sent by `mod_init`; only modules whose
661+
firmware defaults work with an empty config will successfully init.
662+
- `ppl_state` calls `ipc4_pipeline_prepare()` then `ipc4_pipeline_trigger()`
663+
in sequence, mirroring what the host driver does.
664+
- These commands bypass the host driver's topology state machine. Mixing
665+
shell-driven construction with a running host audio session will likely
666+
cause errors.
667+

0 commit comments

Comments
 (0)