Install and run the pinned upstream XLS toolchain

Use Altifigence CLI 0.1.9 on Linux x86_64 to install one pinned upstream XLS toolchain release and run multi-file DSLX projects with it. The CLI verifies the release before every use.

Install the toolchain

Choose a new installation folder and a new configuration file under an existing folder. Both paths must be absolute and must not exist yet. Run the commands as your ordinary user.

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"

Require exit status 0. The selected result fields are:

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

install downloads the release archive xls-v0.0.0-10617-geb3151083-linux-x64.tar.gz over HTTPS with /usr/bin/curl and checks its SHA-256 de9a5570f406d0865a159602180de1ac70e04cd51cfb808ead1f87549e56a4be. It extracts the archive with /usr/bin/tar and /usr/bin/gzip, then checks the SHA-256 of each of the five tools and the standard library inventory. It keeps the release licence files and writes the configuration only after these checks pass. The installation folder is private to your user. The archive can be up to 134217728 bytes and the staged installation up to 536870912 bytes, and child processes share a 300-second deadline.

To install from a copy of the same archive that you already have, add --archive with its absolute path. The same SHA-256 check applies.

Read the coverage

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 is a query. It verifies the installed tools against the pinned release again and reports what you can request. For the installation above, the selected fields are:

{
  "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 lists the release, source revision, archive SHA-256, tool SHA-256 values and standard library SHA-256. limits gives the request, source, file, output, result, time and pipeline bounds.

Run module tests

A request carries every module in files, keyed by a relative path ending in .x. entry names the module to run. Save this request as 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"
  }
}

Create a work folder for the run, then run the request:

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

After exit status 0, the selected result fields are:

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

eval runs the test functions and test procs of the entry module. Each run uses a new private folder inside the work folder and removes it afterwards. processes records each tool with its SHA-256, arguments, exit code and output. Use operation check to parse and type-check the entry module and its imports. Keep a request within 2097152 bytes, up to 64 files and 1048576 bytes of source.

Generate SystemVerilog

Save this request as codegen.json. top names the DSLX function to generate:

{
  "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

After exit status 0, the artifact names are:

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

Each artifact has sha256, bytes and text. This request generates the module xls_top with reset rst. Choose 1 to 64 pipeline stages, or omit pipeline_stages for combinational SystemVerilog. Use operation convert to stop after converted.ir and interface.textproto, or optimize to stop after optimized.ir.

Correct an install or run

When the XLS engine returns an error, the command exits with status 2 and writes an altifigence.xls.error.v1 object to standard output. The CLI reports an empty or oversized request or a relative host path on standard error with the prefix error: and exits with status 1. For an XLS engine error, read its code and message:

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

For install-conflict: installation destination must not exist or install-conflict: toolchain config must not exist, choose new paths. A failed install removes the folder and configuration it created.

For toolchain-mismatch: archive SHA256 does not match pinned official release, pass the original release archive with --archive, or omit --archive to download it.

For toolchain-mismatch: configuration does not identify the supported pinned XLS release, pass the configuration file that install wrote.

For io-error: work root does not exist, create the work folder and run again.

For no-tests: upstream eval requires at least one executed test or test proc, add a #[test] function to the entry module.

For invalid-request: check/eval operate on the entry module, not a selected top, remove top. For invalid-request: DSLX optimize/codegen require a concrete top, add top.

For upstream-failed, the message names the tool and starts its diagnostic output. Correct the module at the reported location and run again.

CLI engine commands