docs(arch): Add ARCHITECTURE and CLAUDE, init repo
Bring the Diag-OS variant of the Blanton A/B/C Tera Term scripts under version control, alongside the SONiC-based Blanton_TTL_Script. - ARCHITECTURE.md: Diag OS flow, acc_* command taxonomy, swutil addressing, TH6 test sequence side effects, and a 6-phase roadmap - CLAUDE.md: stack, per-script command inventory, conventions, footguns - .gitattributes: keep .ttl as CRLF (Windows-only), LF for everything else - .gitignore: secret/, For_AI/, *.log, publish/ output - secret/: README + config_secret.ttl.example for per-unit overrides - Logs/ and utils/ placeholders (logopen needs Logs/ to pre-exist) Known gaps documented, not fixed here: 2_Blanton_Script_B.ttl includes utils/show_margin_status.ttl which does not exist yet, and its while loop has no pause despite the "every 10mins" comment. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SoEiorvuhmdTkpZWtEhJwq
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,122 @@
|
||||
# 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`](../Blanton_TTL_Script) 是同一片硬體的 **SONiC 版**（有 bash 工具庫）。
|
||||
**兩邊不共用檔案**，`config.ttl` 同名但 prompt 不同，不要互相複製。
|
||||
|
||||
完整架構見 [ARCHITECTURE.md](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 前先手動敲）：**
|
||||
|
||||
```bash
|
||||
version # 有輸出 = console 通了
|
||||
acc_iai_i2c device # I2C 列舉，對照 golden list
|
||||
acc_iai_pcie device # PCIe 列舉
|
||||
acc_misc_liquid info # 漏液狀態，異常就別往下跑
|
||||
```
|
||||
|
||||
**Script A 涵蓋的主要指令（依執行順序）：**
|
||||
|
||||
```bash
|
||||
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 協作素材（截圖、草稿筆記）
|
||||
Reference in New Issue
Block a user