Blanton_TTL_Script/CLAUDE.md

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。

目前狀態（2026-09-06）：Script A 為 V1.1.8（A 集中記錄所有 TTL 的變更）。涵蓋 PCIe AER / DDR EDAC / PMON+TPM / 電壓 margin（9 顆 LTC2980）/ SWB loopback 線速流量 / 10G+1G 管理網路 ping / BMC DDR 與 USB / NVMe 健康，壓力層走平台的 bgctl。 switch unit 數量由 config.ttl 的 SWB_UNIT0 / SWB_UNIT1 宣告，風扇轉速由 FAN_SPEED 指定 （預設 100 = 全速；soak 是熱測試，散熱不該是變因）。 測試 job log 收在 DUT 的 /host/hw-eval/jobs/，Script C 結束時掛好 USB 再帶時戳複製到 /mnt/usb/。 100G PRBS（port_prbs_monitor.sh）已隨包交付，但 A/B/C 的呼叫仍註解掉，還在 bring-up。 Script B 的 soak 迴圈每輪印 bgctl list + jobs + systemctl is-active mlucas-amm，並 pause 60 （V1.0.10 之前完全沒有 pause）。V1.1.8 起 AMD CPU 壓力（mlucas-avx2）由 systemd-run 掛成 mlucas-amm transient unit（Restart=always），不再是 shell 的 & 背景 job —— 掉線也不會停， Script C 用 systemctl stop mlucas-amm 收掉並把 log 複製到隨身碟。 V1.1.0 新增全機 SerDes BER 掃描（blanton_ber.sh，Script C 已接，依 SWB_UNIT 分支）、 TR518 負載（blanton_tr518.sh，TTL 尚未接）、SWB 軌功耗（TH6_SWB{0,1}_power_readback.sh）， 線速流量也納入 100G ce0（VLAN 138，靠 ingress mirror 維持循環）。 Script A 開頭會先收掉前一輪殘留（hw-test-session finish + bgctl reset/stop --all）， 再 bgctl list 確認沒有 job 留著佔資源。 NFC tag 讀取由 nfc_polling.sh 背景輪詢（A 做基線、B 起、C 停並 report）。 另有 4_Blanton_Script_thermal_safety.ttl（熱 / 安規，獨立跑不接 A→B→C，滿載後每分鐘 取 PMON + 兩片 SWB 的軌功耗；沒有收尾段，中斷後要手動 blanton_tr518.sh stop）。 以及 5_Blanton_Script_Reboot_Cycle.ttl（重開機循環，獨立跑不接 A→B→C：登入 → 風扇 → Check Pt1Pt13 → reboot → wait "Booting in blind mode"，cnt_cycle 每輪遞增，while 1 無止境， 要停就關 Tera Term 的 macro）。尚未上機驗證。 流程圖：docs/Blanton_Test_Flow.drawio。 最後一次發布是 V1.1.5；SWB 的 I2C 通道與位址已於 2026-08-19 上機驗證。 margin 的 VNOM 已於 2026-08-30 改為 Blanton 實測中位數（144 條軌中 86 條上調 0.82.5%）。 交付用 ./publish/publish.sh 打包。

技術棧

• 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（Ch0Ch17，base 0x300 stride 0x20）、 CB F3 VI2C proxy → ICB/PDB（Ch0Ch4，base 0x780）、CPU 原生 bus（i2cset/i2cget）
• Margin：LTC2980（= 2 × LTC2977）over PMBus，LINEAR16
• 資料面流量：bcmcmd（Broadcom drivshell）SWB loopback，VLAN 30..137 成對 cdN/cdN+32， tx 100 length=512；判定讀 ASIC MIB_TPOK/MIB_RPOK 做 per-pair 雙向交叉比對
• BMC：host 端 bmc-manager run "<cmd>"，不需對 BMC 開 SSH（繞開其 busybox 工具鏈）
• 背景工作：平台的 bgctl run/list/stop --all/reset；長時間 ping 用 systemd-run --unit= 掛 transient unit
• 管理網路：iproute2（ip link set / address replace / route replace ... metric）+ ping -I
• 風扇：max31790 driver rebind + fan-speed-control.sh <%>（轉速讀 config.ttl 的 FAN_SPEED）
• 判定資料源：PCIe AER sysfs（aer_dev_*）、EDAC sysfs（dimm_{ce,ue}_count）、SONiC show platform *
• 無編譯步驟：TTL 與 bash 都直譯執行

常用指令

# ── 部署 bash 工具庫到 DUT ──────────────────────────
scp -r src/Script_ABC_Blanton/Blanton_Script admin@<DUT_IP>:~/

# ── DUT 上載入工具（Script A 也是做這六件事）─────────
source ~/Blanton_Script/blanton_fpga_pcimem.sh   # ← 會自己印出偵測到的 CB FPGA BDF
source ~/Blanton_Script/blanton_cb_i2c.sh
source ~/Blanton_Script/blanton_icb_vi2c.sh
source ~/Blanton_Script/blanton_pwr_data.sh
source ~/Blanton_Script/blanton_traffic_linespeed.sh
source ~/Blanton_Script/LTC2980_Margin_Script/margin.sh

# ── FPGA BDF：自動偵測，不用改檔；必要時手動釘 ───────
fpga_rescan                          # 換 DUT / 重新列舉後重測
FPGA_BDF=0000:05:00 fpga_rescan      # 偵測到多顆或選錯時，指定 domain:bus:dev（不含 .fn）
echo $FPGA_BDF_ACTIVE                # 目前生效的 BDF

# ── 煙霧測試 ────────────────────────────────────────
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

# ── 電壓 margin 寫 NVM（⚠️ 永久，測試中絕不執行）─────
margin_save                        # 只寫當前 margin_init 載入的那顆（2 個 LTC2977）
margin_save all                    # settings/ 全部 9 顆；跑完自動切回原本載入的那顆
margin_save blanton                # Blanton SONiC 捷徑：18 顆全走原生 i2c，不用 margin_init
#   0x15 是 send-byte，不帶 data byte：i2cset -f -y <bus> <addr> 0x15
#   bus = FPGA F3 通道 + 7 → Ch6=13, Ch7=14, Ch8=15, Ch9=16（CB 本來就是 bus 4）
#   ⚠️ 沒裝滿的機器：改 margin.sh 頂端的 MARGIN_BLANTON_STORE，把沒有的板子註解掉

# ── SWB loopback 流量（bcmcmd，unit 0/1）─────────────
# 不帶 -u 就是預設 TL_UNITS="0 1"，兩塊 switch board 都做（TTL 三支腳本即如此）
blanton_traffic_linespeed ps             # 對照線的 link/speed
blanton_traffic_linespeed init           # VLAN 30..137，cdN <-> cdN+32
blanton_traffic_linespeed clear          # clear c
blanton_traffic_linespeed start -tx 100 -length 512
blanton_traffic_linespeed stop           # 移除 VLAN 成員（--destroy 連 VLAN 一起砍）
blanton_traffic_linespeed report         # per-pair TX/RX + PASS/FAIL（exit 2 = 有 FAIL/NA）
blanton_traffic_linespeed run            # ps → init → clear → start → report 一條龍
blanton_traffic_linespeed init   -u 0    # 只做單一 unit 時才需要 -u
blanton_traffic_linespeed init   -n      # -n dry-run：只印要下的 bcmcmd，不碰 DUT
blanton_traffic_linespeed report -f <log>  # 離線重解一份存下來的 console log

# 離線版報表（開發機上跑，選項更多）
python3 tools/bcm_mibpair_report_V1.1.0.py <drivshell.log> -a

# ── 管理網路 ping 監控（需先 chmod +x！）──────────────
chmod +x ~/Blanton_Script/*.sh               # 佈署後必做一次
~/Blanton_Script/mgmt_ping_monitor.sh fg     # 前景試一輪（約 30 秒），確認 IP/對端/網卡
~/Blanton_Script/mgmt_ping_monitor.sh start  # 背景，log/mgmt_ping.log（start 會先清空）
~/Blanton_Script/mgmt_ping_monitor.sh status
~/Blanton_Script/mgmt_ping_monitor.sh stop
~/Blanton_Script/mgmt_ping_monitor.sh summary  # 只看每段的 RESULT 行
#   ⚠️ tail 子命令是 tail -f，會卡住不返回；TTL 裡要倒 log 請用 cat
#   bmc_monitor.sh   start/stop         # free -m + BMC I2C 寫入/讀回圖樣測試，log/bmc_poll.log
#   ⚠️ bmc_monitor_ddr.sh 已停用（DDR 壓力改走 bgctl + bmc-manager），檔案仍在

# ── 100G PRBS（目前 TTL 未啟用，手動測用）────────────
bash ~/Blanton_Script/port_prbs_monitor.sh start        # 兩個 port 同時
bash ~/Blanton_Script/port_prbs_monitor.sh start a      # 只跑 Ethernet513
bash ~/Blanton_Script/port_prbs_monitor.sh start b      # 只跑 Ethernet514
bash ~/Blanton_Script/port_prbs_monitor.sh report       # PASS/FAIL 統計（沒跑的顯示 SKIP）
bash ~/Blanton_Script/port_prbs_monitor.sh stop         # 收尾會跑 prbsstat STOp + prbs clear
#   ⚠️ PRBS 打起來時 link 會顯示 down，這是正常的 —— 所以 start 刻意不印 port status

# ── PDB / CPB power brick 讀值 ──────────────────────
./Blanton_Script/pwr_brick.sh show         # Vin/Iin/Vout/Iout/Temp × 5 顆
./Blanton_Script/pwr_brick.sh show -r      # 多印 raw word
#   四顆 ADPM12200 每個量各一個 PMBus PAGE：Vin 9 / Iin 10 / Vout 2 / Iout 14 / Temp 18
#   CPB.PU37 (0x26) 是不同零件：不寫 PAGE，自己一套換算
#   PB_TRIES=1 ... show -r  可看未經重試的原始行為

# ── 多相 VRM margin（原生 i2c，38 條軌）──────────────
./Blanton_Script/blanton_multiphase_margin.sh high3    # 全部 +3%
./Blanton_Script/blanton_multiphase_margin.sh low3     # 全部 -3%
./Blanton_Script/blanton_multiphase_margin.sh comboA   # 混合，組合 A
./Blanton_Script/blanton_multiphase_margin.sh comboB   # 混合，組合 B
./Blanton_Script/blanton_multiphase_margin.sh save     # ⚠️ 永久寫 NVM
#   -u 0 / -u 1 單邊（SWB0=i2c-13/15，SWB1=i2c-14/16）；-n 只印指令
#   逐條印 SWB0_0V9_ANLG0 - 0.930V Configure Done；save 只印 Multiphase Save All
#   ⚠️ 這不是 margin.sh 管的 LTC2980，兩支摸同一批軌，不要同時用

# ── 全機 SerDes BER（PRBS，期間 link 會顯示 DOWN）────
./Blanton_Script/blanton_ber.sh init          # prbs set p=3 + prbs get（檢查每條 lane 鎖定）
./Blanton_Script/blanton_ber.sh start         # prbsstat STArt Interval=30
sleep 30                                      # 至少等一個 interval 再 report
./Blanton_Script/blanton_ber.sh report        # 每 lane 一列，BER < 1e-6 才 PASS，最後 summary
./Blanton_Script/blanton_ber.sh stop          # prbsstat STOp
./Blanton_Script/blanton_ber.sh clear         # prbs clear（會解除 PRBS，要重測得再 init）
#   -u 0 / -u 1 單邊；-c 1e-9 換門檻；-F 只列失敗；-f <log> 離線重解
#   ⚠️ 不能跟 blanton_traffic_linespeed / blanton_tr518 同時跑（都會接管同一批 port）

# ── TR518 負載 + 量功耗（TTL 尚未接）─────────────────
./Blanton_Script/blanton_tr518.sh start       # 兩 unit，跑完 settle 120s
./Blanton_Script/TH6_SWB0_power_readback.sh   # 19 條軌 V×I + TOTAL POWER
./Blanton_Script/TH6_SWB1_power_readback.sh
./Blanton_Script/blanton_tr518.sh stop        # 只送 port cd lb=none
#   ⚠️ stop 不還原 l2 learn / test mode（TR_RESTORE_LEARN=1 / _TESTMODE=1 才會）

# ── NFC tag 輪詢 ────────────────────────────────────
~/Blanton_Script/nfc_polling.sh start      # 背景，start 會先清空 log
~/Blanton_Script/nfc_polling.sh status     # pid、已跑幾輪、最後一筆結果
~/Blanton_Script/nfc_polling.sh report     # PASS/FAIL/ERROR 統計，polling 中也能跑
~/Blanton_Script/nfc_polling.sh tail 50    # 最後 50 行（不 follow，不會卡住）
~/Blanton_Script/nfc_polling.sh stop
#   log: ~/Blanton_Script/log/nfc_poll.log
#   ERROR = 工具沒印出 [PASS]/[FAIL]（或逾時），跟「tag 讀不到」分開算
#   NFC_INTERVAL_SEC / NFC_TIMEOUT_SEC / NFC_ARGS 可調（要每個子指令都帶）

# ── USB 目標偵測 ────────────────────────────────────
bash ~/Blanton_Script/usb_target.sh -o dev              # /dev/sdX1
bash ~/Blanton_Script/usb_target.sh -o mnt              # 掛好並回傳掛載點

# ── 背景壓力（平台工具）──────────────────────────────
bgctl run /usr/sbin/memtester 1G 100
bgctl list
bgctl stop --all ; bgctl reset --yes

# ── 通道對照表（開發機上跑，改完 settings/*.conf 一定要重產）──
./tools/gen_channel_map.sh              # → docs/LTC2980_channel_map.csv（144 列）
./tools/gen_channel_map.sh -            # 只印到 stdout
#   ⚠️ 需要 gawk（用到 3 參數的 match()）；mawk 會直接擋下並提示

# ── 各工具的 help ───────────────────────────────────
blanton_fpga_help ; blanton_cb_i2c_help ; vi2c_help
temp_sensor_help ; pwr_data_help ; blanton_traffic_linespeed_help

打包交付（在開發機上）：

./publish/publish.sh          # 版號讀 Script A 檔頭 → publish/Script_ABC_Blanton_V1.0.3/
./publish/publish.sh -z       # 另出 zip
./publish/publish.sh -n       # dry run

要出新版先改 Script A 檔頭的 ; Version :，publish 才會用新版號建資料夾。

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_*）
• 版本紀錄：.sh 每支檔頭都有 Version History 區塊，改動時在檔頭補一行 （V1.0.2 YYYY-MM-DD <做了什麼>），不要只改版號。 TTL 這邊 2026-08-17 起改為集中制：1_Blanton_Script_A.ttl 的 History 記錄 A/B/C 三支的 所有變更，B 與 C 的檔頭版本區塊已移除。⚠️ 這是待確認的慣例變更 —— 若要回到「每支各自記錄」，B/C 的 History 需要補回去
• Commit：Conventional Commits，英文。scope 用 ttl / fpga / i2c / vi2c / margin / pwr / temp / docs
• 換行符：由 .gitattributes 管理 —— *.sh *.conf *.py *.txt *.md 釘 LF （要在 SONiC 上跑／被 source），*.ttl 維持 CRLF（Tera Term 只在 Windows 跑）。 編輯 .ttl 時要保留 CRLF，別讓整檔變成 LF 產生假 diff
• 打包：./publish/publish.sh，版號讀 Script A 檔頭不是參數 —— 先改檔頭再打包
• 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 的 —— bash 端已自動化，TTL 端還沒。 blanton_fpga_pcimem.sh V1.5.0（2026-08-17）起 source 時自動偵測（sysfs vendor 0x1590 → lspci → FPGA_BDF_FALLBACK），不用再每台改檔；印一行 [INFO] CB FPGA BDF = ...， 可用 fpga_rescan 重測、FPGA_BDF=... fpga_rescan 手動釘住。 但 utils/show_pcie_error_reg_*.ttl 裡的 7 組 BDF 仍是寫死的，換 DUT 還是要人工校對 —— 不校就會讀到別的裝置，或整段 No such file or directory。
• ⚠️ 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）不理。
• ⚠️ Script C 的 BMC USB service log 不進 master log：改成 journalctl ... > log/bmc_usb_net.log 再複製到隨身碟，那是唯一一份。 收工後翻不到就先確認 job 目錄裡有沒有這個檔
• ⚠️ VI2C 這條路的壞法是「只壞高位元組」，不是整包壞掉。11.98 V 會變成 32.00 V —— 正的、數量級也不誇張，擋全一/全零的過濾完全攔不到。寫任何 VI2C 讀值工具都要有 合理範圍檢查 + 重讀，光靠 PDB_REJECT_FFFF 那種是不夠的（pwr_brick.sh 的教訓）
• ⚠️ PMBus 的 PAGE 不是只有 VRM 通道在用：ADPM12200 把每個量測放在不同 PAGE （Vin 9 / Iin 10 / Vout 2 / Iout 14 / Temp 18），沒寫 PAGE 就讀，回的是 0xFFFF 或 0x0000。blanton_pwr_data.sh 的 PDB 表 page 是 -，這就是它整張表 NA 的原因
• ⚠️ --runtime 是整個 job 的總時限，不是每個 pass 的：V1.1.7 起由 config.ttl 的 SSD_RUNTIME/SSD_COUNT、USB_RUNTIME/USB_COUNT 指定（COUNT 就是 --passes）。 qfx5252-stress-* 跑滿 RUNTIME 秒就停，--passes 不會把它延長 —— RUNTIME=600 就是 10 分鐘，不是 600×COUNT。要 24 小時就填 86400。壓力提早結束時 bgctl list 數量變少是 唯一線索，不會報警。V1.1.8 起出貨預設改為 RUNTIME=3600（1 小時），2 天 soak 要填 172800
• ⚠️ utils/kill_all_process.ttl 只有 kill $(jobs -p)，抓不到 systemd unit：把壓力工作改成 systemd-run 之後，Script C 一定要補對應的 systemctl stop <unit>，否則它會活過 Script C 燒進 下一輪，收工的溫度／功耗全部是在滿載下量的。V1.1.8 已為 mlucas-amm 補上。 Script 4 也改用同一個 unit，但它沒有收尾段，所以那行 systemctl stop 得由人手動下
• ⚠️ config.ttl 少一個變數會讓 macro 當場中止，不是當成 0：EN_timestamp（V1.1.8 新增， 餵 Script A logopen 的第 5 個參數）、BMC_USB_RUNTIME 都是必要項。只更新 .ttl 卻沿用舊的 config.ttl，Script A 會停在 logopen 那一行
• ⚠️ log 時間戳的「格式」不在腳本裡：EN_timestamp 只決定開不開，格式在 Tera Term 的 Setup → Additional settings → Log，存在那台電腦的 TERATERM.INI。同一份 macro 在兩台機器上 可以產生不同格式的 log，跨機比對前先確認
• ⚠️ 多相 VRM 與 LTC2980 是同一批軌的兩條路：blanton_multiphase_margin.sh（原生 i2c） 和 margin.sh（LTC2980 PMBus）都假設自己是唯一寫入者，沒有互斥檢查，只靠人記得
• ⚠️ traffic 的計數器基準在 v0.7.0 變了：tx 100 length=512 → tx 200 length=324， 每 burst 的位元組數 +27%。PASS/FAIL 是成對交叉比對不受影響，但絕對值不能跟舊 log 比
• ⚠️ Script 4（thermal/safety）沒有收尾：while 1 之後就是檔尾。中斷後 DUT 停在 port cd lb=mac / l2 learn off / test mode nr=yes，mlucas-avx2 也還在背景。 下一個測試會在被污染的狀態上開始，而且 show interfaces status 看不出來。 收尾：blanton_tr518.sh stop + kill $(jobs -p) + systemctl stop mlucas-amm （V1.1.8 起 CPU 壓力是 systemd unit，kill $(jobs -p) 收不掉，少這一行 CPU 會一直滿載）
• ⚠️ Script 4 與 Script B 不能共用同一台 DUT：兩者都會接管 port cd 的 loopback
• ⚠️ settings/*.conf 的 VNOM 是實測中位數，不是規格值（2026-08-30 起）。它同時是 margin_status 偏差 % 的分母、也是 margin_set 推算 high/low/OV/UV 的基準，所以改它會 同時移動「看到的數字」和「實際打出去的電壓」。跨這個日期的 margin log 不能直接互比。
• ⚠️ SWB 的 margin profile 是 per-CONN 的：combo_SWB_CONN13~16_{high,low} 各自的百分比 對應該片板子的軌。套到別的 CONN 會 margin 到錯的軌，而且不會報錯。CB 沒有專屬 profile， 用通用的 combo_high3 / combo_low3
• ⚠️ margin_save / STORE_USER_ALL 會永久寫 NVM，斷電保留 → 測試流程中絕不執行， 以免覆蓋客戶出廠 config。margin.sh 的 auto-enable（ON_OFF_CONFIG=0x1a）只改 RAM，斷電復原。 v2.7.0 新增的 margin_save all / margin_save blanton 一次寫 18 個 LTC2977， 同一個警告放大 9 倍；另外 0x15 現在送 send-byte，不再帶多餘的 0x00 data byte。
• ⚠️ SWB 的 LTC2977 有兩條路可以到：cb_pmbus_*（CB FPGA F3 Ch6/7/8/9 → pcimem）與 原生 i2c bus（i2cset -f -y 13/14/15/16，Ch+7 = bus）。margin_save blanton 走後者， 其餘功能走前者。同一顆晶片，不要同時用兩條路。
• ⚠️ 改電壓會弄壞 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 都是錯的。
• ⚠️ bcmcmd 就算失敗也 exit 0（VLAN: ERROR: Entry exists / Failed to execute the diagnostic command 都照樣回 0），所以 blanton_traffic_linespeed.sh 是比對輸出而非看 exit code。另外 bcmcmd 一律要 </dev/null —— 否則它會吃掉 while 迴圈的 stdin，只有第一個 VLAN 被設定（V0.3.1 修過的 bug，很難看出來）。
• ⚠️ stress_hhmd.py / stress_pcie.py 已於 2026-08-17 由 KC 移除（Status 表 ScriptB #5/#7）。 Script B 現在是 8 個背景 job（1 mlucas + 5 mem + ssd + usb），不是 10 個。 I2C／PCIe 的持續讀取壓力目前沒有替代品。
• ⚠️ soak 迴圈沒有 pause：取樣間隔不是 Status 表寫的 10 分鐘，而是取決於指令執行時間。 （-u 0 已於 491e807 移除，A/B/C 現在都跑兩個 switch unit。）
• 🔒 .sh / .conf 一定要 LF。CRLF 的 shell script 在 SONiC 上直接掛（$'\r': command not found）； settings/*.conf 更陰險 —— 它們是被 source 的，CB_I2C_CH=6 會變成 "6\r"，安靜地壞掉。 .gitattributes 已擋住 git 這條路徑，但不會回頭重寫既有工作區檔案：早於它 clone 的目錄要 git rm --cached -r . && git reset --hard 才會生效，而且 git status 乾淨不代表磁碟上是 LF （--renormalize 只在進 index 的路上轉換）。驗證要看 byte：grep -rlU $'\r' <dir>
• ⚠️ TTL 的 timeout 是全域的：timeout = N 之後每一個 wait 都被限制在 N 秒。逾時的 wait 直接返回而沒吃到 prompt，下一個指令就在前一個還沒跑完時送出，之後整輪錯開一拍。設了一定要 配一個 timeout = 0 還原（wait_init.ttl 60→0；Script B 的 cdc_ncm 探測 15→0 兩處各還原一次 —— endif 之後走成功路徑、:skip_ping 走跳過路徑；Script 5 同一段直接還原在 if 之前， 一行涵蓋兩條路徑，因為它的 ping 區塊要 wait 一個 sleep 10，DUT 一忙就逼近 15 s 上限）
• ⚠️ goto 的標籤沒定義，Tera Term 是執行到才報錯：Script 5 從 Script B 抄 cdc_ncm 探測時 只帶走 goto skip_ping 沒帶 :skip_ping，平常測不出來 —— 只有真的抓不到 NCM 介面走進那條分支 才會跳錯誤視窗停住整個循環（已補）。抄段落過去時連標籤一起抄
• ⚠️ 兩張管理網卡同網段會 ARP flux：mgmt_ping_monitor.sh 讓 eth0/eth1 同時 up，同一個 /24 下 對端 ARP 可能由任一張卡回應，回包落在沒送封包的那張。ARP_STRICT=1 擋掉；判讀時看 RESULT 行的 nic_tx/nic_rx（該卡自己的 packet delta）—— ping 成功但 nic_tx 接近 0 = 封包從另一張卡出去的
• ⚠️ PRBS 跑起來時 show interfaces status 會顯示 DOWN，那是 link 離開正常運作模式，不是故障。 port_prbs_monitor.sh 的 start 因此刻意不印 port status（避免測試員誤判），只在 prbs clear 之後的報表裡印
• ⚠️ ip -s link 的欄位順序是 bytes packets errors ...，要 packet 數取的是第 2 欄不是第 1 欄
• ⚠️ mgmt_ping_monitor.sh / bmc_monitor*.sh 需要 exec bit，且不是改用 bash x.sh start 就能繞過 —— do_start 內部是 setsid "$SCRIPT_PATH" __daemon，直接執行該路徑。git 記錄是 100644， Windows → 隨身碟 → DUT 也帶不動權限位元，所以佈署後要 chmod +x ~/Blanton_Script/bmc_monitor*.sh。 沒做的話 start 會 Permission denied、後面的 cat 撲空，而且不會報錯，只會得到一份全空的 log
• ⚠️ 這幾支 monitor 的 tail 子命令是 tail -n 50 -f，永遠不返回。TTL 裡絕對不要呼叫它 （Script C 曾因此卡死，18ce7a1 改成直接 cat log/*.log）
• ⚠️ 背景 monitor 的 start 只等 1 秒就返回，不是跑完一輪。Script A 要做一輪基線的話， start 和 stop 中間必須 pause（目前是 45 秒，一輪約 30 秒）—— 少了它 log 只會有 START banner
• ⚠️ 風扇那段設完會 wait "Set all configured fan channels to" 等確認提示再送 y。該提示沒出現 （版本改了、字串換了）就會永遠卡住且不報錯 —— 現場看起來像 Script A 當掉
• ⚠️ show_dmesg.ttl 結尾會 dmesg -C 清空 kernel ring buffer。這是刻意的（讓 Script C 只看到 soak 期間新產生的訊息），但代表事後在 DUT 上 dmesg 撈不到舊訊息 —— 內容只存在 master log 裡
• ⚠️ bcmcmd 的輸出是 CRLF。show c 的計數器後面還跟著 delta，所以「砍掉第一個空白之後」 順便把 CR 砍掉了；但 prbsstat Ber 的 BER 是整行最後一個 token，CR 直接黏在數字上 —— 數字驗證會失敗（全變 NA），而且印出來時 CR 把游標拉回行首，後面的欄位會覆蓋掉前面的欄位。 寫新的 awk 解析器時，第一件事就是 { gsub(/\r/, "") }（blanton_ber.sh V1.0.1 的教訓）
• ⚠️ bcmcmd 的 exit code 兩邊都不能信：BCM shell 拒絕指令時它回 0 （blanton_traffic_linespeed.sh V0.3.1），而 tr 518 這種跑很久的指令會讓它 poll 逾時而回 非 0，但指令其實已經在跑（polling socket timeout: Success）。可靠的作法是找成功的證據 ——例如 tr 518 印出 TR 518 TEST PARAMETERS 才算收下（blanton_tr518.sh V1.0.1）
• ⚠️ 交換晶片不會把封包從進來的那個 port 送回去（source-port knockout）。所以單一 port 的 VLAN 打不出持續流量：tx 100 就是一趟來回然後結束。ce0 靠 ingress mirror 打回自己繞過 這個限制（鏡像複本不經過 egress filter），且不 stop 就不會自己停
• ⚠️ DUT 的 awk 對 %d 會夾到 INT32（2147483647）。線速流量的計數器是 ~10¹² 量級， 所以 awk 裡輸出大數一律用 %.0f（double 域，精確到 2⁵³）。blanton_traffic_linespeed.sh V0.4.1 已修；寫新的 awk 報表時要記得同一件事

資料夾說明

• src/Script_ABC_Blanton/ — 可執行內容（Tera Term 工作目錄；內含要 scp 到 DUT 的 Blanton_Script/）
• docs/ — 客戶 FPGA 規格、AER/EDAC 檢查依據、逐項 Status 表（最新為 *_20260817.xlsx）、 LTC2980_channel_map.csv（9 個 settings/*.conf 合併成 Board,CONN,Ch,NetName,Vnom 144 列， 查 net 對應哪片哪個 channel 用；改 .conf 後要重跑產生）
• tools/ — Host / 離線端：bcm_mibpair_report_V1.1.0.py（drivshell log → per-pair 報表）、 traffic_loopback_*.txt（bcmcmd 原始指令表，blanton_traffic_linespeed.sh 是其 bash 版， 改 loopback 線路時兩邊要同步）、100G_PRBS.txt / TR518.txt / fan_ctrl.txt （上機手貼用的原始指令；PRBS / TR518 / 100G traffic / multiphase normal 都已有對應 .sh）
• publish/ — publish.sh（打包工具，進 git）+ Script_ABC_Blanton_<Ver>/ 產出（gitignored）
• tmp/ — 🚫 gitignored：還沒上機驗證的腳本暫存區（目前 blanton_reboottest.sh）。 上機測過才搬進 src/Script_ABC_Blanton/Blanton_Script/ 並進 git —— 未驗證的東西不該混在 交付包裡，publish 時測試員分不出哪支能信
• src/Script_ABC_Blanton/hammer/ — 🚫 gitignored：mlucas 的 ELF binary（~99 MB，avx512 / avx2 / avx / sse2 / generic-c）。Script B 與 Script 4 會 chmod +x 後執行，但它由 DUT image 帶， 不從這個 repo 發 —— binary 一旦進 git 就永久留在 history，每個 clone 都要付這個代價。 publish.sh 也把它排除，所以打包結果不會因為誰的工作目錄有沒有 binary 而變成 100 MB
• secret/ — 🚫 gitignored（除 README.md 與 *.example）：DUT 帳密、per-unit BDF 覆寫、COM 設定
• For_AI/ — 🚫 gitignored：AI 協作素材（波形截圖、草稿筆記）