固定された上流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はリリースアーカイブxls-v0.0.0-10617-geb3151083-linux-x64.tar.gzを/usr/bin/curlでHTTPS経由でダウンロードし、その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で選択してください。組み合わせSystemVerilogにする場合はpipeline_stagesを省略します。converted.irとinterface.textprotoで止めるには操作convertを、optimized.irで止めるにはoptimizeを使用してください。

インストールや実行を修正する

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 エンジンコマンド