跳至主要内容

用 Coding Agent 讀一棵陌生的 SoC BSP

一份可重複使用的導讀清單。重點不是「叫 agent 解釋這段程式碼」， 而是先把問題設計好——agent 擅長建索引，但判斷該問什麼還是人的工作。

BSP 這種 tree 有兩個特性讓一般讀碼方法失效：檔案多但入口不明顯， 以及大量邏輯藏在 device tree 和 build 設定裡而不在 .c 檔。 下面六節是我實際用下來覺得有效的順序，每節都附「驗收問題」—— 能用自己的話回答，才算真的讀懂，而不是讀完一份摘要。

節點一：IPC / Mailbox 的訊息表​

任何有協處理器的 SoC，第一個該找的就是這張表。 它是協處理器對外的 API 合約，比任何架構文件都準確、都新。

搜尋路徑

**/ipi*.h
**/*mailbox*
**/mbox*/**
drivers/remoteproc/**

Prompt

找出這個 tree 裡所有協處理器 IPC 的訊息 ID 定義。
整理成表格：ID 名稱、方向（AP→remote / remote→AP）、同步或非同步、
payload 結構、送出端的呼叫點在哪個檔案。
先不要解釋語意，只要建立索引。

驗收問題

  • 哪些是同步（等 ack）、哪些是非同步？
  • 逾時會發生什麼？誰負責 timeout 處理？
  • 開機流程中第一個送出的訊息是哪一個、由誰觸發？

節點二：Device Tree —— 三種 domain 的地圖​

Lifecycle（remoteproc）、power（genpd）、memory（IOMMU / carveout）， 這三種 domain 的關聯圖其實完整攤在 dts 裡，只是沒人整理成一張圖。

Prompt

掃描所有 dts/dtsi，對每個帶有 power-domains、iommus、mboxes 或
memory-region 的 node，整理成表：
node | power domain | IOMMU | mailbox | 保留記憶體
最後用文字描述 power domain 之間的父子與相依關係。

驗收問題

  • 哪些 IP 共用同一個 power domain？關掉會一起掉的有哪些？
  • 哪些 IP 走 IOMMU、哪些直接吃實體位址？
  • 開機時 power domain 的開啟順序由什麼決定？

這一節的產出（一張圖）是整個過程中最實用的東西。 之後遇到「IP 沒上電 / DMA 失敗 / 開機卡住」，直接拿它定位。

節點三：一條完整的資料路徑​

挑一個代表性的請求（例如一次硬體加速的推論、一次影像 frame 送出）， 從 user space ioctl 追到硬體開始執行。

Prompt

追這個請求從 user space 到硬體執行的完整路徑。
列出每一層的檔案與函式，特別標出：
1. 記憶體在哪幾個點被轉換或重新映射
2. 命令在哪裡排隊、排隊策略是什麼
3. 電源狀態在哪裡被檢查與提升

驗收問題

  • 一次請求經過幾次記憶體位址轉換？
  • 硬體進入低功耗後，下一個請求的喚醒延遲花在哪一段？
  • 佇列滿了會怎樣？

節點四：EL3 / TF-A 那一層​

低功耗與 CPU 生命週期的決策，常常不在 kernel 裡。

搜尋路徑

plat/**/psci*
plat/**/*sip*
plat/**/*spm*

Prompt

找出這個平台的 SiP SMC handler 清單，以及低功耗流程中
EL3、協處理器、kernel 三方各自負責的部分。
畫出一次 system suspend 的完整序列：誰先做什麼、誰在等誰。

驗收問題

  • CPU idle 的決策是誰做的？EL3、協處理器、還是 kernel governor？
  • 哪些資源的 refcount 由 EL3 維護、哪些由 kernel 維護？
  • suspend 進不去時，最先該看哪一層？

節點五：版本歷史比文件誠實​

設計取捨的理由通常寫在 commit message 和 review 討論裡，不在文件裡。

Prompt

用 git log 找出這幾個模組近兩年變動最多的檔案，
以及對應的 commit message。整理出：
哪些設計是後來才改成現在這樣的、改的理由是什麼。

驗收問題

  • 有哪一個設計曾經被推翻過？當初的問題是什麼？

節點六：從故障回頭讀​

前五節讀的都是「正常運作時的樣子」，但異構系統真正的相依關係 只有壞掉時才會暴露。手上有 coredump 或失敗 log 的話，用它當入口：

Prompt

這份 log / coredump 對應的程式碼路徑在哪裡？
從錯誤碼往回追，列出可能的觸發點，並指出每個觸發點
需要哪些額外資訊才能排除。

驗收問題

  • 這個故障暴露了哪一組「誰欠誰 refcount」的關係？
  • 同樣的失效模式在其他子系統上會不會發生？

幾個實際踩到的坑​

Agent 很會編出合理但不存在的函式名。 每個關鍵結論都要自己 grep 驗證一次， 尤其是「這裡呼叫了 X」這類斷言。

別讓它一次讀整棵 tree。 分節提問、每節限定目錄，品質差很多。 一次丟太多，它會給你一份四平八穩但沒有資訊量的摘要。

驗收問題要自己先寫。 如果讓 agent 同時出題又答題，你只會得到自洽的幻覺。 問題清單是你的，答案才是它的。

適用範圍​

上面的路徑寫的是 Linux/TF-A 的通用結構，換平台大多只是換目錄名。 公開可讀的練習素材不少——mainline 裡的 drivers/remoteproc/、 各家 SoC 的 arch/arm64/boot/dts/、TF-A 的 plat/， 都可以直接拿來走一遍這六節。

一個必要的提醒：如果你操作的是雇主的 code base， 讀到的內容和公開發表的內容之間要劃清界線—— 檔名、函式名、暫存器名、時序數字、專案代號都屬於前者。 發表前走公司的 review 流程。