# Kaisa：SOF HDMI `STREAM_PCM_PARAMS` 观测（dynamic_debug + IPC 载荷）

在 **jack-Kaisa 真机**（非本仓库 PVE/容器）上执行。目的：在 `STREAM_PCM_PARAMS` 失败前后看到 **发往 DSP 的 IPC 载荷**（`comp_id`、`buffer`、`stream_tag`、格式等），与拓扑/固件预期对照。

## 1. 前置条件

- 内核已加载 SOF（`lsmod | grep snd_sof`）。
- `sof_debug` 为 **模块参数**（`sound/soc/sof/core.c`），权限 **0444**：**不能在运行时通过 sysfs 改写**，须在 **`/etc/modprobe.d`** 中设置并在 **下次加载模块前** 生效（推荐 **重启**，或完整卸载 `snd_sof*` 相关模块后按依赖顺序再加载——易踩坑，**优先重启**）。
- **IPC 载荷十六进制** 依赖 `SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD`（`sof-priv.h` 中 **BIT(11)**，即 **0x800** 或十进制 **2048**）。载荷通过 `dev_dbg` / `print_hex_dump_debug` 输出，需同时打开 **dynamic_debug**（见下）。

## 2. 固定 `sof_debug`（载荷 dump）

创建或编辑（需 root）：

`/etc/modprobe.d/sof-ipc-payload.conf`

```
# BIT(11): SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD — 在 IPC 头发送后 dump 载荷（见 sound/soc/sof/sof-priv.h）
options snd_sof sof_debug=0x800
```

若需叠加其它标志，用按位或，例如同时打印 IPC 成功路径（可能较吵）：

```
# options snd_sof sof_debug=0x800
```

保存后 **重启**，确认：

```bash
cat /sys/module/snd_sof/parameters/sof_debug
# 期望：2048 或 0x800
```

## 3. dynamic_debug（使 `dev_dbg` 进入 dmesg）

挂载 debugfs（通常已挂载）：

```bash
sudo mount -t debugfs none /sys/kernel/debug 2>/dev/null || true
```

对 6.17 源码树中常见路径开启打印（路径以 **当前内核构建** 为准，下列与 Ubuntu HWE 6.17 树一致）：

```bash
sudo bash -c 'for f in \
  sound/soc/sof/ipc3.c \
  sound/soc/sof/ipc3-pcm.c \
  sound/soc/sof/intel/hda-pcm.c \
  sound/soc/sof/intel/hda-dai.c; do
  echo "file $f +p" >> /sys/kernel/debug/dynamic_debug/control
done'
```

若某行报错「Unknown」，用下面命令查看本内核实际注册的 `file` 名后替换：

```bash
grep -E "ipc3-pcm|hda-pcm|hda-dai" /sys/kernel/debug/dynamic_debug/control | head -20
```

## 4. 采集流程（失败前后各一段）

1. 清屏旧日志（可选）：`sudo dmesg -C`
2. 记录物理口：`aplay -L | grep -iE 'hdmi|hdmi3|pcm'`
3. 对目标设备播放（示例，卡号/设备号按本机改）：  
   `speaker-test -D plughw:0,4 -c 2 -l 1`  
   或使用 PipeWire/设置界面切到对应 HDMI sink，以触发 `hw_params`。
4. 立刻保存：

```bash
TS=$(date +%Y%m%d_%H%M%S)
KR=$(uname -r)
sudo dmesg -T > "/tmp/dmesg_sof_TRACE_STREAM_PCM_PARAMS_jack-Kaisa_${KR}_${TS}.txt"
```

5. 将文件复制到本仓库 **`audio_topology/collected/`**（可 scp），并在 `docs/WORK_PROGRESS.md` 或 `docs/REANALYSIS_Linux_HDMI_Audio_Kaisa.md` 中加一行文件名索引。

## 5. 日志中应关注的内容

- `STREAM_PCM_PARAMS` / `ipc tx error` / `stream_tag`
- `Message payload:` / `print_hex_dump` 块中的 **`comp_id`**、buffer 物理地址与长度、**`stream_tag`**、rate/channels/format
- 与 `audio_topology/ANALYSIS_Audio.md` 中 **pcm2/3/4 ↔ HDMI1/2/3** 的对应关系是否一致

## 6. 相关脚本

- `scripts/collect-kaisa-sof-trace.sh`：在本机检查 root、挂载 debugfs、写入 dynamic_debug、提示 `modprobe.d` 与采集命令。

## 7. 参考（源码）

- `sound/soc/sof/sof-priv.h`：`SOF_DBG_DUMP_IPC_MESSAGE_PAYLOAD`（BIT 11）
- `sound/soc/sof/ipc3.c`：`sof_ipc_tx_message` 内对载荷的 `sof_ipc3_dump_payload`
- `sound/soc/sof/ipc3-pcm.c`：`sof_ipc3_pcm_hw_params` 填充 `struct sof_ipc_pcm_params`