Blanton_TTL_Script_Diag/CLAUDE.md

CLAUDE.md — Blanton TTL Script (Diag)

專案簡介

Blanton（Project Helios）交換器平台在 Diag OS（ODM 診斷映像，非 SONiC）下的驗證自動化腳本組。 Windows 端用 Tera Term TTL macro 透過 COM console 驅動 DUT， A / B / C 三支腳本分別跑「功能掃描 → 壓力 soak → 收工判定」，全程存 log。 取數能力全部來自 Diag image 內建的 acc_* 指令集 與 swutil，本專案是純 TTL，沒有 bash 工具庫。

姊妹專案 Blanton_TTL_Script 是同一片硬體的 SONiC 版（有 bash 工具庫）。 兩邊不共用檔案，config.ttl 同名但 prompt 不同，不要互相複製。

完整架構見 ARCHITECTURE.md。

技術棧

• Host：Tera Term 5.x TTL macro（.ttl），Windows
• DUT：ODM Diag OS（busybox 風格），提示字元 root@(none):~#，直接 root、無登入互動
• 診斷指令：acc_<domain>_<device> <subcmd> 家族 —— domain 有 misc / pld / pwr / bmc / iai / dram / fs / scy / net / temp / cool / time / led
• 交換晶片：swutil（*: = 全 unit、1: = unit 1、dsh -c 轉發 Broadcom drivshell）
• 板級 EEPROM：onie-syseeprom -t cpu（ONIE TLV）
• 無編譯步驟：TTL 直譯執行，「build」= 把 src/Script_ABC_Blanton_Diag/ 複製到 Tera Term 工作目錄

常用指令

Host 端跑一輪測試：

Tera Term 連 diag console COM port (115200-8-N-1)
→ 先按一次 Enter，確認提示字元是 root@(none):~#     ← 不符就改 config.ttl 的 prompt_diag
→ 確認工作目錄下有 Logs\                            ← logopen 不會自建目錄
→ Control → Macro → 1_Blanton_Script_A.ttl          (功能掃描，目前唯一完整的一支)
→ 手動跑 2_Blanton_Script_B.ttl                     (壓力 soak，while 1，泡到時間到停掉)
→ 手動跑 3_Blanton_Script_C.ttl                     (收工判定)
→ 檢查 Logs\Blanton_Margin_<ts>.log
→ 收工還原：風扇回 auto、config.yml 的 AUTO 與 extphy_init_LT.soc 復原

DUT 端煙霧測試（跑 Script A 前先手動敲）：

version                    # 有輸出 = console 通了
acc_iai_i2c device         # I2C 列舉，對照 golden list
acc_iai_pcie device        # PCIe 列舉
acc_misc_liquid info       # 漏液狀態，異常就別往下跑

Script A 涵蓋的主要指令（依執行順序）：

version ; acc_misc_version bios|i210|mac ; acc_pld util cb 0 0x0
acc_pwr_mon show d2d ; acc_bmc_board info
acc_misc_liquid info                      # 漏液
onie-syseeprom -t cpu                     # ONIE EEPROM
acc_iai_i2c device ; acc_iai_pcie device  # 匯流排列舉
acc_dram_cpu info|rw|chkecc               # DDR
acc_bmc_iai i2c_device ; acc_bmc_net usb_ping ; acc_bmc_fs spi_test
acc_bmc_dram rw ; acc_bmc_e2p bmc_r       # BMC 子系統
acc_fs_ssd info|rw|selftest short ; acc_fs_usb rw
acc_scy_tpm ; acc_scy_nfc test            # 安全元件
acc_net_cpu traffic mgmtp                 # MGMT 埠流量
acc_temp_thermal ddr|cpu|sensor ; acc_cool_fan speed 30 ; acc_time_rtc test
100init.sh ; acc_net_mac 100G             # 100G
swutil *:ps cd ; swutil *:port cd en=0|1  # 埠狀態 / down-up
acc_net_mac ber -m berproj -p all
acc_net_mac fec -p all
acc_net_mac fdr -m fdr -u all
# TH6：改 config.yml AUTO 0→1、停用 extphy_init_LT.soc、swutil -C -r、dsh 'tr 39'/'tr 55'

開發慣例

• 執行單位：src/Script_ABC_Blanton_Diag/ 整包給測試員（Tera Term 工作目錄）
• TTL 分層：config.ttl 放設定 → 三支主腳本編排流程 → utils/*.ttl 是可 include 的無狀態片段 （只做 wait prompt_diag + sendln，不設變數、不 logopen）
• 新增取數項目 = 新增一支 utils/show_xxx.ttl，再在主腳本 include，不要往主腳本塞指令 （目前 Script A 還是一整條直線，Phase 2 才會拆 —— 新東西直接照新慣例寫）
• 開關用旗標不用註解：要不要跑某個區塊，用 config.ttl 的 EN_* 控制 （現在 LED 測試是用註解關掉的，這是要修的反例）
• 版本紀錄：1_Blanton_Script_A.ttl 檔頭的 Version History 是三支腳本的集中紀錄， 改動時在檔頭補一行（V1.0.1 YYYY-MM-DD <做了什麼>），不要只改版號
• 換行符：.ttl 維持 CRLF（只在 Windows 上跑），.gitattributes 已標 -text； .sh / .md / .py 一律 LF
• Commit：Conventional Commits，英文。scope 用 ttl / diag / bmc / net / th6 / docs

注意事項

• ⚠️ Logs\ 資料夾必須先存在，logopen 不會自建。缺了就整支 macro 在第一步失敗， 而且因為還沒開 log，失敗現場什麼都不會留下。repo 內用 .gitkeep 保留這個目錄。
• ⚠️ prompt_diag = "root@(none):~#" 是全專案唯一的同步基準。Diag image 換版、 hostname 被設定、prompt 客製化 → 整組腳本卡在第一個 wait，畫面上看起來像「當掉」。 換 image 先手動按 Enter 確認這一行。
• ⚠️ wait 沒有 timeout 就是無限等。acc_fs_ssd selftest short、acc_net_mac ber、 acc_dram_cpu rw、acc_bmc_dram rw 都可能跑很久或掛住， 現行腳本沒有逾時保護 —— macro 會永遠停在那一行，且看不出是還在跑還是死了。
• 🔴 utils/show_margin_status.ttl 目前不存在，但 2_Blanton_Script_B.ttl 已經 include 它。 EN_Margin=1 時 Script B 會失敗。修好之前，現場請先在 config.ttl 設 EN_Margin=0。
• ⚠️ Script B 的 while 1 迴圈裡沒有 pause，註解寫「Get data every 10mins」但實際上是 全速空轉，取樣間隔取決於指令執行時間。（Phase 3 要補 EN_LoopInterval。）
• ⚠️ TH6 段落會改 DUT 的檔案且不還原：sed -i 把 config.yml 的 AUTO: 0 改成 1、 把 extphy_init_LT.soc 改名成 .temp。跑完的 DUT 不是出廠狀態，交機前要手動復原。
• ⚠️ acc_cool_fan speed 30 之後沒有還原成自動控制。高負載 soak 時有過熱風險，測完要確認。
• ⚠️ swutil *:port cd en=0 會把埠打掉。用 SSH 而非 COM console 操作時會斷線。
• ⚠️ 一堆 rw 是寫入測試（acc_dram_cpu rw、acc_bmc_dram rw、acc_fs_ssd rw、 acc_fs_usb rw），只能對測試機跑，絕不可對客戶已上線的機器執行。
• ⚠️ 漏液檢查優先於一切（液冷平台）。acc_misc_liquid info 異常時直接中止，別繼續往下測。
• ⚠️ A → B → C 必須同一個 Tera Term session：只有 A 會 logopen，B / C 是 logwrite 續寫。 中途關掉 window，log 就斷了。
• ⚠️ tr 39 / tr 55 的測項定義還沒留檔（Broadcom SDK 內建編號）。 log 裡只看得到編號，看不出測了什麼 —— 拿到 SDK 文件請補進 docs/。
• 🔒 Gitea 上本 repo 依指示設為 public。docs/ 放客戶提供的文件前務必再確認一次， 只有可公開的內容才進 repo。

資料夾說明

• src/Script_ABC_Blanton_Diag/ — 可執行內容（Tera Term 工作目錄，整包給測試員）
• docs/ — 規格與狀態文件（待放：Diag 指令手冊、tr <n> 對照、逐項 Status 表）
• tools/ — Host / 離線端輔助腳本（待放：log 解析器）
• publish/ — 交付用打包輸出（Blanton_Script_ABC_Diag_v<ver>_<date>/ + zip）
• secret/ — 🚫 gitignored（除 README.md 與 *.example）：COM 設定、per-unit 覆寫、未公開附件
• For_AI/ — 🚫 gitignored：AI 協作素材（截圖、草稿筆記）