# ARCHITECTURE — Blanton TTL Script

## Overview

**Blanton_TTL_Script** 是 Blanton（Project Helios）交換器平台的**系統層可靠性測試自動化腳本組**。
測試工程師在 Windows 端用 **Tera Term (TTL macro)** 透過 COM port 連上 DUT 的 SONiC console，
由 A / B / C 三支腳本依序驅動一整輪 stress + margin + error-counter 測試，全程自動存 log。

三支腳本的分工就是一輪測試的三個階段：

| Script | 階段 | 做什麼 |
|--------|------|--------|
| `1_Blanton_Script_A.ttl` | **Pre-test / Baseline** | 登入、對時、載入 shell 工具、清 PCIe AER、抓 PCIe tree / margin / PMON / dmesg 基線 |
| `2_Blanton_Script_B.ttl` | **Stress / Soak** | 開 CPU / DDR / SSD / USB 壓力程序 + 啟動 SWB loopback 線速流量，之後進無限迴圈每輪抓完整 PMON / margin |
| `3_Blanton_Script_C.ttl` | **Post-test / Verdict** | 殺掉壓力程序、停流量並出 per-pair TX/RX 報表、再抓一次 PMON / dmesg / PCIe AER，比對 stress log 判定 |

DUT 端的實際取數能力則來自一組 **bash 工具庫**（`Blanton_Script/`），這一層才是真正碰硬體的地方：
CB FPGA 的 PCIe BAR（`pcimem`）→ FPGA 內建 I2C / VI2C master → 板上 VRM、溫度感測器、
LTC2980 margin 控制器。TTL 只負責「按順序 `sendln` 並把畫面收進 log」，硬體語意全在 bash 這層。

**使用者**：硬體 / 系統驗證工程師（ETWen、KC、Alan）。
**核心價值**：把一輪要跑數小時、跨 PCIe / DDR / I2C / 電源多個子系統的 reliability run，
壓縮成「開 Tera Term → 跑 A → 跑 B 泡著 → 跑 C 收工」三個動作，且每一筆數據都有 log 可回溯。

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| 測試控制端（Host） | Tera Term 5.x **TTL macro**（`.ttl`），Windows |
| Host ↔ DUT 通道 | RS-232 / USB-Serial COM port（SONiC console） |
| DUT OS | SONiC（Debian-based network OS），bash + busybox/mawk |
| DUT 端工具語言 | Bash Shell Script |
| 暫存器存取後端 | `pcimem`（mmap PCI sysfs `resource0` + BAR 相對 offset） |
| I2C / PMBus 路徑 | CB FPGA F3 OpenCores I2C master、CB FPGA F3 VI2C proxy、CPU 原生 bus（`i2cset`/`i2cget`） |
| 電源 margin | LTC2980（= 2 × LTC2977）over PMBus，LINEAR16 編碼 |
| 錯誤計數來源 | Linux PCIe AER sysfs（`aer_dev_*`）、EDAC sysfs（`dimm_ce/ue_count`） |
| 平台監控 | SONiC `show platform *`（pmon container，含 `leak status` / `leak channels`） |
| BMC 存取 | host 端 `bmc-manager run "<cmd>"`（不需對 BMC 開 SSH，繞開其 busybox 工具鏈）；`bmc-first-enroll` / `bmc-manager version\|status` |
| 背景工作管理 | `bgctl run/list/stop --all/reset`（平台工具）；長時間 ping 用 `systemd-run --unit=` 掛成 transient unit |
| 管理網路 | iproute2（`ip link set` / `ip address replace` / `ip route replace ... metric`）+ `ping -I` |
| 測試 session | `hw-test-session start\|log\|status\|finish`；job log 收在 `/host/hw-eval/jobs/` |
| 風扇控制 | max31790 driver rebind（`/sys/bus/i2c/drivers/max31790/{bind,unbind}`）+ `fan-speed-control.sh <%>` |
| 100G PRBS | `bcmcmd -n <unit> -c 'dsh -c "phy diag <phy> prbs …"'`（set / prbsstat STArt / get / Ber / STOp / clear） |
| 壓力測試 | `mlucas-avx2`（AMD CPU）、`bgctl run` 排程的 `memtester` / `qfx5252-stress-ssd` / `qfx5252-stress-usb` |
| 資料面流量 | `bcmcmd`（Broadcom drivshell）VLAN loopback + `tx` burst，switch unit 0 / 1 |
| 流量報表 | DUT 上 awk（`blanton_traffic_linespeed report`）；離線 `python3 tools/bcm_mibpair_report_V1.1.0.py` |
| 版本控制 | Git（NAS + Gitea 私有 remote；**不推 GitHub，含客戶 NDA 資料**） |

> ⚠️ **無編譯步驟。** TTL 與 bash 都是直譯執行，「build」等同「把 `src/Script_ABC_Blanton/` 複製到
> Tera Term 工作目錄，並把 `Blanton_Script/` scp 到 DUT 的 `~/`」。

---

## Architecture Diagram

```
┌──────────────────────────────────────────────────────────────┐
│  Windows Host — Tera Term 5.x                                │
│                                                              │
│   1_Blanton_Script_A.ttl ──┐                                 │
│   2_Blanton_Script_B.ttl ──┼─→ include "config.ttl"          │
│   3_Blanton_Script_C.ttl ──┘   (prompt / EN_* 旗標)          │
│            │                                                 │
│            └─→ include "utils/*.ttl"  (可重用取數片段)        │
│                                                              │
│   logopen → Logs/Blanton_Margin_<ts>.log  (整段 console 存檔) │
└───────────────────────┬──────────────────────────────────────┘
                        │ COM port：sendln "<cmd>" / wait "<prompt>"
                        ▼
┌──────────────────────────────────────────────────────────────┐
│  DUT — SONiC console (root@sonic:~#)                         │
│                                                              │
│  ~/Blanton_Script/  (source 進 shell 後成為一組函數)          │
│   ├ blanton_fpga_pcimem.sh   cb_fpga / pmc_fpga / swb0_fpga  │
│   ├ blanton_cb_i2c.sh        cb_i2c_* / cb_pmbus_*           │
│   ├ blanton_icb_vi2c.sh      vi2c_* (ICB/PDB proxy)          │
│   ├ blanton_temp_sensor.sh   temp_cb / temp_icb / temp_all   │
│   ├ blanton_pwr_data.sh      pwr_data / pwr_data_pdb         │
│   ├ blanton_traffic_linespeed.sh                             │
│   │        init/clear/show/start/stop/ps/report (bcmcmd)     │
│   └ LTC2980_Margin_Script/   margin_init / margin_status ... │
│                                                              │
│  ~/hammer/tools/     壓力程序（mlucas-avx2, stress_*.py）     │
│  bcmcmd -n 0|1       Broadcom drivshell（VLAN loopback / tx） │
│  SONiC CLI           show platform fan/temperature/leak/...  │
│  Linux sysfs         aer_dev_* / edac mc0/rank*              │
└───────────────────────┬──────────────────────────────────────┘
                        │ pcimem /sys/bus/pci/devices/0000:03:00.<fn>/resource0
                        ▼
┌──────────────────────────────────────────────────────────────┐
│  CB FPGA (PCIe EP，4 個 Function；BDF 於 source 時自動偵測)   │
│   F0  local regs：RST_CAUSE_REG 0xD90 / SWB 0xD94,0xD98      │
│   F3  I2C master  Ch0..Ch17  (base 0x300, stride 0x20)       │
│   F3  VI2C→ICB    Ch0..Ch4   (base 0x780, stride 0x20)       │
│   F2  VSPI 橋接 PMC/ICB/SWB（慢，~18ms/reg，本專案不走）      │
└───────────────────────┬──────────────────────────────────────┘
                        │ I2C / PMBus
                        ▼
   TCA9546/9543 mux · MP29816/MP2985B VRM · TMP75/TMP432 溫感
   MAX31790 風扇 · LTC2980 margin (CONN13~16 × CB/SWB0/SWB1)
   PDB：Hotswap / Power brick / EFUSE（走 VI2C ch3/ch4）
```

---

## Project Structure

```
Blanton_TTL_Script/
│
├── CLAUDE.md                          # 專案記憶 & 給 Claude 的指令
├── ARCHITECTURE.md                    # 本架構文件
├── .gitignore                         # secret/ + For_AI/ + tmp/ + hammer/ + logs + publish 產出
├── .gitattributes                     # 換行符政策：.sh/.conf 釘 LF、.ttl 保持 CRLF
│
├── docs/                              # 規格與狀態文件（客戶提供 / 專案產出）
│   ├── Blantons_FPGA_Registers.md         # FPGA 暫存器規格（markdown 正本，查 offset 用）
│   ├── Blantons_FPGA_Registers_draft.docx # 同上，客戶原始 docx
│   ├── Blantons_FPGA_Registers_Map_draft.xlsx
│   ├── Blantons_PCIe_AER_and_DDR_EDAC_checks.pdf  # AER / EDAC 檢查點依據
│   ├── ADPM12200CMLZxx_DS_Datasheet_*.pdf # PDB brick 手冊（PAGE 與 DIRECT 係數的來源）
│   ├── Blanton_Test_Flow.drawio           # A/B/C + 熱安規四支的測試流程圖（draw.io）
│   ├── LTC2980_channel_map.csv            # 9 個 settings/*.conf 合併：Board,CONN,Ch,NetName,Vnom（144 列）
│   ├── TTL_Script_Blanton_Status_20260814.xlsx
│   └── TTL_Script_Blanton_Status_20260817.xlsx    # ⭐ 最新：三支腳本逐項 Status（OK / On-Going + Owner）
│
├── tools/                             # Host / 離線端輔助腳本
│   ├── bcm_mibpair_report_V1.1.0.py       # 離線解析 drivshell log → per-pair TX/RX + PASS/FAIL
│   ├── traffic_loopback_vlan_setting.txt  # bcmcmd VLAN 30..137 建立 + 成對 pbm（cdN <-> cdN+32）
│   ├── traffic_loopback_start.txt         # bcmcmd tx 100 length=512 VLantag=<vid>
│   ├── traffic_loopback_vlan_remove.txt   # bcmcmd vlan remove <vid> pbm=...
│   │                                      # ↑ 三份為手動貼上用的原始指令表，
│   │                                      #   blanton_traffic_linespeed.sh 是其 bash 版
│   ├── 100G_PRBS.txt                      # 100G PRBS 原始指令（port_prbs_monitor.sh 的來源）
│   ├── TR518.txt                          # 內建封包測試 tr 518 → blanton_tr518.sh
│   ├── BER_Test.txt                       # 全機 PRBS BER 指令 → blanton_ber.sh
│   ├── Multiphase_{high3,low3,comboA,comboB,Save}.txt  # → blanton_multiphase_margin.sh
│   ├── Multiphase_Netname                 # 38 條軌的 net 名稱（區塊順序對應）
│   ├── 100G_Traffic.txt                   # ce0 VLAN 138 打流 → blanton_traffic_linespeed.sh
│   ├── fan_ctrl.txt                       # MAX31790 unbind/bind + fan-speed-control.sh 30
│   └── gen_channel_map.sh                 # settings/*.conf → docs/LTC2980_channel_map.csv（需 gawk）
│
├── secret/                            # 🚫 gitignored — DUT 密碼、per-unit BDF、COM 設定
│   ├── README.md                      # ✅ committed — 用途索引
│   ├── config_secret.ttl.example      # ✅ committed — 帳密範本（__CHANGE_ME__）
│   └── config_secret.ttl              # 🚫 實際帳密，由 config.ttl include
│
├── For_AI/                            # 🚫 gitignored — AI 協作素材（波形截圖、草稿）
│
├── publish/
│   ├── publish.sh                     # ✅ committed — 打包工具（版號讀 Script A 檔頭）
│   └── Script_ABC_Blanton_<Ver>/      # 🚫 產出，gitignored（-z 另出同名 .zip）
│
├── tmp/                               # 🚫 gitignored — 尚未上機驗證的腳本暫存區
│   └── blanton_reboottest.sh              # 5_..._Reboot_Cycle.ttl 的 bash 版，測過再搬進 Blanton_Script/
│
└── src/
    └── Script_ABC_Blanton/            # ← Tera Term 的工作目錄（整包給測試員）
        │
        ├── 4_Blanton_Script_thermal_safety.ttl  # 熱 / 安規：獨立跑，不接 A→B→C
        ├── 5_Blanton_Script_Reboot_Cycle.ttl    # 重開機循環：獨立跑，while 1 無止境（未上機驗證）
        ├── config.ttl                 # 全域設定：testcase 名、EN_Margin / EN_log / EN_timestamp、
        │                              #   風扇與 SWB 宣告、SSD/USB/BMC_USB 壓力秒數、三個 prompt 字串
        ├── hammer/                    # 🚫 gitignored — mlucas ELF binary（~99 MB），DUT image 自帶，
        │                              #   publish.sh 也排除；Script B / Script 4 只負責 chmod +x 後執行
        ├── 1_Blanton_Script_A.ttl     # Pre-test：登入 → 對時 → source 工具 → 清 AER → 抓基線
        ├── 2_Blanton_Script_B.ttl     # Stress：開壓力程序 → while 1 每輪抓 fan/temp/margin
        ├── 3_Blanton_Script_C.ttl     # Post-test：kill → 再抓一次 → 比對 stress log
        │
        ├── utils/                     # 可 include 的取數片段（TTL，無狀態、只 wait+sendln）
        │   ├── pcie_bus.ttl               # lspci -tvvv / -vv
        │   ├── setup_pmon.ttl             # show platform summary/fan/temperature/psustatus/voltage/
        │   │                              #   current/ssdhealth/leak status/leak channels + TPM（11 項）
        │   ├── show_dmesg.ttl             # dmesg -T 合併 error 正則 + i2c 過濾 + dmesg -C 清空
        │   ├── show_margin_status.ttl     # source margin_status_all.sh（掃 9 顆 LTC2980）
        │   ├── kill_all_process.ttl       # kill $(jobs -p)
        │   ├── wait_init.ttl              # 輪詢 show platform temperature 直到 pmon 起來
        │   ├── show_pcie_error_reg.ttl        # 舊的合併版（已被下列 per-device 版取代）
        │   ├── show_pcie_error_reg_TH6_SWB0.ttl   # EP 01:00.0 + RP 00:01.1
        │   ├── show_pcie_error_reg_TH6_SWB1.ttl   # EP 02:00.0 + RP 00:01.2
        │   ├── show_pcie_error_reg_FPGA.ttl       # RP 00:01.5（共用上游）
        │   ├── show_pcie_error_reg_BMC.ttl        # EP 03:00.0 + RP 00:01.4
        │   ├── show_pcie_error_reg_I210.ttl       # EP 07:00.0 + RP 00:02.4
        │   ├── show_pcie_error_reg_SSD.ttl        # EP 06:00.0 + RP 00:02.1
        │   └── show_pcie_error_reg_DDR.ttl        # EDAC mc0 rank0~3 CE/UE
        │
        ├── logs/                      # Tera Term logopen 輸出（*.log gitignored）
        │
        └── Blanton_Script/            # ← scp 到 DUT ~/ 的單位（bash 工具庫）
            ├── blanton_fpga_pcimem.sh     # pcimem 後端：cb_fpga/pmc_fpga/icb_fpga/swb0_fpga/swb1_fpga
            ├── blanton_cb_i2c.sh          # CB FPGA F3 I2C master（Ch0~Ch17）+ PMBus helper
            ├── blanton_icb_vi2c.sh        # CB F3 VI2C proxy → ICB/PDB（Ch0~Ch4）
            ├── blanton_temp_sensor.sh     # TMP75 / TMP432 讀溫（CB Ch10 mux + ICB VI2C Ch2）
            ├── blanton_pwr_data.sh        # SWB VRM + PDB brick 的 Vin/Vout/Iout/Temp 表
            ├── blanton_traffic_linespeed.sh  # SWB loopback 線速流量（bcmcmd unit 0/1）
            │                                 #   init/clear/show/start/stop/ps/report/run
            ├── mgmt_ping_monitor.sh       # 10G/1G 管理網路 ping 監控（iproute2）
            │                              #   eth0→TARGET_10G、eth1→TARGET_1G，兩張卡同時持續 ping
            ├── port_prbs_monitor.sh       # 100G uplink PRBS 測試（bcmcmd phy diag）
            ├── blanton_ber.sh             # 全機 SerDes BER 掃描（phydiag prbs / prbsstat）
            ├── blanton_multiphase_margin.sh # 多相 VRM margin（原生 i2c，38 條軌）
            ├── pwr_brick.sh               # PDB / CPB power brick 讀值（VI2C ch4）
            ├── nfc_polling.sh             # NFC tag 背景輪詢 + PASS/FAIL 統計
            ├── blantons_nfc_validate.py   # NFC/NCI 驗證工具（廠商提供，未修改）
            ├── blanton_tr518.sh           # TR518 封包測試，量功耗前的負載來源
            ├── TH6_SWB0_power_readback.sh # SWB0 19 條軌 V×I + 總功耗
            ├── TH6_SWB1_power_readback.sh # SWB1 同上
            │                              #   ⚠️ 已納入交付，但 A/B/C 的呼叫仍註解掉（bring-up 中）
            ├── usb_target.sh              # 偵測 USB 裝置節點／掛載點（排除系統碟）
            ├── bmc_monitor.sh             # BMC 監控：free -m + I2C 寫入/讀回圖樣測試
            ├── bmc_monitor_ddr.sh         # ⚠️ 已停用：B/C 內呼叫處已註解，DDR 壓力改走 bgctl + bmc-manager
            │                              #   ↑ 三支都要 chmod +x 才能跑（見 Key Constraints）
            └── LTC2980_Margin_Script/     # 電壓 margin 子專案（另有獨立 repo）
                ├── margin.sh              # margin_init/status/set/apply_profile/save
                #                            #   v2.7.0：margin_save all / margin_save blanton
                ├── settings/*.conf        # 一個 .conf = 一顆 LTC2980（CB + SWB0/1 × CONN13~16）
                ├── profiles/*.conf        # 16-ch 批次組合。SWB 為 per-CONN：
                #                            #   combo_SWB_CONN13~16_{high,low}（百分比對應該片的軌）
                #                            #   comboA/comboB_{CB,SWB_CONN13~16}（互補棋盤配對）
                #                            #   通用：high3/5、low3/5、normal、all_off
                ├── script/*_all.sh        # 跨 9 顆 LTC2980 的批次 status / apply / save
                ├── Ref/margin_command_trace.md  # 指令追蹤參考（SWB 章節已標過期，見文件內警告）
                └── logs/                  # margin 操作 log
                #  註：v2.6.0 起不再內含 blanton_cb_i2c.sh / blanton_fpga_pcimem.sh 的複本，
                #      改由 _swb_find_backend 往上層 Blanton_Script/ 找共用版
```

---

## Data Models

本專案沒有資料庫，「資料模型」是**設定檔格式**與**暫存器 / sysfs 語意**。

### 1. `config.ttl` — 全域測試參數（TTL 變數）

```ini
project_name  = "Blanton"       ; 專案名，進 log 檔名
strTestcase   = "ENV"           ; 測項名（ENV/EMC/Margin...），進 log 檔名
EN_Margin     = 0               ; 1=跑 margin 掃描, 0=跳過
EN_log        = 1               ; 1=logopen 存檔, 0=不存
FAN_SPEED     = 100             ; 傳給 fan-speed-control.sh 的風扇轉速 (%)，預設全速
SWB_UNIT0     = 1               ; 這台有 switch unit 0（流量與 wait_init 都依此）
SWB_UNIT1     = 1               ; 這台有 switch unit 1
prompt_login      = "sonic login:"
prompt_sonic      = "admin@sonic:~$"
prompt_sonic_root = "root@sonic:~#"
```

> `SWB_UNIT0` / `SWB_UNIT1` 兩個都是 0 時，`wait_init.ttl` 直接 bypass、A/B/C 的流量段整段跳過。

Log 檔名規則：`<mdir>\Logs\<project_name>_<strTestcase>_<YYYYmmdd-HHMMSS>.log`

### 2. `settings/<board>.conf` — 一顆 LTC2980（16 channel）

| 欄位 | 型別 | 說明 |
|------|------|------|
| `TRANSPORT` | string | `""`/`"i2c"` = CPU 原生 bus（`i2cset`）；`"swb"` = 走 CB FPGA F3 I2C |
| `CB_I2C_CH` | int | `TRANSPORT="swb"` 時的 FPGA I2C 通道（6/7/8/9） |
| `CHIPS[]` | string[2] | `"bus:addr"`，index 0 → CH0~7、index 1 → CH8~15 |
| `CHIP_PRE_CMD[]` / `CHIP_POST_CMD[]` | string[1] | mux 切換等前後置指令，`;` 分隔多筆 |
| `CH<n>_VNOM` | string | 這條軌的**基準電壓**（`"-"` = 未使用 / NC） |
| `CH<n>_NET` | string | 電路 net name（對照 schematic） |

Channel 定址：`ch / 8` → `CHIPS[]` index，`ch % 8` → LTC2977 PMBus PAGE（0x00~0x07）。

**`VNOM` 自 2026-08-30 起是「Blanton 實測中位數」，不是規格標稱值。** 144 條軌裡有 86 條
被改上去 +0.8% ~ +2.5%（例：`PVDD3_3V_SYNTH_LDO_*` 3.3 → 3.38、`P0V9_AVDD_*` 0.9 → 0.915、
`PVDD0_8V_T3` 0.8 → 0.82）。這件事影響兩處，**不是只有顯示**：

- `margin_status` 的偏差 % 是對 `VNOM` 算的 —— 以前一條穩定在 0.756 V 的軌顯示 `+0.80%`，
  現在顯示 `0.00%`。**舊 log 的偏差 % 不能跟新 log 直接比。**
- `margin_set` 的 high / low / OV / UV **全部由 `VNOM` 推算**（`VNOM × (1 ± change%)`），
  所以整個 margin 視窗跟著平移。同樣下 `+3%`，實際打到的絕對電壓比以前高。

**SWB 通道與位址對應（2026-08-19 上機驗證，`ababb2c`）：**

| FPGA I2C 通道 | 板 / 接頭 | LTC2977 位址（lo / hi） |
|---|---|---|
| Ch6 | SWB0 CONN14 / CONN16 | CONN14 `0x5C`,`0x5E` ; CONN16 `0x62`,`0x64` |
| Ch8 | SWB0 CONN13 / CONN15 | CONN13 `0x5C`,`0x5E` ; CONN15 `0x62`,`0x64` |
| Ch7 | SWB1 CONN14 / CONN16 | CONN14 `0x5C`,`0x5E` ; CONN16 `0x62`,`0x64` |
| Ch9 | SWB1 CONN13 / CONN15 | CONN13 `0x5C`,`0x5E` ; CONN15 `0x62`,`0x64` |

> 同一顆 LTC2980 的兩個位址**相差 2**（7-bit，由規格書 8-bit 配對除以 2 而來），不是 1。
> 兩張板共用一條通道，所以同通道上的位址必須互斥 —— 上表兩組（`0x5C/0x5E` 與 `0x62/0x64`）不重疊。

**同一批 LTC2977 也掛在原生 i2c bus 上**（2026-08-27 上機驗證）：Blanton 的 SONiC 把 CB FPGA F3
的這四條 I2C 通道同時註冊成 kernel i2c adapter，因此除了 `cb_pmbus_*` → pcimem 這條路，
還可以用 `i2cset -f -y <bus>` 直接打到同一顆晶片：

| FPGA F3 通道 | Linux bus | CB FPGA 路徑 | 原生 i2c 路徑 |
|---|---|---|---|
| Ch6 | 13 | `cb_pmbus_write 6 <addr> …` | `i2cset -f -y 13 <addr> …` |
| Ch7 | 14 | `cb_pmbus_write 7 <addr> …` | `i2cset -f -y 14 <addr> …` |
| Ch8 | 15 | `cb_pmbus_write 8 <addr> …` | `i2cset -f -y 15 <addr> …` |
| Ch9 | 16 | `cb_pmbus_write 9 <addr> …` | `i2cset -f -y 16 <addr> …` |

`margin.sh` 的 `margin_save blanton` 走原生路徑（`MARGIN_BLANTON_STORE` 表），
其餘功能仍走 `TRANSPORT="swb"` 的 FPGA 路徑。兩條路到的是同一顆 LTC2977，
**不要同時用**（同一條匯流排上兩個 master 語意的存取）。

**全通道 net / 電壓對照：`docs/LTC2980_channel_map.csv`**（9 個 `.conf` × 16ch = 144 列，
欄位 `Board,CONN,Ch,NetName,Vnom`）。查「某個 net 在哪片哪個 channel」比翻 9 個 `.conf` 快。
CSV 是產出物，不是正本 —— 改完 `.conf` 用 `./tools/gen_channel_map.sh` 重產，別手改 CSV。
兩件從表上看得出來、改 `.conf` 時要記得的事：

- **SWB0 與 SWB1 的 net / 電壓完全相同**，差別只在 `CHIPS[]` 的 bus（`0:` vs `1:`）與 `CB_I2C_CH`。
  也就是說有兩份會各自漂移的重複資料 —— 改了 SWB0 沒改 SWB1，不會有任何東西擋你。
- **8 個 NC 通道**（SWB0/1 CONN14 的 CH10/CH11/CH13、CONN15 的 CH10）在 CSV 裡以
  `NC` / `-` 原樣保留，不是漏掉；濾掉它們會讓 page 編號對不上。

### 3. `profiles/*.conf` — 16-ch 批次 margin 組合

```bash
PROFILE_CHANNELS=( "0:high:8" "1:low:8" ... )   # "channel:operation:change_percent"
```

| operation | PMBus `OPERATION`(0x01) | 說明 |
|-----------|------------------------|------|
| `high` | `0xA8` | Margin high |
| `low` | `0x98` | Margin low |
| `nominal` | `0x80` | 回標稱值（跟隨 VOUT_COMMAND） |
| `off` | `0x00` | 關閉輸出 |

### 4. FPGA / I2C 暫存器語意（工具庫依賴）

| 區塊 | 位置 | 關鍵欄位 |
|------|------|----------|
| CB F0 local | `cb_fpga 0 0xD90` | `RST_CAUSE_REG`；`0xD94`/`0xD98` = SWB0/SWB1 |
| CB F3 I2C（每 ch 0x20 stride，base 0x300） | `+00/04` PRSCL, `+08` CTRL(b7 MOD_EN), `+0C` TX/RX, `+10` CMD/STAT, `+14` MUX_SEL, `+18` RST, `+1C` SEM |
| CB F3 VI2C（base 0x780，ICB/PDB） | 同上，但 **`+1C` 無 SEM** |
| I2C CMD | `STA=0x80 STO=0x40 RD=0x20 WR=0x10 NACK=0x08 IACK=0x01` |
| I2C STAT | `RX_ACK=0x80(1=NACK) BUSY=0x40 ARB_LOST=0x20 TIP=0x02 INT=0x01` |
| Prescale @75MHz | `0x88` = 100 kHz、`0x24` = 400 kHz |

### 5. 錯誤計數 sysfs（判定依據）

| 類別 | 路徑 | 判定 |
|------|------|------|
| PCIe AER（EP + 上游 RP 都要看） | `/sys/bus/pci/devices/<BDF>/aer_dev_{correctable,nonfatal,fatal}` | test 前後差值 > 0 即 fail（correctable 需依 spec 設門檻） |
| DDR EDAC | `/sys/devices/system/edac/mc/mc0/rank<0-3>/dimm_{ce,ue}_count` | UE > 0 直接 fail；CE 依門檻 |

**Blanton PCIe 拓樸對照**（`show_pcie_error_reg_*.ttl` 的來源）：

| 裝置 | Endpoint BDF | Upstream Root Port |
|------|--------------|--------------------|
| TH6 SWB0 | `0000:01:00.0` | `0000:00:01.1` |
| TH6 SWB1 | `0000:02:00.0` | `0000:00:01.2` |
| CB FPGA | （F0~F3 @ `0000:03:00.x`） | `0000:00:01.5` |
| BMC | `0000:03:00.0` | `0000:00:01.4` |
| I210 1G NIC | `0000:07:00.0` | `0000:00:02.4` |
| NVMe SSD | `0000:06:00.0` | `0000:00:02.1` |

> ⚠️ **BDF 是 per-unit 的，而且只解決了一半。**
> `blanton_fpga_pcimem.sh`（V1.5.0 起）**已改為 source 時自動偵測**，不再需要每台改檔：
> 掃 sysfs 找 `vendor == 0x1590`（HPE）且 `.0`~`.3` 四個 function 都有 `resource0` 的裝置 →
> 退回 `lspci -Dnn` 名稱比對 → 再退回 `FPGA_BDF_FALLBACK`（`0000:03:00`）。
> 偵測結果會印一行 `[INFO] CB FPGA BDF = ...`，並存在 `FPGA_BDF_ACTIVE`。
> 換 DUT 後可用 `fpga_rescan` 重測，或 `FPGA_BDF=0000:05:00 fpga_rescan` 手動釘住。
>
> **但 `utils/show_pcie_error_reg_*.ttl` 裡的 BDF 仍然是寫死的**（上表那 7 組），
> 自動偵測完全沒有涵蓋到它們。換 DUT 時這些 TTL 還是要人工校對，否則 AER 會讀到錯誤的裝置
> ——甚至讀到不存在的路徑而整段 `No such file or directory`。

---

## Key Features

| 模組 | 進入點 | 功能 |
|------|--------|------|
| **Script A（Pre-test）** | `1_Blanton_Script_A.ttl` V1.1.8 | root 登入 → `date -s` 對時 → 清 job log → **收掉前一輪殘留**（`hw-test-session finish` → `bgctl reset --yes` → `bgctl stop --all` → `bgctl list` 確認清空）→ `hw-test-session start` → **設定風扇轉速** → **等資料面就緒**（`wait_init.ttl`）→ DUT 清單（boot/version/fwutil/syseeprom/ssdhealth/TPM/NVMe）→ BMC enroll + version/status → source bash 工具 → 清/讀 7 組 PCIe AER + `ras-mc-ctl --summary` → `lspci` → margin → PMON → dmesg → **10G/1G 管理網路 ping** → **NFC 基線**（start → 30s → stop → report）→ 100G uplink 設定與狀態 → **一輪流量基線** → `show uptime` |
| **Script B（Stress）** | `2_Blanton_Script_B.ttl` | **V1.1.8 起 `mlucas-avx2 -cpu 0:15` 由 `systemd-run --unit=mlucas-amm`（`Type=exec`、`Restart=always`）啟動，不再是 shell 的 `&` 背景 job** + `bgctl run` 的 `memtester` / SSD / USB 壓力（v1.1.7 起 SSD/USB 的 `--runtime`/`--passes` 讀 `config.ttl` 的 `SSD_RUNTIME`/`SSD_COUNT`、`USB_RUNTIME`/`USB_COUNT`；BMC memtester 不帶次數 = 跑到被停） + BMC DDR（`bmc-manager run memtester`）→ BMC USB net test（探測 cdc_ncm 介面，`systemd-run` 掛 `BMC_USB_RUNTIME` 秒的 ping，V1.1.8 前寫死 4 小時）→ 啟動 mgmt ping 監控 → **啟動 NFC 輪詢** → `jobs` / `systemctl is-active mlucas-amm` / `bgctl list` → traffic（依 `SWB_UNIT`）→ `while 1` 每輪 PMON + `bgctl list`/`jobs`/`systemctl is-active mlucas-amm` + `pause 60`（**V1.1.4 起 margin 不在迴圈內**）|
| **Script C（Post-test）** | `3_Blanton_Script_C.ttl` | `kill $(jobs -p)` + **`systemctl stop mlucas-amm`**（systemd unit 不是 shell job，`jobs -p` 抓不到）+ `bgctl stop --all` / `reset` + 停 BMC USB unit、mgmt ping 與 **NFC 輪詢** → PMON + dmesg → 7 組 AER + `ras-mc-ctl` → BMC USB `journalctl` **寫進 `log/bmc_usb_net.log`**（不再印在 console） → `ip -s link show eth0/eth1` → `cat` mlucas log（並 `cp` 進 job 目錄一起帶走）→ **NFC `report`** → traffic `stop` + `report` → **BER 掃描**（依 `SWB_UNIT`）→ NVMe 健康 → `show reboot-cause` → **margin 掃描**（`EN_Margin`，V1.1.4 由 Script B 移來）→ `uptime` → **job log 複製到 USB（帶時戳）** → `exit` + wait『Script done』→ `hw-test-session finish` |
| **Script 4（Thermal / Safety）** | `4_Blanton_Script_thermal_safety.ttl` | **獨立腳本，不接 A→B→C。** Script A 式的環境建立（登入 / session / 風扇 / `wait_init` / DUT 清單 / BMC / PCIe 清除 / `pcie_bus` / PMON / dmesg）→ **滿載**（`mlucas-avx2 -cpu 0:15`，V1.1.8 起與 Script B 同樣掛成 `mlucas-amm` systemd unit + `blanton_tr518.sh start`）→ `while 1`：PMON + `TH6_SWB0/1_power_readback.sh` + `bgctl list` / `jobs` / `systemctl is-active mlucas-amm`，`pause 60`。**沒有收尾段** —— 中斷後 DUT 仍在 `port cd lb=mac` / `l2 learn off` / `test mode nr=yes`，且 CPU 仍滿載，要手動 `blanton_tr518.sh stop` + `systemctl stop mlucas-amm` |
| **Script 5（Reboot Cycle）** | `5_Blanton_Script_Reboot_Cycle.ttl` | **獨立腳本，不接 A→B→C。** `while 1`：登入 → `sudo -i` → 對時 → 風扇 → **Check Pt1~Pt13**（DUT/BMC info、mgmt ping、NFC、SSD、USB、BMC USB、port status + 15s traffic、BER、NVMe、platform data、dmesg i2c、PCIe error counters）→ `show uptime` → `reboot` → `wait "Booting in blind mode"`。`cnt_cycle` 每輪 +1 印在標頭。**沒有結束條件** —— 要停就關掉 Tera Term 的 macro。**尚未上機驗證** |
| **SWB loopback 流量** | `blanton_traffic_linespeed <sub> [-u 0\|1\|all]` | `init`（VLAN 30..137，成對 `cdN`/`cdN+32`）→ `clear` → `start`（`tx 200 length=324 PatternRandom=yes`，v0.7.0 起）→ `stop` → `report`（per-pair TX/RX 交叉比對 PASS/FAIL）；另有 `ps`（link/speed）與 `run`（一條龍）。**V0.6.0 起含 100G uplink `ce0`**（VLAN 138）：它沒有 loopback 對象，靠 **ingress mirror 打回自己**維持循環，`report` 最後一列就是它，底下再接一份跨 unit summary |
| **FPGA 暫存器存取** | `cb_fpga <fn> <addr> [data]`、`fpga_rescan` | pcimem 打 `resource0` + BAR 相對 offset，32-bit word；BDF 於 source 時自動偵測；`pmc/icb/swb0/swb1_fpga` 走 VSPI 窗口 |
| **CB I2C / PMBus** | `cb_i2c_init/scan/read/write`、`cb_pmbus_read/write/linear16` | FPGA F3 OpenCores master，**讀用 Repeated START**（SMBus/PMBus 裝置必需） |
| **ICB / PDB 存取** | `vi2c_init/scan/read/write`、`vi2c_scan_all` | CB F3 VI2C proxy，~3.3 ms/reg，取代 VSPI 的 ~18 ms/reg（後者會踩 SMBus 25–35 ms timeout） |
| **溫度** | `temp_cb` / `temp_icb` / `temp_all` | TMP75（12-bit 左靠齊 ×0.0625）、TMP432（含 RANGE bit 的 −64 偏移、remote1/2） |
| **電源資料** | `pwr_data` / `pwr_data_pdb` / `pwr_pdb_id` | SWB VRM 全軌 Vin/Vout/Iout/Temp 對齊表；MP29816 解析度**執行期從 `MFR_VOUT_SCALE_LOOP` 讀**，不寫死 |
| **電壓 Margin** | `margin_init/status/set/apply_profile/save` + `*_all.sh` | 9 顆 LTC2980（CB CONN13、SWB0/1 CONN13~16）批次 high/low margin 與狀態掃描。`VNOM` 為 Blanton 實測中位數（2026-08-30）；SWB 的 profile 是 per-CONN，套錯 CONN 會 margin 到錯的軌且不報錯。v2.6.0 起 SWB 路徑真正接上共用 cb_i2c 後端，並有 `margin_swb_info/probe/scan/reset/sem` 除錯包裝 |
| **Multiphase VRM margin** | `blanton_multiphase_margin.sh {high3\|low3\|comboA\|comboB\|save} [-u 0\|1\|all]` | 兩片 SWB 的多相控制器（**不是** `margin.sh` 管的 LTC2980），走原生 i2c bus：SWB0 = `/dev/i2c-13`+`-15`、SWB1 = `-14`+`-16`。每片 19 條軌、共 38 條，逐條印 `SWB0_0V9_ANLG0 - 0.930V Configure Done`。`save` 沒有 per-rail 對應，只印 `Multiphase Save All`。⚠️ `save` 是 `STORE_USER_ALL`（0x15，TH6 core 用 0x17）**永久寫 NVM**；⚠️ 與 `margin.sh` 從兩側摸同一批軌，**不可同時用** |
| **Margin 寫 NVM** | `margin_save` / `margin_save all` / `margin_save blanton` | ⚠️ 永久寫入。`0x15` 送 PMBus **send-byte**（不帶 data byte）。`all` = 依 `settings/` 走 9 顆、跑完還原原本載入的板子；`blanton` = 本平台捷徑，18 顆全走原生 i2c bus（`MARGIN_BLANTON_STORE` 表），不需 `margin_init`。每筆之間 `MARGIN_STORE_SETTLE`（0.5s），工具**不 poll busy bit** |
| **管理網路 ping** | `mgmt_ping_monitor.sh {start\|stop\|status\|fg\|tail\|clear\|summary}` | 一輪 = 10G leg + 1G leg，各自 `ip address/route replace` 後 `ping -I <if>` 打自己的對端；兩張卡都保持 up。每 leg 記 `ip -s link show` 與該卡的 TX/RX packet delta，另出一行可 grep 的 `RESULT` |
| **BMC 監控** | `bmc_monitor.sh {start\|stop\|status\|fg\|tail\|clear}` | 由 host 端 `bmc-manager run` 週期取樣 `free -m`，另加一組 **I2C 寫入/讀回圖樣測試**（bus 1、addr 0x41、offset 0x00C0，寫 `55AA55AA` 讀回、再寫 `AA55AA55` 讀回）。B 啟動、C 停止並 `cat log/bmc_poll.log` |
| **BMC DDR 壓力** | `bmc_monitor_ddr.sh` | ⚠️ **已停用** —— B/C 內呼叫處已註解，改由 `bgctl run bmc-manager run memtester` 取代。檔案保留未刪 |
| **100G PRBS** | `port_prbs_monitor.sh {start [both\|a\|b]\|stop\|status\|report\|clear}` | 兩個 uplink 各一個 worker，可同時或單獨跑。setup（`lpmode off` → `prbs set` → `prbsstat STArt`）→ 週期 `prbs get`（判定）+ `prbsstat Ber`（只記錄）→ teardown（`STOp` + `prbs clear`）。輸出含 `PRBS OK!` 才算 PASS。**⚠️ A/B/C 的呼叫目前註解掉** |
| **SerDes BER 掃描** | `blanton_ber.sh {init\|clear\|start\|stop\|report} [-u 0\|1\|all]` | 全機每個對接 port 的 PRBS BER：`prbs set p=3` + `prbs get`（確認每條 lane 都鎖上）→ `prbsstat STArt Interval=30` →（等一個 interval）→ `prbsstat Ber` → `STOp` → `prbs clear`。`report` 一列一條 lane，**BER < 1e-6 才 PASS**，最後跨 unit 的 summary 帶最差 lane。⚠️ PRBS 期間 link 顯示 DOWN、不過流量 |
| **TR518 負載** | `blanton_tr518.sh {start\|stop} [-u 0\|1\|all]` | `port cd lb=mac` → `l2 learn off` → `test mode nr=yes` → `tr 518 ... testphase=1`，然後 settle `TR_SETTLE_SEC`（120s）再讓人量功耗。`stop` 只送 `port cd lb=none`（照 `TR518.txt`），L2 學習與 test mode **不會還原**，`TR_RESTORE_*=1` 才會 |
| **PDB / CPB brick** | `pwr_brick.sh show [-r]` | 5 顆 brick 的 Vin / Iin / Vout / Iout / Temp（SWB0 `0x62`/`0x63`、SWB1 `0x60`/`0x61`、CPB `0x26`）。四顆 ADPM12200 **每個量各自一個 PMBus PAGE**（Vin 9、Iin 10、Vout 2、Iout 14、Temp 18），讀之前一定要先寫 PAGE —— `blanton_pwr_data.sh` 完全沒寫，所以整張 PDB 表都是 NA。換算用手冊 DIRECT 公式 `X=(1/m)(Y×10⁻ᴿ−b)`。每個值重讀到通過三道檢查為止（非 `0xFFFF`、非 `0x0000`、落在合理範圍）—— 這條匯流排**只壞高位元組**，`11.98 V` 會變成 `32.00 V`，全一過濾擋不住 |
| **SWB 軌功耗** | `TH6_SWB{0,1}_power_readback.sh` | 讀 `show platform voltage/current` **各一次**，19 條軌 V×I 與總功耗。舊版每軌各讀一次（38 次呼叫、每軌不同時刻），總和是不同瞬間的加總 |
| **NFC 讀取輪詢** | `nfc_polling.sh {start\|stop\|status\|tail\|report\|clear\|fg}` | 背景重複跑 `blantons_nfc_validate.py`，每輪追加一行機器可讀的 `RESULT=`（PASS/FAIL 取自工具自己的摘要行，兩者皆無則 **ERROR**，與 FAIL 分開計數）。`start` 會先清空 log；`report` **只讀 log，polling 中隨時可跑**，並標示 `RUNNING` 免得快照被當最終結果。`tail` **不 follow** |
| **USB 目標偵測** | `usb_target.sh [-o dev\|mnt\|both\|id] [-n] [-r sec]` | 找出插入的 USB 儲存裝置，排除 `/` 與 `/host` 的底層碟（本平台可能從 USB DOM 開機），多顆時拒絕猜；掛載時會驗證真的可寫 |
| **打包交付** | `publish/publish.sh [-v Ver] [-f] [-z] [-n]` | 版號讀 Script A 檔頭，複製成 `publish/Script_ABC_Blanton_<Ver>/`，排除 `*.log`，可另出 zip |

---

## Data Flow

### 一輪完整測試（端到端）

```
[測試員] 開 Tera Term，連 COM<n>，Control → Macro → 1_Blanton_Script_A.ttl
    │
    ▼
Script A ── logopen Logs/Blanton_Margin_<ts>.log ──┐  (之後所有畫面都進這個檔)
    │                                              │
    ├─ 登入 admin → sudo -i → root@sonic:~#         │
    ├─ date -s "<host 時間>"   ← 讓 DUT 時戳可對照
    ├─ rm /host/hw-eval/jobs/*   ← 清掉上一輪的 job log
    ├─ hw-test-session finish / bgctl reset / stop --all / list   (收前一輪)
    ├─ hw-test-session start / log / status
    ├─ 風扇：max31790 unbind→sleep→bind（18-0020 與 25-0020 各一次）
    │        → fan-speed-control.sh <FAN_SPEED> → 回答 y 確認   │
    ├─ source 6 個 bash 工具（函數進 shell）         │
    │    └ 此時 blanton_fpga_pcimem.sh 印出 [INFO] CB FPGA BDF = ...（自動偵測結果）
    ├─ AER 基線：7 組 EP+RP 的 correctable/nonfatal/fatal
    ├─ lspci -tvvv / -vv       ← 拓樸 + link speed/width
    ├─ margin_status_all       ← 9 顆 LTC2980 × 16ch 的 Vout 與偏差%
    ├─ show platform × 9       ← fan/temp/psu/voltage/current/ssdhealth/leak status/leak channels
    ├─ dmesg -T（合併 error 正則 + i2c 過濾）→ dmesg -C 清空 ← C 只會看到 soak 期間新產生的
    ├─ mgmt ping：start → pause 45 → stop → cat log      ← 10G/1G 各一輪
    ├─ 100G uplink：lpmode off → 兩埠 startup → config save → show interfaces status
    ├─ 一輪流量基線：ps → init → clear → show → start → stop → report
    └─ show uptime
  （最前面還有 wait_init.ttl：輪詢 show platform temperature 直到不再回報
    "Thermal Not detected"，避免 pmon 還沒起來就抓基線）
    ▼
[messagebox "Start Script B"] ← 人工確認後手動跑 B
    │
    ▼
Script B ── 同一個 log 檔續寫（logwrite 分隔線）
    ├─ 背景程序：mlucas-avx2(CPU) ×1, stress_mem ×5, stress_ssd, stress_usb  → 共 8 個 job
    │     （stress_hhmd / stress_pcie 已於 2026-08-17 移除，見 Status 表 ScriptB #5/#7 "KC Remove"）
    ├─ bgctl run: memtester 1G / qfx5252-stress-ssd / qfx5252-stress-usb
    ├─ BMC: bmc-manager run memtester（DDR）、cdc_ncm 介面探測 + systemd-run 4hr ping（USB）
    ├─ mgmt_ping_monitor.sh start
    ├─ jobs / bgctl list        ← 確認全部起來了
    ├─ traffic: ps → init → clear → (pause 15) → show → start  （unit 0 與 1，VLAN 30..137 loopback）
    └─ while 1: setup_pmon（9 項）→ margin_status_all          （soak 期間持續取樣）
    ▼
[測試員 Ctrl-C / 停止 macro，接著跑 C]
    │
    ▼
Script C
    ├─ kill $(jobs -p)          ← 收掉所有背景壓力
    ├─ show platform × 9 + dmesg  ← 收工快照
    ├─ AER 再抓一次              ← 與 Script A 基線相減 = 本輪新增錯誤
    ├─ bgctl stop --all / reset、systemctl stop BMC USB unit、mgmt ping stop
    ├─ journalctl BMC USB unit、ip -s link show eth0/eth1、ras-mc-ctl --summary
    ├─ cat mlucas_amm_log       ← CPU 壓力程式自身的 pass/fail
    ├─ nvme smart-log / smartctl -x /dev/nvme0
    ├─ traffic: stop → report   ← per-pair TX/RX 交叉比對，PASS/FAIL/NA（exit 2 = 有 FAIL/NA）
    ├─ show reboot-cause / show uptime  ← soak 期間有沒有意外重開，一眼看得到
    ├─ usb_target.sh -o dev → sync → mount <dev> /mnt/usb
    ├─ cp bmc_poll.log / mgmt_ping.log → jobs/，再 cp -r jobs/ /mnt/usb/jobs-<YYYYmmdd>_<HHMM>
    └─ hw-test-session finish
    ▼
[messagebox "GOOD JOB! Test Case DONE"] → 人工檢查 log
```

### 硬體讀值路徑（以「讀一顆 SWB VRM 的 Vout」為例）

```
pwr_data
  └→ cb_pmbus_read <ch> <slave7> 0x8B 2        (blanton_cb_i2c.sh)
       └→ _cbi2c_xfer_read：STA+WR(slave|W) → WR(reg) → Sr + STA+WR(slave|R)
                            → RD(ACK) → RD(NACK)+STO             ← Repeated START
            └→ cb_fpga 3 <0x300 + ch*0x20 + reg>                  (blanton_fpga_pcimem.sh)
                 └→ pcimem /sys/bus/pci/devices/0000:03:00.3/resource0 <off> w [data]
                      └→ CB FPGA BAR0 → F3 I2C master → SCL/SDA → MP29816/MP2985B
  └→ 解碼：MP2985B = 1 mV/LSB；MP29816 = 由 MFR_VOUT_SCALE_LOOP(0x29) bit[12:10] 決定
           Vin 一律 31.25 mV/LSB（÷32）
```

---

## Key Constraints & Business Rules

1. **A → B → C 必須依序跑，且 B 之後才能跑 C。** Script B 的背景 job 只存在於那個 shell session，
   Script C 的 `kill $(jobs -p)` 依賴同一個 session；中途斷線就得手動收程序。
   V1.1.8 起 `mlucas-amm` 例外 —— 它是 systemd transient unit，**跨 session 存活**，
   所以 Script C 必須另外 `systemctl stop mlucas-amm`（見第 17 條）。
2. **A / B / C 共用同一個 log 檔**：只有 Script A `logopen`，B / C 用 `logwrite` 續寫分隔線。
   跑 B/C 前若關掉了 Tera Term，log 就斷了。
3. **PCIe AER 的判定是「差值」不是「絕對值」**：Script A 抓基線、Script C 抓結果，
   兩者相減才是本輪產生的錯誤。EP 與上游 Root Port **兩邊都要看**（錯誤可能只記在 RP）。
4. **BDF 是 per-unit 的，bash 端已自動偵測、TTL 端仍寫死**：`blanton_fpga_pcimem.sh` V1.5.0 起
   於 source 時自掃（vendor `0x1590` → `lspci` → fallback），但 `utils/show_pcie_error_reg_*.ttl`
   的 7 組 BDF 還是硬編碼，換 DUT 仍需人工校對（見 Data Models §5 註）。
5. **ICB / PDB 一律走 VI2C，不走 VSPI**：VSPI ~18 ms/reg 會讓 I2C byte 相之間拉到 ~50 ms，
   踩中 SMBus 25–35 ms timeout，裝置會 NACK register pointer。實測全 5 通道掃描 9.4 s vs 34.0 s。
6. **I2C 讀一律用 Repeated START**（不是 STOP + START）：PMBus / SMBus 裝置（VRM、EFUSE）
   只吃 Sr；只有純暫存器裝置兩種都行。
7. **`margin_save`（`STORE_USER_ALL`）會永久寫進 NVM**，斷電保留。測試流程中**絕不執行**，
   以免覆蓋客戶出廠 config。`margin.sh` 的 auto-enable 只改 RAM（`ON_OFF_CONFIG`），斷電復原。
   `margin_save all` / `margin_save blanton`（v2.7.0）一次對 9 顆 LTC2980（18 個 LTC2977）
   下同一道命令，風險同性質但範圍是全機；命令本身是 PMBus send-byte（`0x15`，不帶 data byte）。
8. **操作硬體電壓有損壞 DUT 的風險**：套 profile 前先確認該軌 OV/UV limit 與 servo DAC 注入電阻
   有 populate（本板部分 margin 電阻標 PROTO，沒 populate 的軌電壓不會動）。
9. **`ARB_LOST` 不等於裝置存在**：`vi2c_scan` 只看 `RX_ACK`，仲裁失敗會被誤報成「有裝置」。
   `blanton_pwr_data.sh` 因此加了 ARB_LOST-aware retry 與 plausibility window
   （`0xFFFF` 或超出範圍一律回 `NA`）——**寧可 NA 也不要印出一個看起來像數據的錯值**。
10. **`bcmcmd` 成功退出不代表指令成功**：BCM shell 拒絕指令（`VLAN: ERROR: Entry exists` /
    `Failed to execute the diagnostic command`）時 `bcmcmd` 仍 exit 0。
    `blanton_traffic_linespeed.sh` 因此改用輸出比對（`$TL_ERR_PAT`），並把
    `vlan create` 的 `Entry exists`（重跑 init）與 `vlan remove` 的 `not found`（init 前先 stop）
    當良性情況分開計數。另外 `bcmcmd` 一律以 `</dev/null` 執行 ——
    否則它會吃掉 while 迴圈的 stdin，導致**只有第一個 VLAN 被設定**（V0.3.1 修的 bug）。
11. **DUT 密碼不得進 git**：`1_Blanton_Script_A.ttl` 目前的 `sendln "YourPaSsWoRd"` 是 placeholder，
    實際帳密必須放 `secret/config_secret.ttl`（gitignored）並由 `config.ttl` include。
12. **`.sh` / `.conf` 必須是 LF**：CRLF 的 shell script 在 SONiC 上直接掛
    （`-bash: $'\r': command not found` + `syntax error near unexpected token`），
    `settings/*.conf` 則因為是被 `source` 的，未加引號的賦值會變成 `"6\r"`（安靜地壞掉）。
    `.gitattributes` 已把 `*.sh` `*.conf` `*.py` `*.txt` `*.md` 釘成 LF、`*.ttl` 維持 CRLF。
    ⚠️ 但 `.gitattributes` **不會回頭重寫既有工作區檔案** —— 早於它 clone 出來的目錄，
    需 `git rm --cached -r . && git reset --hard` 或刪掉目錄重新 checkout 才會生效，
    而且 `git status` 乾淨**不代表**磁碟上是 LF（`--renormalize` 只在進 index 的路上轉換）。
13. **`bmc_monitor*.sh` / `mgmt_ping_monitor.sh` 需要執行權**：它們是本專案「被執行」而非被 `source` 的腳本，
    而 `do_start` 內部是 `setsid "$SCRIPT_PATH" __daemon`，**即使用 `bash x.sh start` 呼叫
    也仍需 exec bit**。git 記錄為 `100644`，且 Windows → 隨身碟 → DUT 的路徑無法攜帶權限位元，
    所以佈署後要先 `chmod +x ~/Blanton_Script/bmc_monitor*.sh`，否則 Script B 的 start 會
    `Permission denied`、Script C 的 `cat` 撲空（BMC 段全空但不會報錯）。
14. **TTL 的 `timeout` 是全域的，設了就要還原**：`timeout = N` 之後**每一個** `wait` 都被限制在 N 秒，
    逾時的 `wait` 會直接返回而沒吃到 prompt，於是下一個指令在前一個還沒跑完就送出，之後整輪錯開一拍。
    `wait_init.ttl` 設 60 後還原 0；Script B 的 cdc_ncm 探測設 15，成功路徑在 `endif` 之後還原、
    跳過路徑在 `:skip_ping` 還原（兩處各一次）。
    Script 5 抄了同一段，但它的 ping 區塊要 `wait` 一個 `sleep 10` —— DUT 一忙就逼近 15 s 上限，
    所以**還原點提前到 `if` 之前**：分支之前還原，一行就涵蓋兩條路徑，`:skip_ping` 的那行留作備援。
    加新的 `timeout` 時務必配一個 `timeout = 0`；**抄有 `goto` 的段落時連 `:label` 一起抄** ——
    標籤沒定義 Tera Term 不會在載入時報錯，要真的跳進那條分支才會彈錯誤視窗停住整輪
    （Script 5 原本就漏了 `:skip_ping`，只有抓不到 NCM 介面時才會發作，已補）。
15. **兩張管理網卡同網段時會 ARP flux**：`mgmt_ping_monitor.sh` 讓 eth0/eth1 同時 up，若兩者在同一個
    /24（本專案預設 `192.168.1.99` / `.101`），對端 ARP 可能由任一張卡回應，回包落在沒送封包的那張，
    量到的數字不能歸屬。`ARP_STRICT=1` 會設 `arp_ignore=1` / `arp_announce=2` 擋掉；
    另外每個 leg 的 `RESULT` 行帶 `nic_tx` / `nic_rx`（該卡自己的 packet delta），
    **ping 成功但 `nic_tx` 接近 0 就代表封包從另一張卡出去了**。兩張卡在不同網段時可設 0。
16. **客戶 NDA**：`docs/` 內含客戶 FPGA 規格與 schematic 衍生資訊，**本 repo 只推 NAS + Gitea，
    絕不推 GitHub**。
17. **改用 `systemd-run` 起壓力工作，就要自己補停的那一行。** `utils/kill_all_process.ttl` 的內容
    只有 `kill $(jobs -p)`，而 systemd unit 不是 shell job，它抓不到。V1.1.8 把 `mlucas-avx2`
    搬到 `mlucas-amm` unit（好處：掉線不會停、`jobs` 看不見的問題消失、`Restart=always` 會自動拉回），
    代價是 Script C 少了那行 `systemctl stop` 就會讓 CPU 滿載燒進收工量測與下一輪測試 ——
    而 `show interfaces status` 之類的檢查完全看不出來。目前 `mlucas-amm` 與
    `qfx5252-bmc-usb-net-test` 兩個 unit 都已在 Script C 收掉。
    ⚠️ **`4_Blanton_Script_thermal_safety.ttl` 用同一個 `mlucas-amm` unit，但它沒有收尾段**，
    所以那行 `systemctl stop mlucas-amm` 必須由測試員手動下 —— 這是 Script 4 目前
    唯一一個「不下就會延續到下一輪」的負載。
18. **`config.ttl` 少一個變數會讓 macro 當場中止**，不是當成 0。V1.1.8 新增 `EN_timestamp`
    （Script A `logopen` 的第 5 個參數）與 `BMC_USB_RUNTIME`（Script B 的 ping unit）。
    只更新 `.ttl` 卻沿用舊的 `config.ttl`，Script A 會停在 `logopen` 那一行。
    另外 **時間戳的「格式」不在 macro 裡** —— 它在 Tera Term 的
    Setup → Additional settings → Log，存在那台電腦的 `TERATERM.INI`，會跟著 PC 而不是跟著腳本走。

---

## Security Considerations

| 項目 | 做法 |
|------|------|
| **DUT console 帳密** | 集中在 `secret/config_secret.ttl`（gitignored），`config.ttl` 以 `include` 載入。repo 內只留 `secret/config_secret.ttl.example`，敏感欄位一律 `__CHANGE_ME__` |
| **`secret/` 資料夾** | 本機 / 現場敏感資料集中地：DUT 帳密、per-unit BDF 覆寫、COM port 設定、客戶提供的未公開附件。`.gitignore` 用 `secret/*` + `!secret/README.md` + `!secret/*.example` + `!secret/.gitkeep`，**除 README 與 `.example` 外全部忽略** |
| **客戶機密文件** | `docs/` 內 FPGA 規格（docx/xlsx/md）屬客戶 NDA 範圍；schematic 原始檔（`*.DSN`）一律 gitignore，不進 repo |
| **Remote 限制** | 只推私有 remote：`nas`（`git.et-wen.com:51222`）+ `gitea`（`etgit.et-wen.com`）。**不設 GitHub `origin`** |
| **測試 log** | `logs/*.log` 含 DUT 序號、MAC、韌體版本等可識別資訊 → gitignore，只保留目錄結構（`.gitkeep`） |
| **破壞性硬體指令** | `margin_save` / `margin_save all` / `margin_save blanton` / `STORE_USER_ALL` 為永久 NVM 寫入，工具預設不呼叫；`margin_save all` 與批次腳本 `margin_save_all.sh` 在 README 與程式頂端都有警語 |
| **root 權限** | 全流程在 `root@sonic:~#` 下執行（pcimem / i2c 需要）；腳本不留任何 `chmod 777` 或放寬權限的動作 |
| **For_AI/** | AI 協作素材（截圖、草稿筆記）整個資料夾 gitignore，避免不小心把客戶圖面帶進 repo |

---

## Build & Setup Steps

無編譯。從零到能跑一輪測試：

```bash
# ── 0. 取得專案（開發機 / 測試 NB）────────────────────────────
git clone ssh://ETHouseNAS@git.et-wen.com:51222/volume1/git/Blanton_TTL_Script.git
cd Blanton_TTL_Script

# ── 1. 準備帳密（不進 git）──────────────────────────────────
cp secret/config_secret.ttl.example secret/config_secret.ttl
#   編輯 secret/config_secret.ttl，填入實際 DUT 帳密（取代 __CHANGE_ME__）

# ── 2. DUT 端：部署 bash 工具庫 ─────────────────────────────
scp -r src/Script_ABC_Blanton/Blanton_Script admin@<DUT_IP>:~/
#   佈署後務必補執行權（Windows/隨身碟路徑帶不動 exec bit）：
ssh admin@<DUT_IP> 'chmod +x ~/Blanton_Script/bmc_monitor*.sh'
#   若曾在舊工作區編輯過，先確認沒有 CRLF：grep -rlU $'\r' ~/Blanton_Script
ssh admin@<DUT_IP> 'sudo -i'
#   （現場無網路時改用 USB 隨身碟複製到 ~/Blanton_Script）

# ── 3. DUT 端：煙霧測試（跑 Script A 之前先手動確認）──────────
source ~/Blanton_Script/blanton_fpga_pcimem.sh
#   → 會印 [INFO] CB FPGA BDF = 0000:0X:00.0-.3 (resource0)   ← BDF 自動偵測，不用改檔
#   偵測錯或多顆候選時：FPGA_BDF=0000:05:00 fpga_rescan
cb_fpga 0 0xD90                     # RST_CAUSE_REG，讀得到值 = BAR 通了
source ~/Blanton_Script/blanton_cb_i2c.sh
cb_i2c_init 11 && cb_i2c_scan 11    # Ch11 風扇控制器，應看到 0x20
source ~/Blanton_Script/LTC2980_Margin_Script/margin.sh
margin_init Blanton_CB_CONN13 && margin_status
source ~/Blanton_Script/blanton_traffic_linespeed.sh
blanton_traffic_linespeed ps -u 0            # 對照線的 link/speed
blanton_traffic_linespeed init -u 0 -n       # -n = dry-run，先看要下哪些 bcmcmd

# ── 4. DUT 端：校對 AER 的 BDF（自動偵測沒涵蓋這裡！）─────────
lspci -Dnn                          # 對照 ARCHITECTURE.md 的 PCIe 拓樸表
#   與 src/Script_ABC_Blanton/utils/show_pcie_error_reg_*.ttl 內寫死的 7 組 BDF 比對，
#   不符就改 TTL——否則 AER 會讀到別的裝置或不存在的路徑
```

**Host（Windows）端：**

```
1. 安裝 Tera Term 5.x
2. 把 src\Script_ABC_Blanton\ 整包複製到本機（路徑不要有空白與非 ASCII）
3. 在該資料夾下建立 Logs\ 目錄（Script A 的 logopen 需要）
4. Tera Term 連上 DUT COM port（預設 115200-8-N-1）
5. Control → Macro → 選 1_Blanton_Script_A.ttl
6. A 跑完出現 messagebox → 手動跑 2_Blanton_Script_B.ttl（soak）
7. Soak 時間到 → 停止 B 的 macro → 跑 3_Blanton_Script_C.ttl
8. 檢查 Logs\Blanton_Margin_<ts>.log
```

**打包交付：**

```bash
./publish/publish.sh          # 版號讀 Script A 檔頭 → publish/Script_ABC_Blanton_V1.0.3/
./publish/publish.sh -z       # 另外產出同名 .zip
./publish/publish.sh -n       # dry run，只印會做什麼
./publish/publish.sh -f       # 覆蓋既有輸出資料夾
```

版號**不是參數而是從 Script A 的 `; Version : Vx.y.z` 讀出來的**，所以資料夾名不可能跟
測試員打開 macro 看到的版本不一致。要出新版就先改 Script A 檔頭再跑。
輸出會排除 `*.log`（測試 log 含 DUT 序號，不隨交付外流），但保留空的 `logs/` 供 `logopen` 寫入。

> 註：本專案非 .NET / Blazor / EC2 架構，`aws-ec2-deploy` 與 `vbox-run-deploy` 兩份部署指南不適用，已跳過。

---

## Development Phases

現況基準：`docs/TTL_Script_Blanton_Status_20260814.xlsx` 已逐項標記 OK / On-Going，
以下 Phase 直接把該表的 On-Going 項目排進來，並補上工程化（版控、密碼外移、打包）的缺口。

### Phase 1 — 版控化 + 密碼外移（工作量：S）

**目標：** 專案進 git（NAS + Gitea），帳密不再躺在腳本裡，任何人 clone 下來照文件就能跑。

**包含：**
- [x] `git init` + `.gitignore`（`secret/*`、`For_AI/`、`logs/*.log`、`~$*`、`*.DSN`）
- [x] 建 `secret/README.md` + `secret/config_secret.ttl.example`（`__CHANGE_ME__` placeholder）
- [ ] `config.ttl` 改為 `include "..\..\secret\config_secret.ttl"`（或現場放同層），
      把 `1_Blanton_Script_A.ttl` 的 `sendln "YourPaSsWoRd"` 換成 `sendln dut_password`
      **← 唯一未完成項；密碼目前仍寫在腳本裡**
- [x] `src/Script_ABC_Blanton/logs/.gitkeep`，既有 `Blanton_Margin_20260814-164122.log` 移出 repo
- [x] `CLAUDE.md` + `ARCHITECTURE.md` 進 repo，push `nas` + `gitea`（**不推 GitHub**）

**驗收條件：** 在另一台機器 `git clone` → 填 `secret/config_secret.ttl` → Script A 能完整登入並產生 log；
`git log -p` 中搜不到任何實際密碼。

---

### Phase 2 — Script A 補完：Check History + Margin 驗收（工作量：M）

**目標：** Script A 的基線資料補齊到「開機原因 + 全部電壓軌」都有紀錄，Status 表的兩個 On-Going 轉 OK。

**包含：**
- [ ] 新增 `utils/show_reset_cause.ttl`：`cb_fpga 0 0xD90`（RST_CAUSE_REG）、
      `cb_fpga 0 0xD94`（SWB0）、`cb_fpga 0 0xD98`（SWB1），並在註解貼上 bit 定義
      （來源 `docs/Blantons_FPGA_Registers.md` §5 RST_CAUSE_REG）
- [ ] Script A 的 `; ========== Check History ==========` 區塊改 include 上面這支
- [ ] `utils/show_margin_status.ttl`：清掉已註解的 per-conf 舊寫法，只留
      `margin_status_all.sh`；確認 9 顆 LTC2980 都能掃到（含 SWB 的 `TRANSPORT="swb"` 路徑）
- [ ] 新增 `utils/show_pwr_data.ttl`（`pwr_data` + `pwr_data_pdb`）與
      `utils/show_temp_sensor.ttl`（`temp_all`），把 `blanton_pwr_data.sh` /
      `blanton_temp_sensor.sh` 真正接進流程（目前 Script A 只 source 沒用）
- [x] Script A 開頭加 BDF 自檢 —— 由 `blanton_fpga_pcimem.sh` V1.5.0 的 source 時自動偵測達成，
      log 內會出現 `[INFO] CB FPGA BDF = ...`（比原本規劃的 `lspci` 一行更完整）

**驗收條件：** 跑一次 Script A，log 內同時含 reset cause 三個暫存器值、9 顆 LTC2980 × 16ch 的
margin status、全部 VRM 軌的 Vin/Vout/Iout/Temp、CB + ICB 溫感讀值，且無 `ERR` / `NA` 以外的異常。

---

### Phase 3 — Script B 壓力層穩固化（工作量：M）

**目標：** 壓力程序起得來、起不來看得出來，soak 迴圈有時戳、可控週期。

**包含：**
- [ ] 前置檢查：`~/hammer/tools/amd/mlucas-avx2` 仍是唯一還依賴 hammer 的項目，缺檔就別往下跑
- [ ] 壓力程序 log 加時戳，避免多輪覆蓋：
      `mlucas_amm_log` → `~/logs/mlucas_amm_log_$(date +%Y%m%d-%H%M%S).log`（Status 表 ScriptB #2 的既定寫法）
- [x] 壓力層改用平台的 `bgctl`（`memtester` / `qfx5252-stress-ssd` / `qfx5252-stress-usb`），
      取代 `~/hammer/tools/stress_*.py`；Script B 以 `jobs` + `bgctl list` 兩者並列確認
- [ ] `bgctl list` 之後加數量驗證，不符時 `messagebox` 提示（目前只印出來給人看）
      **← V1.0.10 起 `bgctl list` + `jobs` 改為每輪都印，中途死掉的 job 看得到，但仍要靠人眼比對**
- [ ] soak 迴圈改為「每輪先 `date`、跑完 `pause <間隔>`」，
      把 `EN_LoopInterval`（預設 600 秒 = 10 min）放進 `config.ttl`，兌現 Status 表的「Get data every 10mins」
      **← V1.0.10 已補上 `pause 60`（迴圈不再全速空轉），但 60 秒是寫死的、也還沒有每輪 `date`；
      距 Status 表的 10 分鐘仍有差距，故本項未結**
- [x] soak 每輪補 `show platform psustatus` / `voltage` / `current`
      —— 迴圈已改為 `include "utils/setup_pmon.ttl"`，九項全收
- [ ] 補 `; ========== CLEAR EVENT ==========`（Status 表 ScriptB #1，Owner: Alan）
- [x] BMC 納入 soak：`bmc_monitor.sh`（`free -m` 取樣）與 `bmc_monitor_ddr.sh`（`memtester`）
      由 Script B 啟動、Script C 停止並把 log 併進 master log
- [x] Script A 加開機資訊與就緒等待：`show boot`、BMC `/etc/issue`、`wait_init.ttl`
- [x] Script C 加 `show reboot-cause` / `show uptime`，soak 期間意外重開看得見

**驗收條件：** Script B 啟動後 `jobs` 顯示 8 個 job；連續跑 3 輪，log 內三段各自帶正確時戳且間隔 ≈10 min；
故意把 `~/hammer` 改名，Script B 會在前置檢查就停下並提示。

---

### Phase 4 — Traffic 與 SONiC 介面資料（工作量：M）

**目標：** 補齊 Status 表中 Owner=Alan 的三個 traffic 項目，讓測試涵蓋交換晶片的資料面。

> 📌 **實作路線與原規劃不同**：原本設想用 SONiC CLI（`sonic-clear counters` / `show interface counters`），
> 實際落地的是**更底層的 `bcmcmd` drivshell 路線** —— SWB 實體 loopback 線 + VLAN 成對配置 + `tx` burst，
> 直接讀 ASIC 的 `MIB_TPOK`/`MIB_RPOK`。好處是能做 per-pair 雙向交叉比對（`cdA.TX == cdB.RX`），
> 比 SONiC CLI 的單向 counter 強得多；代價是綁定 Broadcom SDK 與那條 loopback 線。

**包含：**
- [x] `blanton_traffic_linespeed.sh`（V0.4.0）：`init` / `clear` / `show` / `start` / `stop` /
      `ps` / `report` / `run`，unit 0 與 1，VLAN 30..137 對應 `cdN` ↔ `cdN+32`
      （取代原規劃的 `utils/traffic_setup.ttl`）
- [x] per-pair TX/RX 報表與 PASS/FAIL 判定：DUT 上 awk（`report`）+ 離線
      `tools/bcm_mibpair_report_V1.1.0.py`，同版面同判定規則
      （取代原規劃的 `utils/show_traffic_counters.ttl`）
- [x] Script B 接上 `ps → init → clear → show → start`、Script C 接上 `stop → report`
- [x] 原始 bcmcmd 指令表留檔：`tools/traffic_loopback_{vlan_setting,start,vlan_remove}.txt`
- [x] **Script A 的流量基線** —— 原本的空區塊已改成完整一輪
      （`ps → init → clear → show → start → stop → report`，含 15 秒沉澱）
- [ ] `utils/show_interface_detail.ttl`：`show interface transceiver eeprom/dom`、
      `show interface link-training`（Status 表 ScriptC #4，仍 On-Going）
- [ ] `utils/show_tech.ttl`：`show techsupport`（Script C 收工快照，Status 表 ScriptC #4）
- [ ] `config.ttl` 加 `EN_Traffic` 旗標，未接 loopback 線的站點可整段跳過
      （現在 B/C 是無條件執行，沒接線會整批 bcmcmd 失敗）
- [x] `-u 0` 已從三支腳本移除，全部沿用工具預設 `TL_UNITS="0 1"`，兩塊 switch board 都測到
- [x] 100G uplink 狀態：`show interfaces status Ethernet513,Ethernet514`（A 與 B 各一次）

**驗收條件：** `EN_Traffic=1` 時，Script C 的 `report` 印出 108 對的 TX/RX 表且全 PASS；
拔掉一條 loopback 線重跑，該對顯示 FAIL 或 NA 且 exit code 為 2；`EN_Traffic=0` 時整段不執行且不報錯。

---

### Phase 5 — Log 解析與自動判定（工作量：L）

**目標：** 不用人眼掃幾 MB 的 console log，跑完自動吐一張 PASS/FAIL 摘要。

**包含：**
- [ ] `tools/parse_blanton_log.py`：吃 `Logs/*.log`，切出 ScriptA / ScriptB / ScriptC 三段
      （靠 `logwrite` 的 `#####` 分隔線）
- [ ] AER / EDAC 差值計算：抽出 A 與 C 兩次的 `aer_dev_*` 與 `dimm_{ce,ue}_count`，輸出增量表，
      UE > 0 或 fatal/nonfatal > 0 直接標 FAIL
- [ ] Margin 表解析：把 9 顆 × 16ch 的 Vout / 偏差% 收成 CSV，標出超出 ±(profile 設定值 + 容差) 的軌
- [ ] 溫度 / 風扇 / 電源趨勢：soak 期間逐輪取樣 → CSV（可直接畫圖）
- [ ] Stress 判定：`mlucas_amm_log` 與 `bgctl` 各工作的 log
      （`/host/hw-eval/.../qfx5252-stress-{ssd,usb}.log`）的錯誤關鍵字掃描
- [ ] Traffic 判定：**直接複用 `tools/bcm_mibpair_report_V1.1.0.py`**（它已能吃 console log 的
      `show c` 段落並輸出 PASS/FAIL），不要重寫一套解析
- [ ] 管理網路判定：抓 `mgmt_ping_monitor.sh` 的 `RESULT` 行（已是單行可 grep 格式），
      並檢查 `nic_tx`/`nic_rx` 不為 0 —— 否則 PASS 也不能歸屬到那張卡
- [ ] NVMe / EDAC：`nvme smart-log`、`smartctl -x`、`ras-mc-ctl --summary` 的前後差值
- [ ] 產出 `Logs/<run>_summary.md`：一頁 PASS/FAIL + 每個子系統一行結論

**驗收條件：** 拿一份既有 log（如 `Blanton_Margin_20260814-164122.log`）跑解析器，
產出 summary 與 CSV；人工植入一筆假的 `dimm_ue_count=1` 後，summary 正確翻成 FAIL。

---

### Phase 6 — 打包、Runbook 與交付（工作量：S）

**目標：** 產出可直接交給現場測試員（或客戶）的一包，含操作手冊，不需要看原始碼。

**包含：**
- [x] `publish/publish.sh`：把 `src/Script_ABC_Blanton/` 打包成
      `publish/Script_ABC_Blanton_<Ver>/`（`-z` 另出 zip）。版號讀 Script A 檔頭，
      排除 `*.log` 但保留空的 `logs/`。工具本身進 git，產出被 gitignore
- [ ] `README.md`（現場用）：Tera Term 設定、A→B→C 操作順序、常見錯誤（BDF 不符、
      margin 掃不到、hammer 工具缺檔）與對應處理
- [ ] `CHANGELOG.md`：延續三支腳本頂端的 Version History，集中成一份
- [ ] 三支腳本的 header 版號與 `CHANGELOG.md` 對齊，`config.ttl` 加 `script_version` 並寫進 log 開頭
- [ ] `docs/TTL_Script_Blanton_Status_*.xlsx` 更新為全 OK，或把剩餘項目移進 Future Extensions
- [x] 打 git tag，push `nas` + `gitea`（已至 `V1.1.8`；`publish/` 依 Script A 檔頭版號打包）

**驗收條件：** 從 zip 解壓到一台乾淨的測試 NB，照 README 操作，不看原始碼就能完成一輪 A→B→C
並產出 summary；`publish/` 內容與 git tag 一致。

---

## Future Extensions

- **Script B 的 eye measurement**：Status 表 ScriptB「Take one round of eye measurement on uplink ports」
  目前是空區塊，待 TH6 SDK 的 eye scan 指令確認後補上。
- **PDB 電源轉換值驗證**：`blanton_pwr_data.sh` 的 PDB 段落在第一台 DUT（COM39）因 ch4 仲裁問題無法驗證，
  COM36 才拿到部分結果；`READ_VIN` 已知不是真的輸入電壓（跟隨 `READ_VOUT`）。待拿到 brick 的
  `MFR_ID`/`MFR_MODEL` 後對照 datasheet 定案。
- **`show_pcie_error_reg.ttl` 淘汰**：舊的合併版已被 7 支 per-device 版取代，確認無人引用後刪除。
- ✅ **BDF 自動偵測** —— 已於 `blanton_fpga_pcimem.sh` V1.5.0（2026-08-17）完成。
  下一步是把同樣的偵測結果餵給 `utils/show_pcie_error_reg_*.ttl`，
  讓 AER 那 7 組 BDF 也不用手改（目前仍是硬編碼）。
- **`stress_hhmd` / `stress_pcie` 的替代**：兩者已於 2026-08-17 移除，I2C／PCIe 的持續讀取壓力
  目前沒有替代品。若仍需覆蓋這塊，可考慮用 `blanton_cb_i2c.sh` / `cb_fpga` 寫一支輕量 loop。
- **SSH / 網路模式**：目前全走 COM console。若 DUT 管理網路可用，可改用 `plink`/`ssh` 執行同一組
  bash 工具，速度與可靠度都比 serial 好，TTL 只保留開機階段。
- **多 DUT 併行**：多台 DUT 同時 soak 時，Tera Term 每台開一個 macro window；
  可考慮改成 Python（`pyserial`）統一排程與集中收 log。
- ✅ **margin 子專案的重複檔** —— v2.6.0 已移除內含的 `blanton_cb_i2c.sh` /
  `blanton_fpga_pcimem.sh` 複本，改由 `_swb_find_backend` 往上層找共用版，漂移風險解除。
  與獨立 repo `LTC2980_Margin_Script` 的同步機制（submodule 或 vendored 腳本）仍待評估。
- **`Ref/margin_command_trace.md` 需重新產生**：SWB 章節的 1223 條 `cb_pmbus_*` 指令是依
  修正前的通道／位址展開的（其中 487 條用到已不存在的 `0x5D`/`0x5F`/`0x63`/`0x65`），
  文件已加過期警告但內文未動。第 1~4 章不受影響。
- **`wait_init.ttl` 沒有逾時出口**：若 pmon 一直起不來，`result` 既非 1 也非 2，迴圈會無限重試，
  Script A 既不往下走也不報錯。可加最大重試次數 + `messagebox` 提示。
- **腳本的執行權**：`mgmt_ping_monitor.sh` 與 `bmc_monitor.sh`（以及已停用的 `bmc_monitor_ddr.sh`）需人工 `chmod +x`。
  可在 Script B 起它之前補一行（比照既有的 `chmod +x ~/hammer/tools/amd/mlucas-avx2`），或在 publish 時處理。
- **`bmc_monitor_ddr.sh` 已停用**：B/C 內的呼叫已註解，DDR 壓力改由 `bgctl run bmc-manager run memtester`
  取代。檔案還留在 repo，待確認不再需要後刪除，或在檔頭標註停用。
  （`bmc_monitor.sh` 已於 2026-08-25 重新啟用，並加上 I2C 寫入/讀回圖樣測試。）
- **`rm /host/hw-eval/jobs/*` 清不掉子目錄**：Script A 用的是不帶 `-r` 的 `rm`，但 Script C
  是 `cp -r` 那個目錄，代表裡面可能有子目錄。清不乾淨的話，上一輪的 job log 會被當成這輪的一起
  複製到 USB。要確認 `bgctl` 的產出結構，必要時改成 `rm -rf .../jobs/*`。
- **100G PRBS 尚未接進 A/B/C**：`port_prbs_monitor.sh` 已隨包交付、可手動執行，但三支腳本裡的呼叫
  都還註解著（bring-up 中）。要啟用時記得 PRBS 期間 link 會顯示 down，`stop` 之後才會回來。
- **Script 5（Reboot Cycle）尚未上機驗證**：`5_Blanton_Script_Reboot_Cycle.ttl` 隨 V1.1.7 交付，
  但還沒在真 DUT 上跑過一輪完整循環。兩個要現場確認的點：`wait "Booting in blind mode"` 是否
  真的在每一版開機訊息裡出現（沒出現就會永遠等下去，而且沒有 `timeout` 保護）；以及每輪重跑
  `bmc-first-enroll` 是否安全。**沒有結束條件**，測夠了要自己關掉 macro。
- **`tmp/blanton_reboottest.sh`（bash 版重開循環）也未上機驗證**：不用 Tera Term、由 systemd 在
  每次開機跑一輪並自動 `reboot`，登入下 `stop` 才停。整個 `tmp/` 是 gitignored，**不會進交付包** ——
  驗證過再搬進 `Blanton_Script/`。未驗證的腳本混進 `Blanton_Script/` 之後，測試員分不出哪支能信。
- **交付包不含 `hammer/`，但 Script B 與 Script 4 都要用它**：V1.1.8 起 `hammer/` 是 gitignored
  且被 `publish.sh` 排除（~99 MB 的 mlucas binary，進 git 就永久留在 history）。這是刻意的 ——
  binary 由 DUT image 帶 —— 但代表**測試員解開交付包後 `~/hammer` 必須已經在 DUT 上**，
  否則 Script B 會在 `chmod +x ~/hammer/tools/amd/mlucas-avx2` 那一行失敗，而且 macro 不會停，
  接著的 `systemd-run` 只是起一個立刻失敗又被 `Restart=always` 反覆重拉的 unit。
  上機前先 `ls ~/hammer/tools/amd/mlucas-avx2` 確認一次。
- **`mlucas-amm` 的 `~` 依賴 systemd 的環境**：unit 是
  `/bin/bash -c '~/hammer/... >> ~/hammer/mlucas_amm_log'`，system service 沒有 `User=` 時 systemd
  **不會設 `HOME`**，bash 才退回 passwd 的家目錄（root → `/root`）解出同一條路徑。目前會通，
  但那是剛好對上而不是保證；改成絕對路徑 `/root/hammer/...` 就不用賭。**尚未上機驗證。**
- **Script C 的 USB 掛載走 `mount` 而非 `usb_target.sh -o mnt`**：目前是 `-o dev` 取節點再自己
  `mount <dev> /mnt/usb`，繞過了工具內建的 `mkdir -p`、exfat/ntfs `modprobe` 與可寫性驗證。
  掛載點不存在、檔案系統模組沒載、或媒體唯讀時只會失敗一行，job log 就沒帶出來。
- **風扇確認提示是無限等待**：`wait "Set all configured fan channels to"` 之後才 `sendln "y"`；
  若該版 `fan-speed-control.sh` 不再詢問（或字串改了），這個 `wait` 會永遠等下去，Script A 停在那裡
  且不報錯。加個 `timeout` + 分支會比較保險（記得還原 `timeout = 0`）。
- ✅ **TR518 已腳本化** —— `blanton_tr518.sh` V1.0.1（2026-08-28）。仍與 `blanton_traffic_linespeed`
  互斥（兩者都會動 `port cd` loopback 與 L2 學習），檔頭與 help 都標了。剩下三件事：
  `stop` 沒把 `l2 learn` / `test mode` 放回去（照 `TR518.txt` 的定義，旗標可開）；
  **`sleep 120` 的方向還沒驗證** —— 若 `tr 518` 的流量是有時限的（參數含 `runtime=1`、
  `CheckDataTime=200`），等 120 秒可能量到已經降下來的值，要上機比對 0s / 30s / 120s 三次；
  TTL 尚未呼叫它。
- **`--runtime` 是整個 job 的總時限，不是每個 pass 的**：V1.1.7 起由 `config.ttl` 宣告
  （`SSD_RUNTIME`/`SSD_COUNT`、`USB_RUNTIME`/`USB_COUNT`，COUNT 直接對應 `--passes`）。
  `qfx5252-stress-*` 跑滿 RUNTIME 秒就結束，**`--passes` 不會把它延長**，所以
  `RUNTIME=600, COUNT=720` 是 10 分鐘的壓力而不是 120 小時。要跑滿一天就把 RUNTIME 填 `86400`。
  **V1.1.8 起出貨預設是 `RUNTIME=3600`（1 小時）**，`BMC_USB_RUNTIME` 則是 `172800`（2 天）——
  三個壓力源的長度目前刻意不一致，開跑前要照當次 soak 的時間各自對一次。
  壓力提早結束時 Script B 每輪的 `bgctl list` 數量會變少，但**沒有任何東西會主動報警**；
  要比 24 小時更久則得加一段重啟 job 的邏輯。
- **BMC USB 的 service log 只剩隨身碟一份**：Script C 把 `journalctl` 導進
  `log/bmc_usb_net.log` 再 `cp` 到 job 目錄，**不再印在 master console log**。
  那個 `cp` 沒有檢查回傳值（`nfc_polling.log` 檔名打錯那次就是這樣安靜失敗的），
  失敗的話這份 log 就完全消失。要嘛在 `cp` 之後補一次 `ls` 驗證，要嘛保留一份
  `cat` 到 console。
- **`READ_VIN` / `READ_IIN` 不在 ADPM12200 手冊的 Table 3 裡**：`pwr_brick.sh` 讓它們沿用
  Voltage / Current 那兩組係數。50 V 輸入算得出來、數量級也對，但**手冊沒有明說**。要定案
  得找 ADI 確認，或找一個能獨立比對輸入電壓的量測點（`READ_VOUT` 就是靠 `show platform
  voltage` 的 `PDB_IBC_*` 對上的）。
- **VI2C 沒有硬體號誌**（`vi2c_muxsel` 的 help 自己寫了「VI2C has no SEM_REG」），而平台的
  sensor 驅動會週期性讀同一批 PDB 裝置。`pwr_brick.sh` 用「重讀到合理為止」繞過去，但根本
  問題沒解：`_vrd` 裡的 `_vwait` 逾時後仍然回傳半成品，呼叫端也沒檢查它的回傳值。修
  `blanton_icb_vi2c.sh` 會影響所有走 VI2C 的工具（ICB 溫感、風扇、EEPROM），值得先確認
  是不是跟 pmon 競爭再動。
- **`blanton_multiphase_margin.sh` 與 `margin.sh` 沒有互斥機制**：兩支從不同側（原生 i2c vs
  LTC2980 PMBus）摸同一批軌，各自都假設自己是唯一的寫入者。目前只靠文件與 help 提醒，
  沒有任何執行期檢查。
- **Script 4 沒有收尾段**：`while 1` 之後就是檔案結尾，中斷時 DUT 停在 `port cd lb=mac` /
  `l2 learn off` / `test mode nr=yes`，而且 CPU 壓力還在跑。要手動
  `blanton_tr518.sh stop` + `systemctl stop mlucas-amm`（V1.1.8 起它是 systemd unit，
  關掉 Tera Term 或 `kill $(jobs -p)` 都收不掉），否則下一輪任何測試都在被污染的狀態上開始
  （Script A 的 `bgctl reset/stop --all` 收得掉 job，但收不掉 bcm 的 loopback 設定）。
  可考慮加一支對應的收尾腳本，或在檔尾用 `messagebox` 提示要下哪些指令。
- **margin 在 soak 期間不再取樣**（V1.1.4）：只剩 Script A 的起始值與 Script C 的結束值。
  漂移發生在中間就看不到了。若要恢復，比較好的做法是在 B 的迴圈內每 N 輪才掃一次，
  而不是每輪都掃。
- **`blanton_ber.sh` 的 `sleep 30` 與 `BER_INTERVAL` 是兩處要同步改的數字**：Script C 寫死
  `sendln "sleep 30"`，腳本預設 `BER_INTERVAL=30`。改一邊沒改另一邊，report 會讀到還沒累積完
  一個 interval 的數字，而且不會有任何警告。
- **`ce0` 的 ingress mirror 尚未上機驗證**：`mirror port ce0 Mode=Ingress DestPort=ce0` 這條路是
  推論出來的（鏡像複本不受 egress filter 的 source-port knockout 限制），語法取自 DUT 的
  `help mirror`，但**還沒證明硬體真的接受 destport == srcport**。驗證方式是隔 10 秒看兩次
  `show c | grep POK.ce0`，數字有沒有繼續長 —— 光看 report 的 PASS 分不出來，因為一次性 burst
  也是 TX==RX。不通的話備案是 `tr 518 PortList=268`。
- **SWB 的 LTC2977 有兩條路可以到，目前工具兩條都在用**：`cb_pmbus_*`（CB FPGA F3 → pcimem）
  是 `margin_init` / `margin_status` / `margin_set` 走的路；原生 i2c bus（Ch+7 = bus 13/14/15/16）
  是 `margin_save blanton` 走的路。後者短很多 —— 不需要通道初始化、不需要 pcimem，
  單一 `i2cset` 就到。若原生 bus 在這平台夠穩，整個 `TRANSPORT="swb"` 層其實可以退成
  「bus 號不同的 i2c 路徑」，`_swb_*`、probe、semaphore、prescale 那整套都能拿掉。
  要動之前得先確認：讀取（`margin_status` 的 LINEAR16 word read）是否也同樣可靠，
  以及 kernel driver 有沒有搶著存取（`margin_save blanton` 帶 `-f` 就是為了繞過這件事）。
- **`settings/` 裡 SWB0 與 SWB1 是兩份相同的資料**：8 個 `.conf` 中，SWB1 的四個除了 `CHIPS[]` 的
  bus 與 `CB_I2C_CH` 之外，net name 與 `VNOM` 與 SWB0 逐欄相同（見 `docs/LTC2980_channel_map.csv`）。
  改一邊忘了改另一邊不會有任何警告。可考慮改成「共用 net 定義 + 各自的 transport 覆寫」兩層檔案。
- **Script C 沒有倒出 `mgmt_ping.log`**：C 會 `stop` 管理網路監控並印 `ip -s link show`，
  但沒有 `cat ~/Blanton_Script/log/mgmt_ping.log`，所以整個 soak 期間累積的 per-leg `RESULT`
  留在 DUT 上、沒進 master log。Script A 那輪基線有 `cat`。