shell: add mailbox_hex and dbgwin_dump commands

Add two new SOF shell commands for poking at SRAM diagnostics
regions from the live shell, without host-side tooling.

  sof mailbox_hex                          - list the four SOF mailbox
                                             regions (exception, dspbox,
                                             hostbox, debug)
  sof mailbox_hex <region> [off] [len]     - hex-dump that region; off
                                             and len are clamped to the
                                             region size, default 256B

  sof dbgwin_dump                          - list all 15 ADSP debug-
                                             window slot descriptors
                                             (resource_id, type, vma,
                                             decoded type name, core)
  sof dbgwin_dump <slot> [len]             - hex-dump one slot, max
                                             ADSP_DW_SLOT_SIZE (=4096)

mailbox_hex uses the existing MAILBOX_*_BASE/SIZE macros from
sof/lib/mailbox.h. dbgwin_dump re-derives window 2 base from the
device tree (mem_window2) plus WIN2_OFFSET and mirrors struct
adsp_debug_window from
zephyr/soc/intel/intel_adsp/common/debug_window.c, accessed through
an uncached pointer so it works whether or not
CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER=y. Both commands share a small
sof_shell_hex_dump() helper.

Two new Kconfigs (default y):
  CONFIG_SOF_SHELL_MAILBOX_HEX
  CONFIG_SOF_SHELL_DBGWIN_DUMP    (depends on SOC_FAMILY_INTEL_ADSP)

Quick-win 5 was originally listed as crash_log/bt; pivoted because
SOF's in-tree panic_dump() is not compiled on Zephyr (Zephyr installs
its own fatal handler) and a live shell cannot backtrace its own CPU
after a panic. mailbox_hex exception still surfaces whatever the
platform-specific fatal path leaves there, covering the same
diagnostic intent as far as is possible from a running shell.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>

Author: lrgirdwo

zephyr/Kconfig

@@ -517,6 +517,33 @@ config SOF_SHELL_MTRACE_DUMP
 	  receive every byte. Useful when no host driver is attached
 	  (e.g. early bring-up over UART shell only).
 
+config SOF_SHELL_MAILBOX_HEX
+	bool "Hex-dump SOF mailbox regions"
+	default y
+	depends on SHELL
+	help
+	  Enables 'sof mailbox_hex <region> [offset] [length]' which hex
+	  dumps one of the SOF mailbox regions (exception, dspbox, hostbox,
+	  debug). With no arguments lists the regions and their sizes. The
+	  length is clamped to the region size; default 256 bytes.
+
+	  Useful for inspecting the panic dump area after a fatal error and
+	  for low-level IPC payload debugging.
+
+config SOF_SHELL_DBGWIN_DUMP
+	bool "Hex-dump ADSP debug-window slots"
+	default y
+	depends on SHELL && SOC_FAMILY_INTEL_ADSP
+	help
+	  Enables 'sof dbgwin_dump [slot] [length]' which lists the
+	  descriptors of all ADSP debug-window slots (slot manager
+	  metadata in window 2 page 0) with a friendly type name, and
+	  hex-dumps the slot contents when a slot index is given.
+
+	  This makes it possible to peek at gdb_stub, telemetry,
+	  critical_log, broken-marker and other slots from the shell
+	  without host-side tooling.
+
 endmenu # SOF shell commands
 
 config SOF_VREGIONS

zephyr/shell.md

@@ -90,7 +90,7 @@ debug or testing. Items get ticked off as commands land on `topic/shell`.
 | Logging / trace | `log_status`, `mtrace_dump` (snapshot) | **DONE (task 4)** — runtime per-source `log_level` deferred (needs `CONFIG_LOG_RUNTIME_FILTERING`, see notes) |
 | Telemetry / perf | `perf_status`, `perf_reset`, `cpu_load` | TODO |
 | Notifications | `notify_subscribers`, `notify_stats` | TODO |
-| Debug window / mailbox | `dbgwin_dump <slot>`, `mailbox_hex` | TODO |
+| **Debug window / mailbox** | `dbgwin_dump <slot>`, `mailbox_hex` | **DONE (task 5)** |
 | Crash / panic | `crash_log`, `crash_clear`, `panic_info`, `bt`, `regs` | TODO |
 | Heap walk | `heap_walk <zone>`, `heap_blocks`, `obj_pool_stats` | TODO |
 | Probes | `probe_init`, `probe_add <buf_id>`, `probe_remove`, `probe_dma_status` | TODO |
@@ -113,7 +113,7 @@ debug or testing. Items get ticked off as commands land on `topic/shell`.
 2. **`buffer_list` / `buffer_info`** &mdash; DONE.
 3. **`sched_tasks` / `sched_load`** &mdash; DONE.
 4. **`log_status` / `mtrace_dump`** &mdash; DONE.
-5. `crash_log` / `bt` &mdash; pair with the `crash-*` artifacts in the tree.
+5. **`mailbox_hex` / `dbgwin_dump`** &mdash; DONE (was originally `crash_log`/`bt`; pivoted because SOF panic.c isn't built on Zephyr and `bt` of a running CPU from itself isn't meaningful).
 6. `perf_status` &mdash; wraps SOF telemetry counters.
 7. `dai_list` / `dma_chan_status` &mdash; link/DMA blind spot.
 8. `kctl_get/set` &mdash; today only doable via tplg/IPC.
@@ -265,3 +265,47 @@ debug or testing. Items get ticked off as commands land on `topic/shell`.
   future option could format output in pages or filter by severity.
 - A `mtrace_dump --consume` mode (advance `host_ptr`) is intentionally
   not provided to avoid silently breaking host-side tooling.
+
+## Task 5 &mdash; `mailbox_hex` / `dbgwin_dump`
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `sof mailbox_hex` | List the four SOF mailbox regions (exception, dspbox, hostbox, debug) with their base address and size. |
+| `sof mailbox_hex <region> [off] [len]` | Hex-dump a mailbox region; offset and length are clamped to the region size. Default length 256 bytes. |
+| `sof dbgwin_dump` | List all 15 ADSP debug-window slot descriptors (resource_id, type, vma, decoded type name, core). |
+| `sof dbgwin_dump <slot> [len]` | Hex-dump a single slot (max `ADSP_DW_SLOT_SIZE` = 4096 bytes); default length 256. |
+
+### Implementation
+
+- `mailbox_hex` uses the `MAILBOX_*_BASE` / `MAILBOX_*_SIZE` macros
+  from [src/include/sof/lib/mailbox.h](src/include/sof/lib/mailbox.h);
+  the four region records are a static table.
+- `dbgwin_dump` re-derives the window 2 base from the device tree
+  (`mem_window2`) plus `WIN2_OFFSET`, mirrors
+  `struct adsp_debug_window` from
+  [zephyr/soc/intel/intel_adsp/common/debug_window.c](../../zephyr/soc/intel/intel_adsp/common/debug_window.c)
+  and reads through an uncached pointer so we always see the
+  slot-manager state (works whether or not
+  `CONFIG_INTEL_ADSP_DEBUG_SLOT_MANAGER=y`).
+- A small shared `sof_shell_hex_dump()` helper handles the 16-byte
+  hex+ASCII rows and is built whenever either command is enabled.
+- Two new Kconfigs (default `y`):
+  - `CONFIG_SOF_SHELL_MAILBOX_HEX`
+  - `CONFIG_SOF_SHELL_DBGWIN_DUMP` (depends on `SOC_FAMILY_INTEL_ADSP`)
+- Shell commands in [zephyr/sof_shell.c](zephyr/sof_shell.c).
+
+### Notes / follow-ups
+
+- The original quick-win was `crash_log`/`bt`; pivoted because SOF's
+  in-tree `panic_dump()` is not compiled on Zephyr (Zephyr installs
+  its own fatal handler) and a running shell can't backtrace its own
+  CPU after a panic. `mailbox_hex exception` still surfaces whatever
+  the platform-specific fatal path leaves there, so the same
+  diagnostic intent is covered as far as it can be from a live shell.
+- A future `panic_decode` could parse a known on-target oops layout
+  (Zephyr coredump or telemetry slot) once one is standardised on
+  ACE.
+- `dbgwin_dump` is read-only. We do not implement a write/seize
+  command to avoid corrupting host-visible state.

zephyr/sof_shell.c

@@ -1950,6 +1950,203 @@ __cold static int cmd_sof_mtrace_dump(const struct shell *sh,
 
 #endif /* CONFIG_SOF_SHELL_MTRACE_DUMP */
 
+#if CONFIG_SOF_SHELL_MAILBOX_HEX || CONFIG_SOF_SHELL_DBGWIN_DUMP
+
+static void sof_shell_hex_dump(const struct shell *sh, uintptr_t base,
+			       size_t off, size_t len)
+{
+	const uint8_t *p = (const uint8_t *)(base + off);
+	size_t i, j;
+
+	for (i = 0; i < len; i += 16) {
+		size_t row = MIN((size_t)16, len - i);
+		char ascii[17];
+
+		shell_fprintf(sh, SHELL_NORMAL, "%08lx ",
+			      (unsigned long)(off + i));
+		for (j = 0; j < 16; j++) {
+			if (j < row)
+				shell_fprintf(sh, SHELL_NORMAL, " %02x", p[i + j]);
+			else
+				shell_fprintf(sh, SHELL_NORMAL, "   ");
+			ascii[j] = (j < row && p[i + j] >= 0x20 && p[i + j] < 0x7f) ?
+				   (char)p[i + j] : '.';
+		}
+		ascii[16] = '\0';
+		shell_fprintf(sh, SHELL_NORMAL, "  %s\n", ascii);
+	}
+}
+
+#endif
+
+#if CONFIG_SOF_SHELL_MAILBOX_HEX
+
+#include <sof/lib/mailbox.h>
+
+struct sof_shell_mb_region {
+	const char *name;
+	uintptr_t base;
+	size_t size;
+};
+
+static const struct sof_shell_mb_region sof_shell_mb_regions[] = {
+	{ "exception", MAILBOX_EXCEPTION_BASE, MAILBOX_EXCEPTION_SIZE },
+	{ "dspbox",    MAILBOX_DSPBOX_BASE,    MAILBOX_DSPBOX_SIZE    },
+	{ "hostbox",   MAILBOX_HOSTBOX_BASE,   MAILBOX_HOSTBOX_SIZE   },
+	{ "debug",     MAILBOX_DEBUG_BASE,     MAILBOX_DEBUG_SIZE     },
+};
+
+__cold static int cmd_sof_mailbox_hex(const struct shell *sh,
+				      size_t argc, char *argv[])
+{
+	const struct sof_shell_mb_region *r = NULL;
+	size_t off = 0, len;
+	char *end = NULL;
+	int i;
+
+	if (argc < 2) {
+		shell_print(sh, "Mailbox regions:");
+		for (i = 0; i < ARRAY_SIZE(sof_shell_mb_regions); i++)
+			shell_print(sh, "  %-10s base 0x%08lx  size %zu",
+				    sof_shell_mb_regions[i].name,
+				    (unsigned long)sof_shell_mb_regions[i].base,
+				    sof_shell_mb_regions[i].size);
+		shell_print(sh, "Usage: sof mailbox_hex <region> [offset] [length]");
+		return 0;
+	}
+
+	for (i = 0; i < ARRAY_SIZE(sof_shell_mb_regions); i++) {
+		if (!strcmp(argv[1], sof_shell_mb_regions[i].name)) {
+			r = &sof_shell_mb_regions[i];
+			break;
+		}
+	}
+	if (!r) {
+		shell_print(sh, "Unknown region '%s'", argv[1]);
+		return -EINVAL;
+	}
+
+	if (argc > 2) {
+		off = strtoul(argv[2], &end, 0);
+		if (end == argv[2] || off >= r->size) {
+			shell_print(sh, "Bad offset (max 0x%zx)", r->size);
+			return -EINVAL;
+		}
+	}
+
+	len = MIN((size_t)256, r->size - off);
+	if (argc > 3) {
+		len = strtoul(argv[3], &end, 0);
+		if (end == argv[3])
+			return -EINVAL;
+		len = MIN(len, r->size - off);
+	}
+
+	shell_print(sh, "%s @ 0x%08lx + 0x%zx, %zu bytes:",
+		    r->name, (unsigned long)r->base, off, len);
+	sof_shell_hex_dump(sh, r->base, off, len);
+	return 0;
+}
+
+#endif /* CONFIG_SOF_SHELL_MAILBOX_HEX */
+
+#if CONFIG_SOF_SHELL_DBGWIN_DUMP
+
+#include <adsp_memory.h>
+#include <adsp_debug_window.h>
+
+/* Mirror struct used by zephyr/soc/intel/intel_adsp/common/debug_window.c.
+ * We map window 2 directly so we can read descriptors and slot data without
+ * depending on slot-manager internals.
+ */
+struct sof_shell_dw {
+	struct adsp_dw_desc descs[ADSP_DW_DESC_COUNT];
+	uint8_t reserved[ADSP_DW_PAGE0_SLOT_OFFSET -
+			 ADSP_DW_DESC_COUNT * sizeof(struct adsp_dw_desc)];
+	uint8_t partial_page0[ADSP_DW_SLOT_SIZE - ADSP_DW_PAGE0_SLOT_OFFSET];
+	uint8_t slots[ADSP_DW_SLOT_COUNT][ADSP_DW_SLOT_SIZE];
+} __packed;
+
+#define SOF_SHELL_DW_BASE \
+	(DT_REG_ADDR(DT_PHANDLE(DT_NODELABEL(mem_window2), memory)) + WIN2_OFFSET)
+
+static const char *dw_type_name(uint32_t type)
+{
+	switch (type & ADSP_DW_SLOT_TYPE_MASK) {
+	case ADSP_DW_SLOT_UNUSED & ADSP_DW_SLOT_TYPE_MASK:
+		return type ? "?" : "unused";
+	case ADSP_DW_SLOT_CRITICAL_LOG & ADSP_DW_SLOT_TYPE_MASK:
+		return "critical_log";
+	case ADSP_DW_SLOT_DEBUG_LOG & ADSP_DW_SLOT_TYPE_MASK:
+		return "debug_log";
+	case ADSP_DW_SLOT_GDB_STUB & ADSP_DW_SLOT_TYPE_MASK:
+		return "gdb_stub";
+	case ADSP_DW_SLOT_TELEMETRY & ADSP_DW_SLOT_TYPE_MASK:
+		return "telemetry";
+	case ADSP_DW_SLOT_TRACE & ADSP_DW_SLOT_TYPE_MASK:
+		return "trace";
+	case ADSP_DW_SLOT_SHELL & ADSP_DW_SLOT_TYPE_MASK:
+		return "shell";
+	case ADSP_DW_SLOT_DEBUG_STREAM & ADSP_DW_SLOT_TYPE_MASK:
+		return "debug_stream";
+	case ADSP_DW_SLOT_BROKEN & ADSP_DW_SLOT_TYPE_MASK:
+		return "broken";
+	default:
+		return "?";
+	}
+}
+
+__cold static int cmd_sof_dbgwin_dump(const struct shell *sh,
+				      size_t argc, char *argv[])
+{
+	volatile struct sof_shell_dw *dw =
+		(volatile struct sof_shell_dw *)
+		sys_cache_uncached_ptr_get((__sparse_force void __sparse_cache *)
+					   SOF_SHELL_DW_BASE);
+	int slot, i;
+	size_t len = 256;
+	char *end = NULL;
+
+	if (argc < 2) {
+		shell_print(sh,
+			    "ADSP debug window @ 0x%08lx (%d slots, %u bytes each)",
+			    (unsigned long)SOF_SHELL_DW_BASE,
+			    ADSP_DW_SLOT_COUNT, ADSP_DW_SLOT_SIZE);
+		shell_print(sh, "  slot  res_id      type       vma         name");
+		for (i = 0; i < ADSP_DW_SLOT_COUNT; i++) {
+			shell_print(sh,
+				    "  %3d   0x%08x  0x%08x 0x%08x  %s (core %u)",
+				    i, dw->descs[i].resource_id, dw->descs[i].type,
+				    dw->descs[i].vma, dw_type_name(dw->descs[i].type),
+				    dw->descs[i].type & ADSP_DW_SLOT_CORE_MASK);
+		}
+		shell_print(sh, "Usage: sof dbgwin_dump <slot> [length]");
+		return 0;
+	}
+
+	slot = strtol(argv[1], &end, 0);
+	if (end == argv[1] || slot < 0 || slot >= ADSP_DW_SLOT_COUNT) {
+		shell_print(sh, "Bad slot (0..%d)", ADSP_DW_SLOT_COUNT - 1);
+		return -EINVAL;
+	}
+
+	if (argc > 2) {
+		len = strtoul(argv[2], &end, 0);
+		if (end == argv[2])
+			return -EINVAL;
+	}
+	len = MIN(len, (size_t)ADSP_DW_SLOT_SIZE);
+
+	shell_print(sh, "Slot %d type=0x%08x (%s, core %u) vma=0x%08x; %zu bytes:",
+		    slot, dw->descs[slot].type, dw_type_name(dw->descs[slot].type),
+		    dw->descs[slot].type & ADSP_DW_SLOT_CORE_MASK,
+		    dw->descs[slot].vma, len);
+	sof_shell_hex_dump(sh, (uintptr_t)dw->slots[slot], 0, len);
+	return 0;
+}
+
+#endif /* CONFIG_SOF_SHELL_DBGWIN_DUMP */
+
 SHELL_STATIC_SUBCMD_SET_CREATE(sof_commands,
 	SHELL_CMD(test_inject_sched_gap, NULL,
 		  "Inject a gap to audio scheduling\n",
@@ -2138,6 +2335,18 @@ SHELL_STATIC_SUBCMD_SET_CREATE(sof_commands,
 		  cmd_sof_mtrace_dump),
 #endif
 
+#if CONFIG_SOF_SHELL_MAILBOX_HEX
+	SHELL_CMD_ARG(mailbox_hex, NULL,
+		  "Hex-dump a mailbox region: <region> [offset] [length]\n",
+		  cmd_sof_mailbox_hex, 1, 3),
+#endif
+
+#if CONFIG_SOF_SHELL_DBGWIN_DUMP
+	SHELL_CMD_ARG(dbgwin_dump, NULL,
+		  "List ADSP debug-window slots, or hex-dump one: [slot] [length]\n",
+		  cmd_sof_dbgwin_dump, 1, 2),
+#endif
+
 	SHELL_SUBCMD_SET_END
 );