docs: Fold the LTC2980 margin README into the user guide

Section 2.4 now carries the full LTC2980_Margin_Script usage: the nine
boards, every margin_* function, the OPERATION codes, all profiles
including the comboA/comboB checkerboards, the script/ batch runners, and
the NVM save commands with the 18-line margin_save blanton table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0131orciRKrejchsuDk6UpXk

src/Script_ABC_Blanton/Script_User_Guide.md

@@ -28,7 +28,7 @@
   - [2.1 總覽表](#21-總覽表)
   - [2.2 平台存取底層（source 進來用）](#22-平台存取底層source-進來用)
   - [2.3 溫度 / 電壓 / 電流 / 功耗](#23-溫度--電壓--電流--功耗)
-  - [2.4 電壓 Margin](#24-電壓-margin)
+  - [2.4 電壓 Margin（含 LTC2980 Margin Script 完整說明）](#24-電壓-margin)
   - [2.5 交換晶片：流量 / BER / FDR / 負載](#25-交換晶片流量--ber--fdr--負載)
   - [2.6 SerDes DSC 擷取](#26-serdes-dsc-擷取)
   - [2.7 背景監控（start / stop 型）](#27-背景監控start--stop-型)
@@ -499,21 +499,157 @@ PB_TRIES=1 ~/Blanton_Script/pwr_brick.sh show -r    # 看不經重試的原始
 
 ### LTC2980_Margin_Script/margin.sh — 9 顆 LTC2980
 
-```bash
+用 PMBus 控制 LTC2980 的電壓 margin。**一個 `.conf` = 一顆 LTC2980**（= 2 顆 LTC2977，每顆 8 channel，合起來 CH0~CH15）。
-source ~/Blanton_Script/LTC2980_Margin_Script/margin.sh
+
-margin_init Blanton_CB_CONN13        # 載入一顆（settings/ 底下的 .conf）
+```
-margin_status                        # 看每個 channel 的電壓與偏差 %
+~/Blanton_Script/LTC2980_Margin_Script/
-margin_set 0 high 8                  # ch0 margin high 8%
+├── margin.sh          ← 主程式（source 進來用）
-margin_set 5 low 5                   # ch5 margin low 5%
+├── settings/*.conf    ← 每顆 LTC2980 的 channel 定義（Vnom、Net 名稱、I2C 位址）
-margin_set 3 nominal 8               # ch3 回標稱值
+├── profiles/*.conf    ← 批次套用的 margin 組合
-margin_apply_profile profiles/combo_SWB_CONN13_high.conf     # 批次套用
+├── script/*.sh        ← 多顆一起跑（status / apply / save）
-margin_apply_profile profiles/all_off.conf                   # 全部回 nominal
+└── logs/              ← 操作 log（主 log + detail log）
 ```
 
-- 可載入的 9 顆：`Blanton_CB_CONN13`、`Blanton_SWB0_CONN13~16`、`Blanton_SWB1_CONN13~16`。
+#### 載入
-- **SWB 的 profile 是 per-CONN 的**：`combo_SWB_CONN13_*` 只能套在 CONN13，套錯 CONN 會 margin 到錯的軌，**而且不會報錯**。CB 用通用的 `combo_high3` / `combo_low3`。
+
-- 一次看全部 9 顆：`source ~/Blanton_Script/LTC2980_Margin_Script/script/margin_status_all.sh`
+```bash
-- `VNOM` 是 Blanton 實測中位數（2026-08-30 起），跨這個日期的 margin log 不能直接互比。
+cd ~/Blanton_Script/LTC2980_Margin_Script     # ← profile 路徑是相對於目前目錄，先 cd 進來
+source margin.sh
+margin_init Blanton_SWB0_CONN14              # 指定要操作哪一顆（支援 TAB 補全）
+```
+
+可以載入的 9 顆：
+
+| `margin_init` 名稱 | 板 / 接頭 |
+|---|---|
+| `Blanton_CB_CONN13` | CB 板 CONN13 |
+| `Blanton_SWB0_CONN13` ~ `Blanton_SWB0_CONN16` | SWB0 板 CONN13 ~ 16 |
+| `Blanton_SWB1_CONN13` ~ `Blanton_SWB1_CONN16` | SWB1 板 CONN13 ~ 16 |
+
+#### 函式一覽
+
+| 函式 | 說明 |
+|---|---|
+| `margin_init <NAME>` | 載入 `settings/<NAME>.conf`，之後的指令都作用在這一顆 |
+| `margin_status [ch]` | 讀 CH0~CH15（或指定 channel）的 Vout 與偏差 % |
+| `margin_set <ch> <op> <change%>` | 三合一：寫 margin 值 + 切 operation + 讀回驗證 |
+| `margin_set_value <ch> <vnom> <change%>` | 只寫 HIGH / LOW / OV / UV 暫存器 |
+| `margin_operation <ch> <op>` | 只切 OPERATION（不改 margin 值） |
+| `margin_apply_profile <file>` | 把一個 profile 套到目前載入的那顆 |
+| `margin_save` | ⚠️ 寫 NVM：目前這顆（2 顆 LTC2977） |
+| `margin_save all` | ⚠️ 寫 NVM：`settings/` 底下全部 9 顆，跑完切回原本那顆 |
+| `margin_save blanton` | ⚠️ 寫 NVM：Blanton 專用，18 顆 LTC2977 走原生 i2c，不需 `margin_init` |
+| `margin_debug [on\|off]` | 印出所有 i2c 指令（不帶參數 = 切換） |
+| `margin_log [on\|off]` | 開關 log 記錄（預設開） |
+
+`<op>` 對應的 OPERATION（PMBus 0x01）值：
+
+| op | 值 | 說明 |
+|---|---|---|
+| `high` | 0xA8 | margin high |
+| `low` | 0x98 | margin low |
+| `nominal` | 0x80 | 回標稱值 |
+| `off` | 0x00 | **關閉輸出** |
+
+Channel 編號：`ch / 8` 決定是哪顆 LTC2977（0 = 低位址、1 = 高位址），`ch % 8` 是該顆的 page（0~7）。
+
+#### 常用範例
+
+```bash
+margin_status                  # 全部 channel
+margin_status 3                # 只看 ch3
+
+margin_set 0 high 8            # ch0 margin high 8%
+margin_set 5 low 5             # ch5 margin low 5%
+margin_set 3 nominal 8         # ch3 回標稱值
+
+margin_operation 0 high        # 只切 operation
+margin_operation 0 nominal
+
+margin_apply_profile profiles/combo_SWB_CONN13_high.conf   # 批次套用（要在 LTC2980_Margin_Script/ 底下）
+margin_apply_profile profiles/combo_normal.conf            # 全部回 nominal
+
+margin_init Blanton_SWB1_CONN16                            # 換一顆
+margin_apply_profile profiles/combo_SWB_CONN16_high.conf
+```
+
+#### Profile 一覽
+
+| Profile | 適用 | 說明 |
+|---|---|---|
+| `combo_SWB_CONN13_high` / `_low` | **只能套 SWB CONN13** | 每個 channel 依該板的軌給 3% 或 5% |
+| `combo_SWB_CONN14_high` / `_low` | **只能套 SWB CONN14** | 同上 |
+| `combo_SWB_CONN15_high` / `_low` | **只能套 SWB CONN15** | 同上 |
+| `combo_SWB_CONN16_high` / `_low` | **只能套 SWB CONN16** | 同上 |
+| `comboA_SWB_CONN13~16` / `comboB_SWB_CONN13~16` | **只能套對應 CONN** | 棋盤式：相鄰軌一高一低；A、B 互補，兩個都跑完每條軌兩個方向都測到 |
+| `comboA_CB` / `comboB_CB` | **只能套 CB** | 同上，CB 版 |
+| `combo_high3` / `combo_low3` | 通用 | 全部 channel ±3%（CB 用這組） |
+| `combo_high5` / `combo_low5` | 通用 | 全部 channel ±5% |
+| `combo_normal` | 通用 | 全部回 nominal |
+| `all_off` | 通用 | ⚠️ 全部 OPERATION **off（關輸出）** |
+
+- SWB0 與 SWB1 的同號 CONN 共用同一個 profile（兩片板子的軌相同，只差 I2C bus）。
+- ⚠️ **per-CONN profile 套到別的 CONN 會 margin 到錯的軌，而且不會報錯。** 套之前確認 `margin_init` 載入的是哪一顆。
+- 回到正常狀態用 `combo_normal`，**不是 `all_off`**。
+
+#### 多顆一起跑（script/）
+
+```bash
+cd ~/Blanton_Script/LTC2980_Margin_Script
+source script/margin_status_all.sh            # 9 顆依序 margin_init + margin_status
+source script/margin_apply_profile_all.sh     # 每顆套各自的 profile（預設 SWB 用自己 CONN 的 _high，CB 用 combo_high3）
+source script/margin_save_all.sh              # ⚠️ 只寫其中幾顆的 NVM（全部 9 顆請用 margin_save all）
+```
+
+- 要改範圍：編各支 script 開頭的 `BOARDS=( ... )` 陣列，註解掉不想跑的那行。
+- `margin_apply_profile_all.sh` 另有 `PROFILES=( ... )` 陣列，`PROFILES[i]` 套在 `BOARDS[i]`，只寫名稱（不含路徑和 `.conf`），兩個陣列長度不同會直接報錯。
+- 跑 LOW 那一輪：把 `PROFILES` 裡的 `_high` 全換成 `_low` 再跑一次。
+- Script A / C 的 `EN_Margin=1` 走的就是 `margin_status_all.sh` + 逐顆 `margin_status`。
+
+#### 寫 NVM（⚠️ 永久，測試流程中絕不執行）
+
+`margin_save*` 會把目前的 margin / OV / UV 設定**永久寫進 NVM**，斷電不會還原，可能蓋掉客戶出廠設定。
+真的要寫之前，先用 `margin_status_all.sh` 確認每個 channel 的狀態正確。
+
+| 指令 | 寫哪些 | 備註 |
+|---|---|---|
+| `margin_save` | 目前載入的那顆（2 顆 LTC2977） | |
+| `margin_save all` | `settings/` 全部 9 顆 | 中途失敗不會停，最後印成功 / 失敗總結 |
+| `margin_save blanton` | 18 顆 LTC2977，走原生 i2c | 不需 `margin_init`、不動目前載入的那顆；2026-08-27 上機驗證 |
+
+`margin_save blanton` 送出的就是這 18 行（PMBus `STORE_USER_ALL` = `0x15`，send-byte，不帶 data）：
+
+```bash
+i2cset -f -y 4  0x5C 0x15 ; i2cset -f -y 4  0x5E 0x15    # CB   CONN13
+i2cset -f -y 15 0x5C 0x15 ; i2cset -f -y 15 0x5E 0x15    # SWB0 CONN13
+i2cset -f -y 13 0x5C 0x15 ; i2cset -f -y 13 0x5E 0x15    # SWB0 CONN14
+i2cset -f -y 15 0x62 0x15 ; i2cset -f -y 15 0x64 0x15    # SWB0 CONN15
+i2cset -f -y 13 0x62 0x15 ; i2cset -f -y 13 0x64 0x15    # SWB0 CONN16
+i2cset -f -y 16 0x5C 0x15 ; i2cset -f -y 16 0x5E 0x15    # SWB1 CONN13
+i2cset -f -y 14 0x5C 0x15 ; i2cset -f -y 14 0x5E 0x15    # SWB1 CONN14
+i2cset -f -y 16 0x62 0x15 ; i2cset -f -y 16 0x64 0x15    # SWB1 CONN15
+i2cset -f -y 14 0x62 0x15 ; i2cset -f -y 14 0x64 0x15    # SWB1 CONN16
+```
+
+| Linux bus | CB FPGA F3 通道 | 板 / 接頭 |
+|---|---|---|
+| 4 | （CPU 原生） | CB CONN13 |
+| 13 | Ch6 | SWB0 CONN14 / CONN16 |
+| 15 | Ch8 | SWB0 CONN13 / CONN15 |
+| 14 | Ch7 | SWB1 CONN14 / CONN16 |
+| 16 | Ch9 | SWB1 CONN13 / CONN15 |
+
+- **DUT 沒裝滿板子時**：把 `margin.sh` 開頭 `MARGIN_BLANTON_STORE` 陣列裡對應的行註解掉。
+- 回報 `/dev/i2c-N` 不存在 = FPGA 的 i2c adapter 沒起來；回報 NACK = 板子 / 晶片的問題。
+- 每顆之間預設等 0.5 秒（`MARGIN_STORE_SETTLE`），工具沒有去讀晶片的 busy bit，這段等待是唯一的緩衝。
+
+#### 注意事項
+
+- **改電壓會弄壞 DUT**：套 profile 前確認該軌的 OV / UV limit；部分 margin 電阻沒 populate，那些軌的電壓不會動，不是腳本壞了。
+- `margin_status` 的偏差 % 是以 `VNOM`（Blanton 實測中位數，2026-08-30 起）為分母；**跨這個日期的 margin log 不能直接互比**。
+- SWB 的 LTC2977 有兩條路可以到：一般功能走 CB FPGA（`cb_pmbus_*`），`margin_save blanton` 走原生 i2c。**同一顆晶片不要兩條路同時用。**
+- margin 之前 `margin.sh` 會自動把該 channel 的 `ON_OFF_CONFIG` 設成 `0x1a`（否則 margin 不會生效），這只改 RAM，斷電會還原，不是 NVM 寫入；`MARGIN_AUTO_ENABLE=0` 可關掉。
+- log 在 `LTC2980_Margin_Script/logs/`：主 log 是摘要，每行帶 `(detail Line:N)` 對到 detail log 的完整輸出。
 
 ### blanton_multiphase_margin.sh — 多相 VRM（38 條軌）