安装并运行固定版本的上游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使用/usr/bin/curl通过HTTPS下载发行版压缩包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 引擎命令