教學 01 — 版本血緣與共用池
操作前置條件:已安裝 iSVN 0.1.0-internal(fcf6302),並已備妥、初始化及驗證 Demo Kit v3 練習專案與 learner 工作區;專案必須包含下方列出的六個版本。這些步驟僅適用於該版本與資料集。缺少相符環境時,請以概念與操作示範閱讀,不要套用到真實團隊專案。
適用於 iSVN 0.1.0-internal(commit
fcf6302)與 Demo Kit v3。其他版本的畫面與指令輸出可能不同。
適合誰: 熟悉 Linux 基本操作與設計流程、第一次接觸 iSVN 的 IC 設計與 CAD 工程師。
你會做什麼: 從一個真實的除錯問題出發,透過 iSVN 記錄的血緣(lineage)找到正確的上游版本,只 Checkout 那一個版本,把它設為使用中的版本,並讀取它的檔案。接著了解 LINKED 標示代表什麼、Project File Cache Pool 有什麼好處,以及如何把檔案「設為可編輯」(Make Editable)再還原。
所需時間: 大約 30 分鐘。
怎麼使用這份 Guide
- 每個實作步驟都依相同順序撰寫:目的 → 前置條件 → 位置 → 操作 → 預期結果 → 如何確認 → 結果不同時。
- 圖片分成兩類,並在圖說中標明:
- 真實畫面:錄製的 learner 操作過程中未經修改的畫面。GUI 每次都以繁體中文啟動,本 Guide 的畫面與引用的介面文字都是繁體中文介面,必要時附上英文名稱方便對照英文版。
- 教學示意:用來說明概念的圖,不是產品畫面。示意圖中的文字是英文,本 Guide 在圖說中以中文說明。
- 真實畫面上的橘色與青色框是本 Guide 為了指出重點而加上的,畫面其他部分都沒有修改。
- 版本 ID 的結構是
<phase>/<block>/<stage>/<version>,例如trial/cpu/200_fe_datain/v2。口語中fe唸作 Front-End、datain唸作 Data-In,所以200_fe_datain/v2唸作「Front-End Data-In v2」。
目錄
- 問題情境
- 開始之前
- 準備示範專案
- 追溯血緣
- 選取並 Checkout
- Set Active 並查看 Work
- Project File Cache Pool 的好處
- 修改檔案:設為可編輯
- Flow 情境與限制
- 回顧與自我檢查
- 附錄 A · 疑難排解
- 附錄 B · 名詞解釋
- 附錄 C · 用命令列 Checkout(選用)
- 附錄 D · 來源、版本與限制
1. 問題情境
APR/layout 出了問題,你被要求 review 一份 layout 資料輸入:trial/cpu/400_layout_datain/v1。要除錯,你需要找出它實際所依據的 front-end 資料輸入。
版本清單裡有兩個 front-end 候選:200_fe_datain/v2 和 200_fe_datain/v3。依「選號碼最大的」習慣會挑 v3。但在 IC 設計中,每一次 ECO 或客戶改版都可能開出一條新的 stage 版本路徑。版本號比較大,只代表「比較晚建立」,不代表它就是「你正在除錯的那個版本的上游」。

圖 F01 · 教學示意。箭頭代表記錄下來的上游關係。檢查目標 400_layout_datain/v1 是從 200_fe_datain/v2 建立的。虛線問號代表一個誘人的假設:以為版本號較大的 200_fe_datain/v3 才是它的來源;其實 v3 屬於另一條路徑。
iSVN 會為每個版本記錄它是從哪個版本建立的。這份記錄下來的血緣能直接回答問題,你不必再從版本號、資料夾名稱或時間去猜。
2. 開始之前
需要準備
| 項目 | 說明 |
|---|---|
| 電腦 | Linux x86_64,glibc 2.34 或更新(目標平台:Ubuntu 24.04、Rocky Linux 9),並有可開啟 GUI 的圖形桌面環境 |
| Qt | Terminux 使用的 Qt 6.7.3 gcc_64 安裝。iSVN 不自帶 Qt,而是連結到這一份。 |
| iSVN 套件 | isvn-0.1.0-internal-fcf6302-linux-x86_64.tar.gz |
| Demo Kit | isvn-demo-kit-tut01-v3-0.1.0-internal.tar.gz,用來建立練習專案 |
| 其他 | python3(Demo Kit 會用到)。不需要 root 權限,也不需要另外安裝 Subversion,套件已附帶自己的 Subversion 工具。 |
步驟 2.1 · 檢查安裝結果
- 目的: 在使用已準備好的示範資料集之前,確認 iSVN、附帶的 Subversion 工具與共用的 Qt 都能正常運作。
- 前置條件: 已安裝相符的 iSVN 0.1.0-internal(fcf6302)。以下檢查必須以
Ready.結束,且版本輸出必須相符;否則 STOP,不要繼續。 - 位置: 同一個終端機(任何資料夾都可以)。
- 操作:
ISVN_HOME="$HOME/.local/opt/isvn/current"
"$ISVN_HOME/isvn-preflight"
"$ISVN_HOME/isvn" version
- 預期結果:
isvn-preflight對 CLI 以及附帶的svn、svnadmin、svnmucc印出OK,接著是 Qt 檢查,最後一行是Ready.;isvn version印出isvn 0.1.0-internal與commit: fcf6302。
- 如何確認: preflight 的最後一行是
Ready. - 結果不同時:
- 出現
WARN no DISPLAY只代表這個終端機沒有圖形環境;CLI 仍可使用,之後請從桌面環境中的終端機開啟 GUI。 - 其他警告或失敗:先停在這裡,把完整輸出交給你的 iSVN 聯絡窗口。
- 出現
3. 準備示範專案
已準備好的 Demo Kit v3 練習資料集包含:
- 一個本機 Subversion repository;
- 一個 iSVN 專案,內含 CPU block 的六個版本,以及各版本記錄下來的上游;
- 一個給你使用、目前是空的 learner 工作區。
所有設計檔案都是合成的教學資料。
步驟 3.1 · 在 learner 工作區開啟 iSVN GUI
- 目的: 在 iSVN 認得你的工作區與專案的位置啟動 GUI,並確認介面語言。
- 前置條件: 相符的 Demo Kit v3 練習專案已初始化並驗證,包含下方六個版本及 learner 工作區;步驟 2.1 的 preflight 以
Ready.結束,版本符合 0.1.0-internal(fcf6302)。請在圖形桌面環境中的終端機執行。 - 位置: learner 工作區資料夾
~/isvn_demo/learner-workspace。 - 操作: 從 learner 工作區啟動 GUI。視窗開啟後,看一下右上角的語言按鈕,說明如下。
ISVN_HOME="$HOME/.local/opt/isvn/current"
cd "$HOME/isvn_demo/learner-workspace"
"$ISVN_HOME/isvn-gui"
- 預期結果:
- 視窗開啟在 工作(Work)頁,介面是繁體中文。GUI 每次開啟都以繁體中文啟動;
- 右上角的語言按鈕顯示「繁體中文」。每按一次會切換到下一種語言(繁體中文 → 简体中文 → English);本 Guide 使用繁體中文介面,不需要切換;
- 因為還沒有 Checkout 任何版本,Work 頁顯示「沒有本機工作版本」與「先檢出一個版本,然後重新整理。」

圖 F02 · 真實畫面。GUI 在 learner 工作區開啟後的 Work 頁。橘色框是語言按鈕;青色框標出空白狀態訊息「沒有本機工作版本」。
- 如何確認: 上方有「首頁」(Home)、「工作」(Work)、「探索」(Explore)、「維運」(Maintenance)四個分頁,語言按鈕顯示「繁體中文」,Work 頁顯示上述空白狀態訊息。
- 結果不同時:
- GUI 顯示的是別的專案:關閉後從
~/isvn_demo/learner-workspace重新啟動,GUI 會使用啟動時所在的資料夾。 - 一啟動就結束,並顯示 An existing GUI endpoint could not be authenticated:請看附錄 A。
- GUI 顯示的是別的專案:關閉後從
步驟 3.2 · 列出所有版本
- 目的: 在選擇之前,先看到這個 block 的所有版本。
- 前置條件: 已選定相符、已初始化及驗證的 Demo Kit v3 learner 工作區。GUI 保持開啟,另外開第二個終端機。
- 位置: learner 工作區
~/isvn_demo/learner-workspace。新的終端機不會記得先前設定的變數,所以下面會重新設定。 - 操作:
ISVN_HOME="$HOME/.local/opt/isvn/current"
cd "$HOME/isvn_demo/learner-workspace"
"$ISVN_HOME/isvn" branches
- 預期結果: 六個版本,都屬於同一個 phase(
trial)與 block(cpu):
trial/cpu/000_datain/v1
trial/cpu/200_fe_datain/v1
trial/cpu/200_fe_datain/v2
trial/cpu/200_fe_datain/v3
trial/cpu/400_layout_datain/v1
trial/cpu/400_layout_datain/v2
GUI 中也看得到同樣六個版本。在 探索(Explore)頁按「選擇版本」(Choose version):

圖 F03 · 真實畫面。版本選擇清單依路徑列出各版本。200_fe_datain/v2(青色框)和版本號較大的 v3(橘色框)緊鄰排列,畫面上沒有任何標示說哪一個是「最新」或「正確」的。
- 如何確認: 兩邊的清單都剛好是這六個 ID。經過幾次 ECO 之後,
200_fe_datain有 v2 與 v3,400_layout_datain有 v1 與 v2。 - STOP:繼續前請確認練習專案符合 Demo Kit v3 的版本清單。
如果你開啟了選擇清單,先按 Close 關閉,第 5 章會再用到。
4. 追溯血緣
任務是 review 400_layout_datain/v1,所以你需要的是它實際所依據的 front-end 輸入,而不一定是號碼最大的那個。直接問 iSVN。
步驟 4.1 · 查詢檢查目標的血緣
- 目的: 讀取 iSVN 在建立每個版本時記錄下來的上游鏈。
- 前置條件: 步驟 3.2 的第二個終端機。
- 位置:
~/isvn_demo/learner-workspace(同一個終端機,變數已設定)。 - 操作:
"$ISVN_HOME/isvn" ancestry trial/cpu/400_layout_datain/v1
- 預期結果:
trial/cpu/400_layout_datain/v1
<- trial/cpu/200_fe_datain/v2
<- trial/cpu/200_fe_datain/v1
<- trial/cpu/000_datain/v1
- 如何確認:
400_layout_datain/v1下方的第一個上游是200_fe_datain/v2。 - 結果不同時: 如果指令回報找不到版本,請對照
branches的清單檢查拼字。ID 區分大小寫,並使用底線。
步驟 4.2 · 對照另一個 layout 輸入
- 目的: 看清楚
200_fe_datain/v3實際屬於哪一條路徑。 - 前置條件: 步驟 4.1。
- 位置: 同一個終端機。
- 操作:
"$ISVN_HOME/isvn" ancestry trial/cpu/400_layout_datain/v2
- 預期結果:
trial/cpu/400_layout_datain/v2
<- trial/cpu/200_fe_datain/v3
<- trial/cpu/200_fe_datain/v1
<- trial/cpu/000_datain/v1

圖 F04 · 真實終端機。錄製時用完整路徑 ~/.local/opt/isvn/current/isvn 執行同樣兩個指令,並多加了 echo "[rc=$?]"。400_layout_datain/v1 來自 200_fe_datain/v2(青色框);400_layout_datain/v2 來自 200_fe_datain/v3(橘色框)。
- 如何確認:
200_fe_datain/v3只出現在400_layout_datain/v2的上游鏈中。 - 結果不同時: 請看步驟 4.1。
這代表什麼
200_fe_datain/v3的號碼比較大,但它在另一條路徑上,不是400_layout_datain/v1的上游。- 要 review 的版本是
200_fe_datain/v2。 - 兩條路徑都從
200_fe_datain/v1出發,那裡就是兩個 ECO 方向分岔的地方。 - 這裡的「血緣」是指建立每個版本時記錄下來的上游鏈,不是從名稱、號碼或日期推測出來的。
5. 選取並 Checkout
在 GUI 中,「選取版本」和「Checkout 版本」是兩個不同的動作。選取只是檢視這個版本;Checkout 才會把它取回你的工作區。
步驟 5.1 · 在 Explore 選取 200_fe_datain/v2
- 目的: 在取回副本之前,先開啟正確的版本來檢視。
- 前置條件: 第 4 章已確認要用的版本是
trial/cpu/200_fe_datain/v2。 - 位置: GUI → 探索(Explore)。
- 操作: 按「選擇版本」,再點清單中的
trial/cpu/200_fe_datain/v2。 - 預期結果:
- 「檢視中的版本」欄位顯示
trial/cpu/200_fe_datain/v2; - 下方提示:「這個版本不在此工作區中。Checkout 只會建立它的本機 working copy,不會改變啟用中的版本。」
- 「檢視中的版本」欄位顯示

圖 F05 · 真實畫面。200_fe_datain/v2 是檢視中的版本(青色框),提示(橘色框)說明 Checkout 只會建立它的本機 working copy,不會改變啟用中的版本。此時尚未 Checkout。
- 如何確認: 右上角出現「Checkout…」按鈕;你的 learner 工作區中還沒有任何版本資料夾。
- 結果不同時: 如果顯示的是別的版本,再開一次「選擇版本」,點
200_fe_datain/v2那一列(不是 v3)。
步驟 5.2 · Checkout v2
- 目的: 只把
200_fe_datain/v2這一個版本取回你的工作區,成為 Working Copy。 - 前置條件: 步驟 5.1;v2 是檢視中的版本。
- 位置: GUI → 探索(Explore),右上角。
- 操作: 按「Checkout…」,看完對話框內容後,按對話框中的「Checkout」。如果改按「取消」,一切都不會改變。
- 預期結果:
- 標題為「Checkout 版本」的對話框詢問是否要把這個版本 checkout 到你的工作區,並列出版本
trial/cpu/200_fe_datain/v2與本機資料夾…/learner-workspace/trial/cpu/200_fe_datain/v2; - 對話框也說明只會 checkout 這一個版本,啟用中的版本不會改變;
- 確認之後,提示訊息回報 checkout 完成,並再次說明「啟用中的版本沒有改變」。
- 標題為「Checkout 版本」的對話框詢問是否要把這個版本 checkout 到你的工作區,並列出版本

圖 F06 · 真實畫面。按右上角的「Checkout…」後出現的確認對話框,列出版本與將要建立的資料夾(青色框)。按下對話框中的「Checkout」(橘色框)只會取回這一個版本。
- 如何確認: 接著到 Work 頁做步驟 6.1。
- 結果不同時: 如果對話框列出的是別的版本,按「取消」,然後重做步驟 5.1。
6. Set Active 並查看 Work
磁碟上有了 Working Copy,還不等於「你正在處理這個版本」。在 iSVN 中,你正在處理的是使用中(啟用中)的版本,必須透過 Set Active 明確指定。
步驟 6.1 · 確認 Checkout 沒有改變使用中的版本
- 目的: 分清楚「已 Checkout」和「使用中」的差別。
- 前置條件: 步驟 5.2。
- 位置: GUI → 工作(Work)。
- 操作: 點「工作」分頁。
- 預期結果:
- 「本機工作版本」底下列出
v2(trial / cpu / 200_fe_datain),狀態為「乾淨」; - 頁首仍顯示「尚無使用中版本」,檔案清單是空的。
- 「本機工作版本」底下列出

圖 F07 · 真實畫面。v2 已經是本機工作版本(青色框),但仍然沒有使用中的版本(橘色框),也沒有檔案清單。Checkout 不等於 Set Active。
- 如何確認: 頁首顯示「尚無使用中版本」。
- 結果不同時: 如果沒有列出
v2,代表 Checkout 沒有執行,回到步驟 5.2。
步驟 6.2 · 把 v2 設為使用中
- 目的: 告訴 iSVN 你現在要處理的是
200_fe_datain/v2。 - 前置條件: 步驟 6.1。
- 位置: GUI → 探索(Explore)右上角,檢視中的版本仍是
200_fe_datain/v2。 - 操作: 按「設為啟用並開啟工作」(Set Active and Open Work)。
- 預期結果: GUI 切換到 工作(Work)頁並開啟 v2(見步驟 6.3)。

圖 F08 · 真實畫面。回到 Explore,提示(青色框)確認版本已 checkout 到 learner 工作區,而且啟用中的版本沒有改變。接下來要按的是「設為啟用並開啟工作」(橘色框)。
- 如何確認: 接著做步驟 6.3。
- 結果不同時: 如果找不到這個按鈕,確認檢視中的版本仍是
trial/cpu/200_fe_datain/v2(步驟 5.1)。
步驟 6.3 · 在 Work 讀取四個 LINKED 檔案
- 目的: 確認使用中的版本就是你選的那一個,並查看它的檔案。
- 前置條件: 步驟 6.2。
- 位置: GUI → 工作(Work)(會自動開啟)。
- 操作: 看頁首與「檔案狀態」清單。
- 預期結果:
- 頁首「使用中的工作版本」顯示 trial / cpu / 200_fe_datain / v2;
- 檔案清單有四個檔案:README、時序約束、設計規格與 RTL。每個檔案都是「乾淨」,來源為 LINKED:
| 路徑 | 狀態 | 來源 | 大小 |
|---|---|---|---|
README.md |
乾淨 | LINKED | 270 B |
constraints.sdc |
乾淨 | LINKED | 239 B |
design_spec.md |
乾淨 | LINKED | 379 B |
top.v |
乾淨 | LINKED | 383 B |

圖 F09 · 真實畫面。使用中的版本(左上青色框)以及四個乾淨、來源為 LINKED 的檔案(橘色框)。右側「工作流程」面板中有「設為可編輯」(Make Editable)按鈕(青色框),第 8 章會用到。
- 如何確認: 頁首是
200_fe_datain / v2,四個檔案都顯示 LINKED。 - 結果不同時:
- 頁首仍是「尚無使用中版本」:Set Active 沒有完成,重做步驟 6.2。
- 檔案或大小不同:確認你選的是 v2 而不是 v3。
步驟 6.4 · 在終端機讀取 top.v
- 目的: 親眼確認這些檔案就是你要 review 的設計資料。
- 前置條件: 步驟 6.3;第二個終端機,位於 learner 工作區。
- 位置:
~/isvn_demo/learner-workspace。 - 操作:
cat trial/cpu/200_fe_datain/v2/top.v
- 預期結果: v2 的 RTL,一個帶
en(enable)輸入的 4-bit 計數器:
// demo_counter: 4-bit counter with synchronous enable (synthetic tutorial example).
module top (
input wire clk,
input wire rst_n,
input wire en,
output reg [3:0] count
);
always @(posedge clk or negedge rst_n) begin
if (!rst_n)
count <= 4'd0;
else if (en)
count <= count + 4'd1;
end
endmodule

圖 F10 · 真實終端機,位置在 learner 工作區。指令(青色框)以及 v2 設計中的 en 輸入(橘色框)。
- 如何確認: 檔案中有
input wire en,這一行。 - 結果不同時: 出現 No such file or directory,代表你不在 learner 工作區(執行
cd "$HOME/isvn_demo/learner-workspace"),或還沒有 Checkout(步驟 5.2)。
到這裡,你已經依血緣找到正確的上游版本,只 Checkout 了那一個版本,把它設為使用中,並讀取了它的檔案。
7. Project File Cache Pool 的好處
步驟 6.3 的四個檔案都標示為 LINKED。在大型 IC 設計專案中,許多 stage 版本的檔案內容相同,例如同一份 RTL、約束或規格從一個版本沿用到下一個版本。如果沒有任何機制,每個版本的每份 Working Copy 都會各自存一份這些檔案。
iSVN 可以把相同內容的工作檔案,在專案的 Project File Cache Pool 中只存一份唯讀副本。Working Copy 中的 LINKED 檔案指向這份共用的唯讀內容,而不是另存一份。

圖 F11 · 部署示意(圖中標示「教學示意」)。工程師保有各自的帳號與 Working Copy,同一個專案群組的成員共用共享專案儲存空間上的一個 Pool。projA_f01、projA_b03、projA_grp 與範例 Pool Owner projA_p00 都是範例名稱,不是必須建立的帳號。多台伺服器共用是目標部署形態,尚未驗證。

圖 F12 · 教學示意。200_fe_datain/v2/top.v 與 400_layout_datain/v1/top.v 的內容完全相同(示範專案中,layout v1 原封不動沿用了 fe v2 的 top.v),所以兩個 LINKED 檔案都指向同一份唯讀物件。共用的只有工作樹檔案。
這代表什麼,以及不代表什麼:
- 它減少的是重複的工作檔案:內容相同、未修改的工作檔案只存一份。
- 每位工程師仍有自己的 Working Copy,Subversion 也仍會為每份 Working Copy 保留自己的資料(
.svn/pristine)。Checkout 仍然會從 Subversion 取得資料。 - 它不會對 Subversion repository 去除重複,不代表「零下載」,本 Guide 也沒有量測任何節省比例。
- 展示與驗證的差別:
- 本 Guide 的真實畫面都來自單一帳號的操作;
- 多位工程師共用一個 Pool,在這裡只以概念圖呈現;
- 多台伺服器共用一個 Pool 尚未驗證。
8. 修改檔案:設為可編輯
LINKED 檔案指向共用的唯讀物件,所以不能直接在原處修改。需要修改檔案時,要先取得你自己的副本。

圖 F13 · 操作概念示意,不是產品畫面。工程師選擇「設為可編輯」(Make Editable)後,iSVN 在該 Working Copy 中建立個人的 LOCAL 副本,共用的唯讀物件不會改變。檔案不會自行變成可編輯。
- 原則: 檔案不會自行變成可編輯或個人副本。只有在**你主動對檔案選擇「設為可編輯」**時,iSVN 才會建立個人副本。
- 會發生什麼: 檔案的來源從 LINKED 變成 LOCAL,也就是你 Working Copy 中的個人可編輯副本。不會建立版本庫修訂,Project Pool 中的物件也不會被修改,所以其他連結到相同內容的 Working Copy 不受影響。
- 動手試試: 步驟 8.1 與 8.2 是選用的:先把
top.v設為可編輯,再把它還原為 LINKED,讓 Working Copy 回到步驟 6.3 結束時的狀態。這兩個步驟只會改變你自己的 Working Copy,不會改動版本庫。
步驟 8.1 · 把 top.v 設為可編輯(選用)
- 目的: 親眼看到 LINKED 檔案變成你自己的 LOCAL 副本。
- 前置條件: 步驟 6.3;Work 頁首顯示使用中的版本為
trial / cpu / 200_fe_datain / v2。 - 位置: GUI → 工作(Work):「檔案狀態」清單與「工作流程」面板。
- 操作: 勾選
top.v前面的方框,按「工作流程」面板中的「設為可編輯」,在確認畫面按「套用」。出現結果畫面後,按「完成」。

圖 F14 · 真實畫面。已勾選 top.v(青色框),「工作流程」面板顯示「已選路徑 · 1」,「設為可編輯」(橘色框)現在可以按了。

圖 F15 · 真實畫面。確認畫面「設為可編輯」說明:將受管檔案轉為可編輯的本機副本,不會建立版本庫修訂。按「套用」(橘色框)執行;按「取消」則檔案不變。這個畫面不會列出檔名,按下之前請先確認勾選的檔案。
- 預期結果:
- 結果畫面顯示「已完成」與「未建立版本庫修訂」;
- 按「完成」後,Work 中的
top.v狀態為「可編輯」、來源為 LOCAL,大小仍是 383 B;頁首多出「1 已變更」與「1 LOCAL」; - 其他三個檔案仍是「乾淨」與 LINKED。

圖 F16 · 真實畫面。top.v 現在是「可編輯」、LOCAL(橘色框);頁首顯示一個已變更、一個 LOCAL 檔案(青色框)。其他三個檔案仍是 LINKED。
- 如何確認: 「來源」欄中
top.v是 LOCAL,其他三個檔案是 LINKED。 - 結果不同時:
- 「設為可編輯」一直是灰色:沒有勾選任何檔案(「已選路徑 · 0」)。
- 如果按了「取消」,一切都沒有改變;重新做這個步驟。
步驟 8.2 · 把 top.v 還原為 LINKED(選用)
- 目的: 復原步驟 8.1,讓 Working Copy 回到步驟 6.3 結束時的狀態。
- 前置條件: 步驟 8.1;
top.v仍是勾選狀態。 - 位置: GUI → 工作(Work)的「工作流程」面板。
- 操作: 按「還原」。確認畫面會警告「這會捨棄本機變更」:還原受管狀態並捨棄本機修改,不會建立版本庫修訂。如果你改過
top.v而且想保留,請在這裡按「取消」;否則按「套用」,再在結果畫面按「完成」。 - 預期結果:
top.v回到「乾淨」與 LINKED,頁首不再顯示「1 已變更」或「1 LOCAL」。 - 如何確認: 四個檔案都再次顯示 LINKED,和圖 F09 相同。
- 結果不同時: 如果
top.v仍顯示 LOCAL,確認它有被勾選,然後重做這個步驟。
9. Flow 情境與限制
在設計 Flow 中,血緣更加重要。一次 Flow 執行可能同時讀取好幾個 stage 的 RTL、約束與其他資料。如果其中一份來自另一條 ECO 或客戶改版路徑,Flow 仍可能順利跑完,但結果建立在錯誤的資料組合上。
iSVN 記錄了每個版本的來源。把它和 Flow 實際讀取了哪些資料的記錄(例如來自 Terminux)放在一起,就能互相比對,讓工程師注意到值得檢查的不一致。
僅為概念。 本章介紹的是整合概念。本 Guide 不主張 iSVN,或 iSVN 搭配 Terminux,能自動偵測混用的 Flow 輸入。目前需要你自己比對這些記錄,方法就是第 4 章示範的
isvn ancestry。
10. 回顧與自我檢查

圖 F17 · 回顧卡,卡片文字為英文。
四個步驟:
- 追溯血緣(Trace the lineage):
isvn ancestry trial/cpu/400_layout_datain/v1指向200_fe_datain/v2。 - 選對 stage 版本(Choose the right stage version):是
200_fe_datain/v2,不是號碼較大的 v3。 - 只 Checkout 一次(Checkout once):一份 Working Copy,使用中的版本不變。
- Set Active 後再 review(Set Active, then review):Work 列出 v2 的四個檔案。
兩個重點:
- 正確的血緣(Correct lineage):依血緣選版本,不是選號碼最大的。
- 有效率的工作儲存(Efficient working storage):透過 Project Pool 重複使用內容相同的工作檔案。
自我檢查
| 問題 | 去哪裡看 | 預期答案 |
|---|---|---|
400_layout_datain/v1 是從哪個版本建立的? |
isvn ancestry trial/cpu/400_layout_datain/v1 |
trial/cpu/200_fe_datain/v2 |
| v3 是檢查目標的上游嗎? | 兩個 layout 輸入的 isvn ancestry |
不是,v3 是 400_layout_datain/v2 的上游 |
| Checkout 有改變使用中的版本嗎? | Checkout 之後的 Work 頁 | 沒有,頁首顯示「尚無使用中版本」 |
| 現在使用中的版本是哪一個? | Work 頁首 | trial / cpu / 200_fe_datain / v2 |
| 四個檔案的來源是什麼? | Work「檔案狀態」清單的「來源」欄 | LINKED |
| 要怎麼取得可編輯的副本? | Work 的「工作流程」面板 | 勾選檔案後選擇「設為可編輯」,它會變成 LOCAL(步驟 8.1) |
| 要怎麼把它還原為 LINKED? | Work 的「工作流程」面板 | 「還原」;這會捨棄該檔案的本機修改(步驟 8.2) |
附錄 A · 疑難排解
| 看到的現象 | 可能原因 | 安全的下一步 |
|---|---|---|
| isvn-preflight 未以 Ready. 結束,或版本不是 0.1.0-internal(fcf6302) | 相依環境或安裝版本與本教學不符 | STOP:保留 preflight 輸出,請管理者確認安裝版本與 Qt 6.7.3;未符合前置條件時不要繼續。 |
isvn-preflight 最後一行不是 Ready. |
缺少系統函式庫或 Qt 有問題 | 保留輸出並聯絡 iSVN 窗口,不要繼續 |
| GUI 結束並顯示 An existing GUI endpoint could not be authenticated | 執行期資料夾路徑(XDG_RUNTIME_DIR)特別長,常見於容器或測試環境;一般桌面環境不會發生 |
從一般桌面環境的終端機啟動 GUI |
| GUI 沒有任何版本,或顯示別的專案 | GUI 不是在 learner 工作區啟動的 | 關閉後從 ~/isvn_demo/learner-workspace 重新啟動 |
| Checkout 之後 Work 沒有檔案 | 還沒有 Set Active | 做步驟 6.2 |
| 切換過語言,重新開啟 GUI 後又是繁體中文 | GUI 每次都以繁體中文啟動,語言設定不會保存 | 需要其他語言時,再按語言按鈕切換(步驟 3.1) |
| 重新開啟 GUI 後,Work 顯示「尚無使用中版本」,但 v2 之前是使用中 | 在新帳號上,這個版本可能不會在兩次開啟之間記住使用中的版本 | 在 Explore 重新選擇 trial/cpu/200_fe_datain/v2(畫面會說明這個版本已在此工作區中),再按「設為啟用並開啟工作」。不要再 Checkout 一次 |
cat …/top.v 顯示 No such file or directory |
資料夾不對,或還沒有 Checkout | 執行 cd "$HOME/isvn_demo/learner-workspace";確認步驟 5.2 |
| 版本 ID 和步驟 3.2 的六個不同 | 專案是用別的 Demo Kit 建立的 | STOP:請確認已備妥、初始化及驗證的 Demo Kit v3 練習資料集,且包含步驟 3.2 列出的六個版本;不相符時不要繼續。 |
注意安全:
- 本教學完全不需要管理類或破壞性的指令。跟著本 Guide 操作時,不要對真實專案執行
delete、gc或admin init。 - 發生預期外的狀況時,先停下來並保留終端機輸出。
附錄 B · 名詞解釋
| 名詞 | 在本 Guide 中的意思 |
|---|---|
| 版本 ID | <phase>/<block>/<stage>/<version>,例如 trial/cpu/200_fe_datain/v2 |
datain、fe |
Data-In、Front-End;200_fe_datain 是 front-end 資料輸入 stage,400_layout_datain 是 layout 資料輸入 stage |
| ECO | Engineering Change Order(唸作「E-C-O」);每次 ECO 或客戶改版都可能開出一條新的版本路徑 |
| 血緣(Lineage) | 記錄下來的上游版本鏈,在建立每個版本時設定 |
isvn ancestry |
印出某個版本記錄下來的血緣 |
| 探索(Explore) | 瀏覽版本與血緣的 GUI 頁面 |
| 選擇版本(Choose version) | 開啟 Explore 中的版本選擇清單 |
| Checkout | 為一個版本建立本機 Working Copy;不會改變使用中的版本 |
| 設為啟用並開啟工作(Set Active) | 把已 Checkout 的版本設為你正在處理的版本,並在 Work 中開啟 |
| 使用中的工作版本(Active version) | Work 頁顯示並操作的版本 |
| Working Copy | 某個版本在你工作區中的本機副本 |
| 工作(Work) | 顯示使用中版本與其檔案的 GUI 頁面 |
| LINKED | 指向 Project File Cache Pool 中共用唯讀物件的工作檔案 |
| LOCAL | 你 Working Copy 中的個人可編輯檔案 |
| 設為可編輯(Make Editable) | 把 LINKED 檔案變成你自己的 LOCAL 副本的動作 |
| 還原(Revert) | 讓選取的檔案回到受管狀態;會捨棄這些檔案的本機修改 |
| Project File Cache Pool | 專案的儲存空間,內容相同的工作檔案只保留一份唯讀副本 |
| 乾淨(clean) | 沒有本機修改 |
附錄 C · 用命令列 Checkout(選用)
下面這個指令建立的 Working Copy,與步驟 5.2 的 GUI Checkout 相同。如果你偏好用終端機,可以用它取代步驟 5.2,在步驟 3.2 的第二個終端機執行(位於 learner 工作區,ISVN_HOME 已設定):
"$ISVN_HOME/isvn" checkout trial/cpu/200_fe_datain/v2
它會印出 checked out trial/cpu/200_fe_datain/v2 to …/learner-workspace/trial/cpu/200_fe_datain/v2。和 GUI 的 Checkout 一樣,它不會設定使用中的版本;之後請在 GUI 做步驟 6.2。
附錄 D · 來源、版本與限制
- 展示的產品:
- iSVN Portable 0.1.0-internal,commit
fcf6302,共用 Terminux 的 Qt 6.7.3; - Demo Kit v3,使用標準版本 ID。
- iSVN Portable 0.1.0-internal,commit
- 真實畫面: 中立的 learner 操作,單一帳號(
learner),在可拋棄的容器中錄製:繁體中文 GUI 與終端機畫面錄於 2026-11-13;「設為可編輯」與「還原」的畫面錄於 2026-11-14。/home/learner/isvn_demo/…這類路徑屬於那些錄製環境。 - fcf6302 版本不適合多個帳號共用一個專案。跨伺服器共用、高儲存量與舊 Pool 遷移不在本教學的適用範圍;第 7、8 章的 Pool 圖僅說明概念。