跳至主要内容

製作 Package

TUT03 · Terminux · 繁體中文影片

影片​

在 YouTube 開啟影片

指南​

TUT03 — 為你的 EDA Tool 開發 Terminux Package

本 Guide 示範如何自己撰寫 Package,把 EDA Tool 整合到 Terminux。示範工具是 Yosys,一套開源的 RTL Synthesis Tool。在 Design Flow 中,它和 Cadence Genus、Synopsys Design Compiler 屬於同一大類工具,但各家的功能、指令與 Log 都不同,並不是一對一的對應。

本課實際執行的內容: 只有 Yosys 的 hierarchy check(hierarchy -check):Top Module 引用的 RTL Module 是否都已載入。這是預檢查,不是合成、時序分析或 sign-off。

名詞說明。

  • Package:你自己的 Python handler 加上 manifest。對應的工具指令結束後,Terminux 會呼叫它解讀結果,並回報一行訊息。
  • when.tools:manifest 中指定要跟隨哪個工具執行的欄位。
  • after handler:讀取證據的 Python 函式(本例讀 -l 指定的 log 與結束碼)。
  • PhaseResult:handler 的回傳值:ok、warn、fail 或 noop,加上一段訊息。
  • 離線案例(package-tests):預先準備的 log,用來在安裝前驗證 handler;通過不代表你的 RTL 沒問題。
  • DISPATCH_READY:代表設定就緒;只有真實執行才能證明整合有效。

前置條件

  • 已安裝 Terminux,且在 Terminux 終端機中,terminux-tool、terminux-package-new 等命令在 PATH 上。
  • 已安裝可用的 Yosys,且可以從 PATH 找到。安裝 Yosys 不在本課範圍。本課使用 Yosys 0.68+post(git a5af9d69)測試,其他版本未測試。請見下方「取得 Yosys」。
  • 在 Terminux 終端機使用 bash。本課以 bash 錄製;tcsh 的說明未經實測。
  • 已把教材檔案解開成 ~/TUT03_learner_assets/(見下方〈教材檔案〉)。
  • 選用(第 1A 節與第 7 節步驟 3):Terminux AI 已設定好模型供應者。設定方式不在本課範圍;其餘步驟不需要 AI。
  • 指令沿用示範錄影中的路徑(~/tut03/...、~/TUT03_learner_assets/...)。如果你的檔案或 Yosys 安裝在其他位置,請換成自己的路徑。

終端機語言: Terminux 終端機的語言設定預設是 繁體中文(zh-Hant)。切換方式:在終端機內按右鍵 → Language → English(影片中有實際操作)。本課用到的命令與 Package 訊息,不論哪種設定都是英文:我們在兩種設定下都跑過 第 1–5 節的全部命令,輸出相同。

取得 Yosys(前置條件,不屬於本課)

本課假設 Yosys 已由你或 CAD/工具管理員安裝好。請用第 0 節最前面的命令確認。可能的來源如下, 都沒有與本課一起驗證 :公司內部的工具安裝;YosysHQ OSS CAD Suite 的二進位發行版;從 YosysHQ 原始碼自行建置;Linux 發行版套件(Ubuntu 24.04 的 apt 提供較舊的 0.33 版,且需要管理員權限)。不同版本的 log 文字可能不同;本 Package 讀取的是 ERROR: 、 Top module: 、 Used module: 與 End of script. 這幾種行。

教材檔案

教材檔案是一個壓縮檔 TUT03_learner_assets.tar.gz。在家目錄解開:tar -xzf TUT03_learner_assets.tar.gz -C ~。解開後的結構如下(第 0 節會用 ASSETS.sha256 檢查):

TUT03_learner_assets/
  ASSETS.sha256
  packages/
    yosys_hier_check/
      README.md
      __init__.py
      after.py
      package-tests/
        hierarchy_ok.yaml
        incomplete_log_warns.yaml
        log_missing_warns.yaml
        log_outside_workspace_warns.yaml
        missing_module_fails.yaml
        no_log_flag_warns.yaml
        non_wrapper_source_ignored.yaml
      package.yaml
  rtl/
    adder.v
    hier_check.ys
    top.v
Guide 與影片對照

影片依相同順序分成 S01–S07 幾個段落,沒有章節連結;可用下表找到對應的部分。

影片 內容 Guide
S01 Package 的用途 開頭說明
S02 現有 Package 的組成(選用) 1
S03 寫 handler 前先問 Terminux AI 1A
S04 語言、確認 Yosys、登記、建立、驗證、安裝、啟用 0、2–5
S05 執行 Yosys 並判讀結果 6
S06 弄壞、問 AI、修好 7
S07 回顧與移植到其他工具 9
— 清除(僅 Guide,影片未拍攝) 8

0. 開始之前

目的: 確認 Yosys 與 Terminux 命令都已就緒,並設定終端機語言。

在哪裡操作: Terminux 終端機(GUI 視窗)、bash、任何資料夾。

  1. 確認找得到 Yosys,以及它的版本:
command -v yosys
yosys -V

command -v yosys 會印出你的 Yosys 執行檔路徑(每台機器不同)。yosys -V 印出版本:

預期輸出(節錄) — yosys -V:

Yosys 0.68+post (git sha1 a5af9d690a43744bf6b2cc3dea2717c16b54621c, Release, GNU /usr/bin/g++ 13.3.0)
  1. 查看 Terminux 的工具清單。全新的設定檔、尚未登記任何工具時,最後一行是 No user tools registered.;如果之前登記過工具,則會列出那些工具。
terminux-tool list

預期輸出(節錄) — terminux-tool list:

No user tools registered.
  1. 確認教材檔案完整:
cd ~/TUT03_learner_assets && sha256sum -c ASSETS.sha256

每個檔案印出一行,結尾都是 OK(共 14 個檔案)。

  1. 把教材 RTL 複製到工作資料夾。這一步假設是全新開始:如果 ~/tut03/rtl 已經存在,cp -r 會在裡面再放一份(~/tut03/rtl/rtl)。遇到這種情況,請先自行改名或移走舊資料夾;本 Guide 不會替你刪除檔案。
mkdir -p ~/tut03 && cp -r ~/TUT03_learner_assets/rtl ~/tut03/rtl

這個命令不會印出任何內容。

圖: 第一次啟動時的 Language 子選單:預設勾選繁體中文。

圖: 第一次啟動時的 Language 子選單:預設勾選繁體中文。

圖: 選擇 English 之後,選單顯示 English 已勾選。

圖: 選擇 English 之後,選單顯示 English 已勾選。

成功確認: yosys -V 印出版本,且 sha256sum -c 的每一行結尾都是 OK。如果 command -v yosys 沒有印出任何內容,請先停下:安裝 Yosys 或修正 PATH。

1. 從現有的 Package 學習模式(選用)

目的: 選用的旁支:可以略過本節,直接進行第 1A 或第 2 節;第 3 節會在你自己的 Package 裡看到相同的部分。以內建範例 icc2_shell_dqe 看懂每個 after-phase Package 都有的三個部分。它標示為 FAKE:依假工具撰寫,只用來參考結構。

在哪裡操作: Terminux 終端機、bash。前兩行請在同一個 session 執行。

  1. 把範例複製到你自己的資料夾:
TX_PY=$(head -1 "$(command -v terminux-package-new)" | cut -c3-)
mkdir -p ~/tut03/reference && cp -r "$("$TX_PY" -c 'import os, terminux_engine.packages as p; print(os.path.dirname(p.__file__))')/icc2_shell_dqe" ~/tut03/reference/
cd ~/tut03/reference/icc2_shell_dqe

輔助命令: 本 Guide 撰寫的輔助命令:找出執行 Terminux 命令的 Python。它假設這些命令是從 Terminux Python wheel 安裝的(與錄影示範相同);其他安裝方式未經測試。如果在你的環境無法使用,可略過步驟 1–3:第 3 節會在你自己的 Package 裡看到相同的部分(package.yaml、after.py)。

輔助命令: 本 Guide 撰寫的輔助命令:把內建範例複製到你自己的資料夾再閱讀。請在上一行的同一個 bash session 執行。

這兩行都不會印出任何內容。

  1. 閱讀 manifest。找 when: tools:(這個 Package 處理哪個工具的執行)與 phases: after: after.run(工具結束後 Terminux 呼叫的函式)。按 Ctrl+X 離開 nano。
nano -v package.yaml
  1. 閱讀入口函式 run(ctx):它先確認是哪個工具,最後回傳 PhaseResult(ok、warn、fail 或 noop)。
nano -v +48 after.py

圖: icc2_shell_dqe/package.yaml(FAKE 範例)。

圖: icc2_shell_dqe/package.yaml(FAKE 範例)。

成功確認: 你能指出 manifest、after handler 與它的結果。產品沒有附上這個範例的測試案例,所以本課在自己的 Package 中示範測試案例(第 3 節)。

1A. 寫 handler 前先問 Terminux AI(選用)

目的: 請 Terminux AI 整理一份檢查清單,再逐項對照真實檔案,確認後才採用。

在哪裡操作: Terminux 終端機,任何資料夾。需要已設定模型供應者的 Terminux AI(見前置條件)。

  1. 在提示字元輸入 @@、一個空格和問題,再按 Enter。以下是錄影中實際使用的問題(英文原文):

    @@ I am building a Terminux Python after-phase Package for a Yosys RTL hierarchy check. Which Package parts are reusable, which parts must be adapted to the Yosys command and log, and which checks should I test before installing it?
    
  2. 回答會出現在視窗上方的 NotificationBar(錄影中約在按 Enter 後 25 秒),並留在通知列的歷史紀錄裡。不同模型、不同 Session 的回答都不一樣,不要期待相同的文字。在新的 Session 裡,AI 可能看不到你的檔案或 Log;錄影中的回答自己就這樣說明:

    I can't tell you what your existing package looks like, because this turn has no tool access and the context above contains no package source, no Yosys command line, and no log sample.

    (中譯)我無法告訴你你現有的 Package 長什麼樣子,因為這一輪沒有工具權限,上面的內容也沒有 Package 原始碼、Yosys 指令或 Log 範例。

  3. 錄影回答中,本課採用的建議(英文原文):

    Your parser must key on Yosys's actual strings, not on a generic "error" regex.

    (中譯)Parser 必須依據 Yosys 實際輸出的字串判斷,而不是用通用的「error」正規表示式。

    Clean design, correct top → expect pass, exit 0, zero unresolved modules.

    (中譯)正常設計、正確的 top → 預期通過、exit 0、沒有未解析的 module。

    Deliberately missing submodule → expect fail with the specific missing module named in your output.

    (中譯)刻意缺少子模組 → 預期 fail,並在輸出中指名是哪一個 module 缺少。

  4. 採用之前,逐項對照真實檔案:

    建議 對照哪裡 結果
    依 Yosys 自己的 Log 字串判斷 after.py 第 25–27 行(ERROR:、Top module:、Used module:)與第 97 行(End of script.) 相符
    正常設計 → 通過 package-tests/hierarchy_ok.yaml 預期 ok 相符
    缺少子模組 → fail 並指名 module package-tests/missing_module_fails.yaml 預期 fail,訊息含 \adder 相符
    Corner、Metric、Lineage artifact(回答中也有提到) package.yaml 只有 when.tools 與 phases.after 不適用

成功確認: 每一項採用的建議,都能指出對應的檔案行號或測試案例。

2. 把 Yosys 登記為你的工具

目的: 告訴 Terminux yosys 是你的工具。它會在你自己的 ~/.terminux/bin 放一個小 wrapper 在 Yosys 前面;不需要管理員權限,內建工具清單也不會變動。

在哪裡操作: Terminux 終端機、bash。

cd ~/tut03/rtl
terminux-tool register yosys

預期輸出(節錄) — terminux-tool register yosys:

Registered user tool yosys (executables: yosys)
  ...
  wrapper link yosys: CREATED
Not active yet: run `terminux-package-status --activate` to load it into the running daemon.

成功確認: 看到 wrapper link yosys: CREATED。此時尚未啟用,第 5 節才會啟用。

3. 建立 Package 並加入 handler

目的: 從官方 scaffold 開始,再把它的 placeholder handler 換成教材 handler,並加入 7 個測試案例。

在哪裡操作: Terminux 終端機、bash。

  1. 建立 Package 骨架:
mkdir -p ~/tut03/packages
terminux-package-new yosys_hier_check --root ~/tut03/packages --tool yosys

預期輸出(節錄) — terminux-package-new yosys_hier_check --root ~/tut03/packages --tool yosys:

Package Scaffold v1 — status=CREATED package_id=yosys_hier_check
  + __init__.py
  + package.yaml
  + after.py
  + README.md
validation: 0 error(s), 0 warning(s)
  1. 產生的 package.yaml 已經包含 when: tools: [yosys] 與 phases: after: after.run。產生的 after.py 只是 placeholder,一律回傳 noop:

    產生的 package.yaml(與教材中的檔案相同,共 13 行):

    完整檔案 package.yaml(共 13 行)。

    package:
      id: yosys_hier_check
      version: 0.1.0
      api: terminux.package.v1
    
    schema: 1
    
    when:
      tools:
        - yosys
    
    phases:
      after: after.run
    
cd ~/tut03/packages/yosys_hier_check
nano -v after.py
  1. 換成已備妥的教材 handler,並加入測試案例。(影片展示的是備妥的程式碼;完整檔案在 ~/TUT03_learner_assets/packages/yosys_hier_check/after.py,共 109 行。)
cp ~/TUT03_learner_assets/packages/yosys_hier_check/after.py ~/tut03/packages/yosys_hier_check/after.py
cp -r ~/TUT03_learner_assets/packages/yosys_hier_check/package-tests ~/tut03/packages/yosys_hier_check/
ls package-tests

ls package-tests 列出七個案例:hierarchy_ok.yaml、incomplete_log_warns.yaml、log_missing_warns.yaml、log_outside_workspace_warns.yaml、missing_module_fails.yaml、no_log_flag_warns.yaml、non_wrapper_source_ignored.yaml。如果重做這一步,cp -r 會把新的一份放進既有資料夾裡(package-tests/package-tests);請先自行改名或移走舊資料夾。

  1. 閱讀 handler 的判斷部分(第 79–109 行):沒有 -l log → warn;讀不到 log → warn;有 ERROR: 行 → fail,並附上 log 行號;結束碼非 0 或沒有 End of script. → warn;其餘 → ok,並列出 top module 與找到的 submodule。不是 wrapper 送來的事件會回傳 noop(第 75 行)。
nano -v +97 after.py
  1. handler 的結構。以下節錄都是 after.py 的真實程式行,每段都標出行號範圍。它們不是完整檔案;完整的 handler 是 ~/TUT03_learner_assets/packages/yosys_hier_check/after.py。

    從 Terminux 匯入的型別,以及它要找的 Yosys Log 字串:

    節錄自 after.py 第 20–27 行(不是完整檔案)。

    from terminux_engine.package_runtime.context import PackageContext
    from terminux_engine.package_runtime.result import NotificationRequest, PhaseResult
    
    MAX_LOG_BYTES = 1_000_000
    _LOG_FLAGS = ("-l", "--logfile", "-L", "--line-buffered-logfile")
    _ERROR_RE = re.compile(r"^ERROR:\s*(.+)$")
    _TOP_RE = re.compile(r"^Top module:\s+\\?(\S+)")
    _USED_RE = re.compile(r"^Used module:\s+\\?(\S+)")
    

    進入點。yosys 結束後 Terminux 呼叫 run(ctx);不是經由 wrapper 送來的事件一律略過:

    節錄自 after.py 第 73–77 行(不是完整檔案)。

    def run(ctx: PackageContext) -> PhaseResult:
        event = ctx.event
        if event.source != "wrapper":
            return PhaseResult(status="noop", message=f"ignored event from source={event.source!r}")
        facts: dict = {"exit_code": event.exit_code, "command": event.command}
    

    找出 -l 後面的 Log 檔並讀取。_read_log(第 41–60 行)只讀工作資料夾內、1 MB 以下的一般檔案:

    節錄自 after.py 第 79–86 行(不是完整檔案)。

        name = _log_name(list(event.argv))
        if name is None:
            return _result("warn", "Yosys ran without a log file; rerun with -l <file> so the hierarchy "
                           "result can be checked", facts)
        facts["log"] = name
        text, problem = _read_log(event.cwd, name)
        if text is None:
            return _result("warn", f"cannot check the hierarchy: {problem}", facts)
    

    有 ERROR: 行就是 fail,並附上 Log 行號:

    節錄自 after.py 第 88–95 行(不是完整檔案)。

        lines = text.splitlines()
        errors = [(number, match.group(1)) for number, line in enumerate(lines, 1)
                  if (match := _ERROR_RE.match(line))]
        facts["error_count"] = len(errors)
        if errors:
            number, first = errors[0]
            return _result("fail", f"Yosys hierarchy check FAILED (exit {event.exit_code}): {first} "
                           f"[{name}:{number}]", facts)
    

    結束碼非 0,或 Log 沒有 End of script. → warn;其餘 → ok,並列出 top module 與找到的 submodule:

    節錄自 after.py 第 97–109 行(不是完整檔案)。

        finished = any(line.startswith("End of script.") for line in lines)
        if event.exit_code != 0 or not finished:
            return _result("warn", f"Yosys exit {event.exit_code} without an ERROR line in {name}; "
                           "the log may be incomplete", facts)
    
        top = next((m.group(1) for line in lines if (m := _TOP_RE.match(line))), None)
        used = sorted({m.group(1) for line in lines if (m := _USED_RE.match(line))})
        if top is None:
            return _result("warn", f"Yosys finished but {name} shows no hierarchy check "
                           "(add: hierarchy -check -top <module>)", facts)
        facts.update(top=top, used_modules=used)
        used_text = ", ".join(used) if used else "none"
        return _result("ok", f"Yosys hierarchy OK: top={top}, submodules found: {used_text} [{name}]", facts)
    

    每個結果都是一個 PhaseResult,附一則通知:ok 顯示為 info,fail 為 error,其餘為 warning:

    節錄自 after.py 第 63–70 行(不是完整檔案)。

    def _result(status: str, message: str, facts: dict) -> PhaseResult:
        level = {"ok": "info", "fail": "error"}.get(status, "warning")
        return PhaseResult(
            status=status,  # type: ignore[arg-type]
            message=message,
            facts=facts,
            notifications=[NotificationRequest(level=level, title="yosys_hier_check", message=message)],
        )
    

圖: after.py 的判斷部分(nano -v +97)。

圖: after.py 的判斷部分(nano -v +97)。

成功確認: ls package-tests 列出七個 .yaml 檔。

4. 驗證並執行離線案例

目的: 檢查 Package 結構,再不執行 Yosys、直接跑 7 個預先準備的案例。

在哪裡操作: Terminux 終端機、bash。

terminux-package-validate --root ~/tut03/packages
terminux-package-doctor --root ~/tut03/packages --run-cases --require-cases

預期輸出(節錄) — terminux-package-validate --root ~/tut03/packages:

Package Contract Validator v1 — 1 package(s) scanned, 0 error(s), 0 warning(s)
VALID

預期輸出(節錄) — terminux-package-doctor --root ~/tut03/packages --run-cases --require-cases:

PASS yosys_hier_check [7 cases, 7 passed]

1 packages: 1 valid, 0 invalid
7 cases: 7 passed, 0 failed
0 warnings
  1. 選擇性:單獨跑一個案例。這個案例預期對真實 Yosys「找不到 module」的 log 回報 fail,所以 PASS 代表 Package 反應正確:
terminux-package-test --root ~/tut03/packages --package yosys_hier_check --case ~/tut03/packages/yosys_hier_check/package-tests/missing_module_fails.yaml

預期輸出(節錄) — terminux-package-test --root ~/tut03/packages --package yosys_hier_check --case ~/tut03/packages/yosys_hier_check/package-tests/missing_module_fails.yaml:

PASS yosys_hier_check::missing_module_fails

圖: 驗證與離線案例:7 個全部通過。

圖: 驗證與離線案例:7 個全部通過。

成功確認: 看到 VALID,接著 7 cases: 7 passed, 0 failed。離線 PASS 不等於 Yosys PASS。

5. 安裝並啟用

目的: 把 Package 的快照複製到 Terminux,並請執行中的 daemon 載入。

在哪裡操作: Terminux 終端機、bash。

terminux-package-install ~/tut03/packages/yosys_hier_check
terminux-package-status --activate

預期輸出(節錄) — terminux-package-install ~/tut03/packages/yosys_hier_check:

Installed user package yosys_hier_check 0.1.0
  ...
WARNING: This Package runs Python under your account in the Terminux daemon; it is not sandboxed. Validation checks Package structure, not whether the code is safe. Install only code you trust.
Not active yet: run `terminux-package-status --activate` to load it into the running daemon.

預期輸出(節錄) — terminux-package-status --activate:

Activation: ACTIVATED
yosys_hier_check 0.1.0
  INSTALLED  yes  ...
  VALID      yes
  LOADED     yes  ...
  STATE      LOADED
  TOOL       yosys origin=user TOOL_REGISTERED yes
  WRAPPER    yosys: WRAPPER_READY (wrapper first on PATH; real executable .../yosys)
  DISPATCH_READY yes (configuration only; not a live run)

圖: 啟用:LOADED、WRAPPER_READY、DISPATCH_READY。

圖: 啟用:LOADED、WRAPPER_READY、DISPATCH_READY。

成功確認: 看到 LOADED yes、TOOL_REGISTERED yes、WRAPPER_READY、DISPATCH_READY yes。DISPATCH_READY 只代表設定就緒;下一節才證明真的會運作。之後若修改 after.py,請加 --replace 重新安裝,再啟用一次。

6. 照常執行 Yosys

目的: 像平常一樣執行 hierarchy 檢查,並閱讀 Package 的結果。

在哪裡操作: Terminux 終端機、bash,位於 ~/tut03/rtl。

cd ~/tut03/rtl
cat hier_check.ys
yosys -s hier_check.ys -l hier_check.log
echo "exit code: $?"

預期輸出(節錄) — cat hier_check.ys:

# Hierarchy preflight: read every RTL file, then check that all instantiated modules exist.
read_verilog top.v
read_verilog adder.v
hierarchy -check -top top

預期輸出(節錄) — yosys -s hier_check.ys -l hier_check.log:

3.2. Analyzing design hierarchy..
Top module:  \top
Used module:     \adder
Removed 0 unused modules.

預期輸出(節錄) — echo "exit code: $?":

exit code: 0

下面這一行不是 Yosys 印出的。約兩秒內,視窗上方的 Terminux NotificationBar 會顯示這次執行的 Package 結果:

[Package yosys_hier_check] Yosys hierarchy OK: top=top, submodules found: adder [hier_check.log]

圖: 上:NotificationBar,最新一則是 OK。下:Yosys 輸出的結尾與 。兩者是同一時刻的畫面。

圖: 上:NotificationBar,最新一則是 OK。下:Yosys 輸出的結尾與 exit code: 0。兩者是同一時刻的畫面。

成功確認: 看到 exit code: 0(bash;tcsh 可用 echo $status,但本教學未實測)。通知列會保留先前的結果當作歷史;最新的結果在清單的最後一行。

7. 弄壞、判讀結果、修好

目的: 看看真實的工具失敗長什麼樣子,並修正正確的地方。

在哪裡操作: Terminux 終端機、bash,位於 ~/tut03/rtl。

  1. 打開 script,刪掉 read_verilog adder.v 這一行(nano:移到該行按 Ctrl+K),存檔(Ctrl+O、Enter)後離開(Ctrl+X):
nano hier_check.ys
  1. 再執行一次同一個指令:
yosys -s hier_check.ys -l hier_check.log
echo "exit code: $?"

預期輸出(節錄) — yosys -s hier_check.ys -l hier_check.log:

2.1. Analyzing design hierarchy..
Top module:  \top
ERROR: Module `\adder' referenced in module `\top' in cell `\u_adder' is not part of the design.

預期輸出(節錄) — echo "exit code: $?":

exit code: 1

Yosys 以上面的 ERROR 停止,exit code 為 1。另外,Terminux NotificationBar 最新的一則是這次執行的 Package 結果,並指向 Log 第 20 行:

[Package yosys_hier_check] Yosys hierarchy check FAILED (exit 1): Module `\adder' referenced in module `\top' in cell `\u_adder' is not part of the design. [hier_check.log:20]
  1. 選用:詢問 Terminux AI 應該先檢查哪裡。以下是錄影中實際使用的問題(英文原文):

    @@ Yosys reports that module \adder referenced by \top is not part of the design. Is this an RTL input or script problem, or a Terminux Package failure? What should I check first, and how can I verify the fix?
    
  2. 閱讀建議,只採用你能驗證的部分。錄影中的回答這樣說(不同模型、不同 Session 的回答都不一樣):

    This is almost certainly an RTL input / script problem, not a Terminux Package failure.

    (中譯)這幾乎可以確定是 RTL 輸入/script 的問題,不是 Terminux Package 的失敗。

    Check the read_verilog / read_systemverilog lines in your script.

    (中譯)檢查 script 裡的 read_verilog/read_systemverilog 這幾行。

    Confirm the reference resolves: run hierarchy -check -top top. A clean pass with no "not part of the design" message means the reference is resolved.

    (中譯)**確認引用已解決:**執行 hierarchy -check -top top。順利通過、沒有「not part of the design」訊息,就表示引用已解決。

    回答的其他部分是針對較大專案的一般建議(例如 ifdef 條件或 library 檔),不適用於這個只有兩個檔案的範例。

  3. 照回答的建議檢查 script:

cat hier_check.ys

預期輸出(節錄) — cat hier_check.ys:

# Hierarchy preflight: read every RTL file, then check that all instantiated modules exist.
read_verilog top.v
hierarchy -check -top top
  1. read_verilog adder.v 這一行不見了。top.v 使用了 adder 這個 module,但只有 adder.v 定義它。少了這個檔案,hierarchy -check 會找到一個從未讀入的 module 引用,所以 Yosys 以 ERROR 停止,exit code 為 1。Package 正常運作:它找到那一行 ERROR:(Log 第 20 行)並回報。要修改的是 Yosys script,不是 Package。(\adder 是 Yosys 表示 module 名稱的寫法。)

    top.v 實例化 adder:

    節錄自 top.v 第 7–11 行(不是完整檔案)。

        adder u_adder (
            .a  (a),
            .b  (b),
            .sum(sum)
        );
    

    只有 adder.v 定義它:

    節錄自 adder.v 第 2 行(不是完整檔案)。

    module adder (
    
  2. 把 read_verilog adder.v 補回(放在 hierarchy -check -top top 之前),存檔後再執行一次。這就是回答建議的驗證方式:階層檢查通過,不再出現「not part of the design」訊息。

nano hier_check.ys
yosys -s hier_check.ys -l hier_check.log
echo "exit code: $?"

預期輸出(節錄) — yosys -s hier_check.ys -l hier_check.log:

3.2. Analyzing design hierarchy..
Top module:  \top
Used module:     \adder
Removed 0 unused modules.

預期輸出(節錄) — echo "exit code: $?":

exit code: 0

NotificationBar 最新的一則:

[Package yosys_hier_check] Yosys hierarchy OK: top=top, submodules found: adder [hier_check.log]

圖: 上:NotificationBar 最新一則,FAILED(exit 1),指向 。下:Yosys 的  與 。兩者是同一時刻的畫面。

圖: 上:NotificationBar 最新一則,FAILED(exit 1),指向 [hier_check.log:20]。下:Yosys 的 ERROR 與 exit code: 1。兩者是同一時刻的畫面。

成功確認: 第 2 次:Yosys ERROR、exit code: 1、最新通知 FAILED … [hier_check.log:20]。第 3 次:Yosys hierarchy 輸出沒有 ERROR、exit code: 0、最新通知 Yosys hierarchy OK。如果問了 AI,你已自己在 script 中確認它的建議。

8. 清理(選擇性)

目的: 移除 Package 與工具登記。之後 yosys 會直接執行,不經過 wrapper。本節只在 Guide 中;影片沒有拍攝。

在哪裡操作: Terminux 終端機、bash。

terminux-package-uninstall yosys_hier_check
terminux-tool unregister yosys
terminux-package-status --activate

成功確認: 之後執行 Yosys 不再出現 Package 結果。

9. 把模式套用到 Genus 或 Design Compiler

目的: 沿用的是開發流程,不是 Yosys 的程式碼。本節內容都沒有實際執行:本課沒有 Genus 或 DC 的 Package,也沒有商用工具的擷取。

在哪裡操作: 你自己的工具環境,依第 2–6 節的步驟。

  1. 先分清楚這個 Package 哪些部分可以沿用:沿用的是結構與開發方法,而不是 Yosys 專用的命令選項、判斷字串或結束碼意義。行號指 after.py:

    部分 在這個 Package 換成其他工具時
    Manifest 結構、api、phases.after: after.run package.yaml 沿用
    when.tools [yosys] 改成你登記的執行檔名稱
    run(ctx) 進入點、只處理 wrapper 事件、回傳 PhaseResult 第 73–77 行 沿用
    安全讀取 Log(限工作資料夾、一般檔案、大小上限) _read_log,第 41–60 行 可沿用的做法,前提是該工具的 Log 是工作資料夾內的一般檔案,且在支援的大小以內;否則要為該工具調整證據的尋找與讀取方式
    結果與通知的輔助函式 _result,第 63–70 行 沿用
    命令列上指定 Log 檔的方式 _LOG_FLAGS(第 24 行)、_log_name(第 30–38 行) 調整:依你的工具文件中的選項
    失敗與成功的判斷字串 ERROR:、Top module:、Used module:(第 25–27 行)、End of script.(第 97 行) 調整:依你的工具的真實 Log
    結束碼的意義 非 0 但沒有 ERROR: → warn(第 97–100 行) 調整:查你的工具文件中的結束碼
    離線案例 7 個以真實 Yosys Log 建立的案例 用你的工具的真實 Log 重新建立

    本表沒有提供 Genus 或 Design Compiler 的指令、選項或 Log 文字:本課都沒有實測。請依你的工具文件與你系統上的真實 Log 決定。

  2. 登記該工具的執行檔名稱(第 2 節),並確認它不是 Terminux 內建工具的名稱。

  3. 決定 handler 要讀哪些證據:指令列指定的 log、報告目錄,或結束碼。每個工具輸出的標記都不同,要為該工具撰寫解析邏輯。

  4. 以該工具的真實 log 撰寫離線案例(成功、你在意的失敗、缺少或不完整的 log),再執行驗證與案例(第 4 節)。

  5. 安裝、啟用,並在 Terminux 終端機以一次真實執行確認(第 5–6 節)。

成功確認: 檢查項目和 Yosys 相同:VALID、離線案例全部通過、DISPATCH_READY yes,以及真實執行後出現一行正確的結果。

故障排除

看到的訊息 意義/處理
執行 Yosys 後沒有通知 請在 Terminux GUI 終端機內執行 Yosys,並確認 terminux-package-status 顯示 DISPATCH_READY yes。
warn … without a log file 在指令加上 -l hier_check.log。
warn … outside the working directory 把 log 寫在執行 Yosys 的資料夾內。
DISPATCH_READY no (TOOL_REGISTRATION_PENDING_ACTIVATION:…) 執行 terminux-package-status --activate。
WRAPPER_NOT_FIRST_ON_PATH、REAL_EXECUTABLE_NOT_FOUND PATH 中 ~/.terminux/bin 必須排在 Yosys 之前,而且 Yosys 必須已安裝。
登記時出現 USER_TOOL_USED_BY_BUILTIN_PACKAGE/USER_TOOL_SHADOWS_BUILTIN 這個名稱屬於 Terminux 內建;請換一個工具名稱。
USER_TOOL_EXECUTABLE_PATH_OCCUPIED ~/.terminux/bin 已經有名為 yosys 的檔案;Terminux 不會覆蓋它。
命令之後出現 [1]+ Done … terminux-notify post_exec … 無害。Terminux 的 bash 整合在每個命令後於背景送出通知,bash 只是回報該工作已結束。屬已知的外觀問題。
tcsh 登記後馬上找不到命令 執行一次 rehash。(未在 Terminux GUI 中測試。)

限制

  • 檔名與參數不可包含空白或引號。
  • Package 讀取的是 -l 指定的 log 檔,不是終端機畫面的輸出。
  • 你的 Package 是以你的帳號在 Terminux daemon 內執行的 Python,沒有 sandbox。只安裝你信任的程式碼。
  • 離線案例全部通過(7 cases: 7 passed)代表 Package 對這些預先準備的 log 反應正確;不代表你的 RTL 沒問題,也不是一次真實執行。

教材檔案與授權

本課教材檔案不授予再散布權利。icc2_shell_dqe 範例標示為 FAKE,並非真實 IC Compiler II。

適用版本​

相關文件​