安裝並執行固定版本的上游XLS工具鏈

安裝固定的上游XLS發行版本，檢查其涵蓋範圍，並執行DSLX模組測試與SystemVerilog產生。

在Linux x86_64上使用Altifigence CLI 0.1.9，安裝一個固定的上游XLS工具鏈發行版本，並用它執行多檔案的DSLX專案。CLI會在每次使用前驗證該發行版本。

安裝工具鏈

請選擇新的安裝資料夾，以及位於既有資料夾下的新設定檔。兩個路徑都必須是絕對路徑，且尚不得存在。請以一般使用者身分執行命令。

set -euo pipefail
TOOLS="$HOME/alti-tools"
mkdir -p "$TOOLS"
alti xls upstream install \
  --destination "$TOOLS/xls-upstream" \
  --toolchain-config "$TOOLS/xls-upstream.json" > "$TOOLS/xls-install.json"
jq '{schema, status, license_files}' "$TOOLS/xls-install.json"

請確認結束狀態為0。所選結果欄位如下：

{
  "schema": "altifigence.xls.upstream-install.v1",
  "status": "succeeded",
  "license_files": [
    "LICENSE",
    "THIRD_PARTY_NOTICES.txt"
  ]
}

install會透過HTTPS以/usr/bin/curl下載發行封存檔xls-v0.0.0-10617-geb3151083-linux-x64.tar.gz，並檢查其SHA-256為de9a5570f406d0865a159602180de1ac70e04cd51cfb808ead1f87549e56a4be。它會以/usr/bin/tar與/usr/bin/gzip解壓縮封存檔，然後檢查五個工具各自的SHA-256以及標準程式庫清單。它會保留發行版本的授權檔案，且僅在這些檢查通過後才寫入設定。安裝資料夾僅供您的使用者使用。封存檔最大可達134217728位元組，暫存的安裝內容最大可達536870912位元組，且子程序共用300秒的期限。

若要從您已有的同一封存檔副本安裝，請加上--archive及其絕對路徑。同樣會套用SHA-256檢查。

讀取涵蓋範圍

CONFIG="$HOME/alti-tools/xls-upstream.json"
alti xls upstream capabilities --toolchain-config "$CONFIG" > "$HOME/alti-tools/xls-capabilities.json"
jq '{schema, operations, input_kinds}' "$HOME/alti-tools/xls-capabilities.json"

capabilities是查詢。它會再次依固定的發行版本驗證已安裝的工具，並回報您可以請求的內容。對於上述安裝，所選欄位如下：

{
  "schema": "altifigence.xls.upstream-capabilities.v1",
  "operations": ["check", "eval", "convert", "optimize", "codegen"],
  "input_kinds": {
    "dslx": ["check", "eval", "convert", "optimize", "codegen"],
    "xls-ir": ["check", "optimize", "codegen"]
  }
}

identity列出發行版本、原始碼修訂、封存檔SHA-256、各工具的SHA-256值與標準程式庫SHA-256。limits提供請求、原始碼、檔案、輸出、結果、時間與管線的上限。

執行模組測試

請求會在files中帶入每個模組，並以.x結尾的相對路徑作為鍵。entry指定要執行的模組。將此請求儲存為tests.json：

{
  "schema": "altifigence.xls.upstream-request.v1",
  "operation": "eval",
  "input_kind": "dslx",
  "entry": "main.x",
  "files": {
    "adder.x": "pub fn add(x: u8, y: u8) -> u8 { x + y }\n",
    "main.x": "import adder;\n\n#[test]\nfn wraps() {\n  assert_eq(adder::add(u8:255, u8:1), u8:0);\n}\n"
  }
}

為此次執行建立工作資料夾，然後執行請求：

mkdir -p "$HOME/alti-work/xls"
alti xls upstream run --toolchain-config "$CONFIG" \
  --work-root "$HOME/alti-work/xls" --request tests.json > tests.result.json
jq '{schema, status, operation, tests_executed}' tests.result.json

結束狀態為0後，所選結果欄位如下：

{
  "schema": "altifigence.xls.upstream-result.v1",
  "status": "succeeded",
  "operation": "eval",
  "tests_executed": 1
}

eval會執行入口模組的測試函式與測試proc。每次執行都會在工作資料夾內使用新的私有資料夾，並在事後移除。processes會記錄每個工具及其SHA-256、引數、結束代碼與輸出。使用操作check可剖析並型別檢查入口模組及其匯入的模組。請求須在2097152位元組以內，最多64個檔案與1048576位元組的原始碼。

產生SystemVerilog

將此請求儲存為codegen.json。top指定要產生的DSLX函式：

{
  "schema": "altifigence.xls.upstream-request.v1",
  "operation": "codegen",
  "input_kind": "dslx",
  "entry": "adder.x",
  "top": "add",
  "pipeline_stages": 2,
  "files": {
    "adder.x": "pub fn add(x: u8, y: u8) -> u8 { x + y }\n"
  }
}

alti xls upstream run --toolchain-config "$CONFIG" \
  --work-root "$HOME/alti-work/xls" --request codegen.json > codegen.result.json
jq '.artifacts | keys' codegen.result.json
jq -r '.artifacts["module.sv"].text' codegen.result.json > module.sv

結束狀態為0後，成品名稱如下：

[
  "converted.ir",
  "interface.textproto",
  "module.sv",
  "optimized.ir",
  "schedule.textproto",
  "signature.textproto"
]

每個成品都有sha256、bytes與text。此請求會產生含重設rst的模組xls_top。請選擇1到64個管線級，或省略pipeline_stages以產生組合邏輯SystemVerilog。使用操作convert可在converted.ir與interface.textproto之後停止，使用optimize則在optimized.ir之後停止。

修正安裝或執行

當XLS引擎傳回錯誤時，命令會以結束狀態2結束，並將altifigence.xls.error.v1物件寫入標準輸出。CLI會將空白或過大的請求，或相對主機路徑，以error:前綴回報至標準錯誤，並以結束狀態1結束。若為XLS引擎錯誤，請讀取其代碼與訊息：

jq -r '.error.code + ": " + .error.message' tests.result.json

若出現install-conflict: installation destination must not exist或install-conflict: toolchain config must not exist，請選擇新的路徑。失敗的安裝會移除其所建立的資料夾與設定。

若出現toolchain-mismatch: archive SHA256 does not match pinned official release，請以--archive傳入原始的發行封存檔，或省略--archive以下載。

若出現toolchain-mismatch: configuration does not identify the supported pinned XLS release，請傳入install所寫入的設定檔。

若出現io-error: work root does not exist，請建立工作資料夾後再次執行。

若出現no-tests: upstream eval requires at least one executed test or test proc，請在入口模組中加入#[test]函式。

若出現invalid-request: check/eval operate on the entry module, not a selected top，請移除top。若出現invalid-request: DSLX optimize/codegen require a concrete top，請加入top。

若出現upstream-failed，訊息會指出工具名稱，並開始顯示該工具的診斷輸出。請在回報的位置修正模組後再次執行。

CLI 引擎指令