etwenandClaude Opus 5
24c704c667
Bring the Blanton Tera Term TTL test suite under version control and document how the pieces fit together. - ARCHITECTURE.md: A/B/C script roles, host-to-DUT-to-FPGA data path, config/settings/profile data models, PCIe AER + EDAC topology table, 10 key constraints, and 6 development phases derived from the Status_20260814 spreadsheet's On-Going items - CLAUDE.md: stack, smoke-test commands, conventions, and the hardware footguns (per-unit BDF, VSPI vs VI2C timing, repeated START, STORE_USER_ALL, ARB_LOST false positives) - secret/: gitignored credential store with README + .example template, so the DUT login stops living in 1_Blanton_Script_A.ttl - .gitignore: secret/*, For_AI/, *.log, publish/, *.DSN Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014RetWKFZFG1ZHcitQAyhwM
111 lines
6.9 KiB
Markdown
111 lines
6.9 KiB
Markdown
# CLAUDE.md — Blanton TTL Script
|
||
|
||
## 專案簡介
|
||
|
||
Blanton（Project Helios）交換器平台的系統層可靠性測試自動化腳本組。
|
||
Windows 端用 **Tera Term TTL macro** 透過 COM console 驅動 DUT 的 SONiC，
|
||
A / B / C 三支腳本分別跑「基線 → 壓力 soak → 收工判定」，全程存 log。
|
||
DUT 端的取數能力由一組 **bash 工具庫** 提供（CB FPGA `pcimem` → FPGA I2C/VI2C → VRM / 溫感 / LTC2980）。
|
||
|
||
完整架構見 [ARCHITECTURE.md](ARCHITECTURE.md)。
|
||
|
||
## 技術棧
|
||
|
||
- **Host**：Tera Term 5.x TTL macro（`.ttl`），Windows
|
||
- **DUT**：SONiC（Debian-based），bash + busybox/mawk，`root@sonic:~#`
|
||
- **暫存器存取**：`pcimem`（mmap PCI sysfs `resource0` + BAR 相對 offset，一律 32-bit word）
|
||
- **I2C/PMBus**：CB FPGA F3 I2C master（Ch0~Ch17，base 0x300 stride 0x20）、
|
||
CB F3 VI2C proxy → ICB/PDB（Ch0~Ch4，base 0x780）、CPU 原生 bus（`i2cset`/`i2cget`）
|
||
- **Margin**：LTC2980（= 2 × LTC2977）over PMBus，LINEAR16
|
||
- **判定資料源**：PCIe AER sysfs（`aer_dev_*`）、EDAC sysfs（`dimm_{ce,ue}_count`）、SONiC `show platform *`
|
||
- **無編譯步驟**：TTL 與 bash 都直譯執行
|
||
|
||
## 常用指令
|
||
|
||
```bash
|
||
# ── 部署 bash 工具庫到 DUT ──────────────────────────
|
||
scp -r src/Script_ABC_Blanton/Blanton_Script admin@<DUT_IP>:~/
|
||
|
||
# ── DUT 上先確認 FPGA BDF（每台不同！）───────────────
|
||
lspci -Dnn | grep -i fpga
|
||
ls -d /sys/bus/pci/devices/0000:*:00.3
|
||
|
||
# ── DUT 上載入工具（Script A 也是做這五件事）─────────
|
||
source ~/Blanton_Script/blanton_fpga_pcimem.sh
|
||
source ~/Blanton_Script/blanton_cb_i2c.sh
|
||
source ~/Blanton_Script/blanton_icb_vi2c.sh
|
||
source ~/Blanton_Script/blanton_pwr_data.sh
|
||
source ~/Blanton_Script/LTC2980_Margin_Script/margin.sh
|
||
|
||
# ── 煙霧測試 ────────────────────────────────────────
|
||
cb_fpga 0 0xD90 # RST_CAUSE_REG，讀得到 = BAR 通了
|
||
cb_i2c_init 11 && cb_i2c_scan 11 # Ch11 風扇控制器，應看到 0x20
|
||
vi2c_scan_all # ICB/PDB 五個通道
|
||
temp_all # CB + ICB 溫感
|
||
pwr_data # SWB VRM 全軌
|
||
margin_init Blanton_CB_CONN13 && margin_status
|
||
|
||
# ── 各工具的 help ───────────────────────────────────
|
||
blanton_fpga_help ; blanton_cb_i2c_help ; vi2c_help
|
||
temp_sensor_help ; pwr_data_help
|
||
```
|
||
|
||
**Host 端跑一輪測試：**
|
||
|
||
```
|
||
Tera Term 連 COM port (115200-8-N-1)
|
||
→ Control → Macro → 1_Blanton_Script_A.ttl (基線，跑完出 messagebox)
|
||
→ 手動跑 2_Blanton_Script_B.ttl (壓力 soak，while 1 迴圈，泡到時間到停掉)
|
||
→ 手動跑 3_Blanton_Script_C.ttl (kill + 收工快照 + 判定)
|
||
→ 檢查 Logs\Blanton_Margin_<ts>.log
|
||
```
|
||
|
||
## 開發慣例
|
||
|
||
- **執行單位**：`src/Script_ABC_Blanton/` 整包給測試員（Tera Term 工作目錄）；
|
||
其中 `Blanton_Script/` 是 scp 到 DUT `~/` 的單位
|
||
- **TTL 分層**：`config.ttl` 放設定 → 三支主腳本編排流程 → `utils/*.ttl` 是可 include 的無狀態片段
|
||
（只做 `wait prompt_sonic_root` + `sendln`，不設變數、不 logopen）
|
||
- **新增取數項目** = 新增一支 `utils/show_xxx.ttl`，再在主腳本 `include`，不要往主腳本塞指令
|
||
- **bash 命名**：公開函數 `cb_i2c_* / vi2c_* / temp_* / pwr_* / margin_*`，內部 helper 一律底線開頭
|
||
（`_cbi2c_* / _vr / _ts_* / _pwr_*`）
|
||
- **版本紀錄**：每支 `.ttl` 與 `.sh` 檔頭都有 `Version History` 區塊，改動時**在檔頭補一行**
|
||
（`V1.0.2 YYYY-MM-DD <做了什麼>`），不要只改版號
|
||
- **Commit**：Conventional Commits，**英文**。scope 用 `ttl` / `fpga` / `i2c` / `vi2c` /
|
||
`margin` / `pwr` / `temp` / `docs`
|
||
- **Status 表**：`docs/TTL_Script_Blanton_Status_*.xlsx` 是逐項進度的正本（OK / On-Going + Owner），
|
||
完成一項就同步更新，別讓文件跟腳本脫節
|
||
|
||
## 注意事項
|
||
|
||
- 🔒 **NDA：本 repo 只推 `nas` + `gitea`，絕不推 GitHub。** `docs/` 內含客戶 FPGA 規格。
|
||
- 🔒 **DUT 帳密不進 git**。`1_Blanton_Script_A.ttl` 的 `sendln "YourPaSsWoRd"` 是 placeholder，
|
||
實際值放 `secret/config_secret.ttl`（gitignored）。**任何 commit 前先 grep 一次確認沒帶到真密碼。**
|
||
- ⚠️ **PCIe BDF 是 per-unit 的**。`blanton_fpga_pcimem.sh` 的 `FUNCT0..3_RES` 已經改過三次
|
||
（04:00.x → 03:00.x → 05:00.x → 03:00.x）。換 DUT 一定先 `lspci -Dnn | grep -i fpga`，
|
||
`utils/show_pcie_error_reg_*.ttl` 內的 BDF 也要一起校。
|
||
- ⚠️ **AER 判定看差值不看絕對值**：Script A 抓基線、Script C 抓結果，相減才是本輪錯誤。
|
||
**Endpoint 與上游 Root Port 兩邊都要讀**，錯誤可能只記在 RP。
|
||
- ⚠️ **ICB/PDB 一律走 VI2C（`blanton_icb_vi2c.sh`），不要走 VSPI**：VSPI ~18 ms/reg 會讓 I2C
|
||
byte 相間隔拉到 ~50 ms，踩中 SMBus 25–35 ms timeout，裝置直接 NACK。實測全掃 9.4 s vs 34.0 s。
|
||
- ⚠️ **I2C 讀一律 Repeated START**（不是 STOP + START），否則 PMBus/SMBus 裝置（VRM、EFUSE）不理。
|
||
- ⚠️ **`margin_save` / `STORE_USER_ALL` 會永久寫 NVM**，斷電保留 → **測試流程中絕不執行**，
|
||
以免覆蓋客戶出廠 config。`margin.sh` 的 auto-enable（`ON_OFF_CONFIG=0x1a`）只改 RAM，斷電復原。
|
||
- ⚠️ **改電壓會弄壞 DUT**：套 profile 前確認該軌 OV/UV limit，且 servo DAC 注入電阻有 populate
|
||
（本板部分 margin 電阻標 PROTO，沒 populate 的軌電壓不會動，不是腳本壞掉）。
|
||
- ⚠️ **`ARB_LOST` ≠ 有裝置**：`vi2c_scan` 只看 `RX_ACK`，仲裁失敗會被誤報成裝置存在。
|
||
`blanton_pwr_data.sh` 已加 retry + plausibility window，**寧可印 `NA` 也不要印看起來像數據的錯值**。
|
||
- ⚠️ **A → B → C 必須同一個 Tera Term session**：B 的背景 job 與 C 的 `kill $(jobs -p)` 綁在同一個
|
||
shell；log 也只有 A 會 `logopen`，B/C 是續寫。中途關掉 window 就得手動收程序、log 也斷了。
|
||
- ⚠️ **MP29816 的 Vout 解析度不是固定值**，由 `MFR_VOUT_SCALE_LOOP(0x29)` bit[12:10] 決定，
|
||
`blanton_pwr_data.sh` 執行期從晶片讀；xlsx 上寫的 `/5mV` 與 MP2985B 的 `+49` offset **都是錯的**。
|
||
|
||
## 資料夾說明
|
||
|
||
- `src/Script_ABC_Blanton/` — 可執行內容（Tera Term 工作目錄；內含要 scp 到 DUT 的 `Blanton_Script/`）
|
||
- `docs/` — 客戶 FPGA 規格、AER/EDAC 檢查依據、逐項 Status 表
|
||
- `tools/` — Host 端輔助腳本（log 解析、報表產生、打包）
|
||
- `publish/` — 交付用打包輸出（`Blanton_Script_ABC_v<ver>_<date>/` + zip）
|
||
- `secret/` — 🚫 gitignored（除 `README.md` 與 `*.example`）：DUT 帳密、per-unit BDF 覆寫、COM 設定
|
||
- `For_AI/` — 🚫 gitignored：AI 協作素材（波形截圖、草稿筆記）
|