CLI 首次成功运行

在 CPU 上求值一个小型 XLS 请求,然后可选择验证离线作业封装及源码边界。

概述

先完成 验证 和 安装。下述命令使用已安装的 alti,位于 PREFIX/bin 目录。以普通用户而非 root 身份运行。

运行小型 CPU XLS 求值

此请求将两个 8 位数相加。它使用有界的原生 XLS 引擎,不需要 Google 工具链、GPU 或 Cloud 会话,且结果会明确体现溢出。

Bash
alti capabilities
alti xls eval --request - <<'JSON'
{
  "schema": "altifigence.xls.operation-request.v1",
  "operation": "eval",
  "input_kind": "xls-ir",
  "source": "package demo\ntop fn compute(x: bits[8], y: bits[8]) -> bits[8] { ret sum: bits[8] = add(x, y) }",
  "top": "compute",
  "backend": "cpu",
  "vectors": [["255", "1"], ["0x10", "0b11"]]
}
JSON

要求退出码为 0,且两个向量的引擎结果分别为 bits[8]:0x0 和 bits[8]:0x13。这仅证明这些输入经过求值。更广泛的 DSLX 语言支持请使用独立的 Google XLS 路径。

可选的离线作业预检

以下工作流读取操作清单,并验证作业封装及一个本地源文件。它不读取凭据、不联系服务端、不上传源码、不提交工作,也不运行 RTL 引擎。其回执仅描述本地验证;提交与服务端授权状态仍为 false。

1. 检查随版本交付的操作清单

Bash
alti commands

成功的命令向 stdout 写入一个 JSON 数组,stderr 无输出。每个条目包含 name,description,inputSchema,executes,以及 class。当前公开 CLI 返回 25 个条目。executes 的值描述分派契约;命令仍可能需要本地引擎、账户权限或托管服务。

2. 准备私有本地源码

在当前由用户拥有的工作目录中创建私有工作区:

Bash
ALTI_WORKSPACE="$(mktemp -d -p "$PWD" alti-first-success.XXXXXX)"
mkdir -p "$ALTI_WORKSPACE/inputs/rtl"

将以下无害源码保存为 $ALTI_WORKSPACE/inputs/rtl/top.sv:

SystemVerilog
module top(input logic clock, output logic value);
    always_ff @(posedge clock) value <= ~value;
endmodule

设置源码仅所有者可读写:

Bash
chmod 600 "$ALTI_WORKSPACE/inputs/rtl/top.sv"

预检会拒绝位于工作区外、具有多个硬链接、不属于当前用户,或可由组及其他用户写入的源码。请勿放宽权限检查。

将下述内容保存为 $ALTI_WORKSPACE/job.json:

JSON
{
  "schema": "altifigence.engine.job.v1",
  "job_id": "offline-job-1",
  "operation": {
    "engine_id": "rtl-engine",
    "operation_id": "analyze",
    "contract_id": "rtl-analysis-request.v1"
  },
  "execution_placement": "cloud",
  "device_preference": {
    "selection": { "mode": "class", "value": "cpu" },
    "fallback": "deny"
  },
  "resources": {
    "cpu_slots": 1,
    "memory_bytes": 536870912,
    "device_slots": 0,
    "device_memory_bytes": 0,
    "max_wall_time_ms": 30000
  },
  "inputs": [
    {
      "artifact_id": "rtl-source-bundle",
      "role": "source_bundle",
      "artifact_schema": "rtl-source-bundle.v1",
      "uri": "workspace://inputs/placeholder",
      "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "cancellation": { "cancellation_id": "cancel-offline-job-1" }
}

客户端会在内存中的验证副本中,将占位 URI 和摘要替换为所选工作区相对源码及计算出的 SHA-256。

3. 生成离线回执

Bash
alti --json job validate \
  --job "$ALTI_WORKSPACE/job.json" \
  --workspace-root "$ALTI_WORKSPACE" \
  --source rtl/top.sv

成功结果是在 stdout 上输出一个符合以下契约的 JSON 对象:

字段

必须按此理解

receipt_schema

altifigence.cli.engine-job-preflight.v1

status

client_preflight_valid

submitted

必须为 false

server_authority_verified

必须为 false

job_schema,job_id,operation

本地验证的封装标识

execution_placement

封装中请求的放置位置,不是提交证据

source.workspace_uri

规范化的工作区相对源码 URI

source.sha256,source.size_bytes

本地计算的源码依据

退出状态 0 仅表示客户端预检通过,不表示源码已编译、服务端已接受作业,或任何工作已经运行。

失败输出与退出状态

使用 --json 时,验证失败不会向 stdout 写成功回执,而会向 stderr 写入一个 altifigence.cli.error.v1 对象。例如,格式错误的作业 JSON 会产生 ENGINE_JOB_JSON_INVALID,其中 retryable: false,并以状态 1 退出。

对于清单检查及离线预检:

退出状态

含义

0

清单已输出,或离线客户端预检已通过

1

注册表、I/O、源码边界或作业验证失败

2

命令行语法或参数解析失败

其他 alti 命令使用的退出状态未列在此表中。3 为 CLASS_NOT_ALLOWED;4 表示请求在分派前被拒绝,且此版本中的 alti whoami 和 alti login 均以 4 退出;由引擎支持的命令原样传递引擎自身退出状态,此外无法启动引擎时为 126,未找到引擎时为 127。如果脚本会运行上述两个命令之外的命令,请使用 命令参考 中的完整契约,并默认将每个非零状态视为失败。

保持 stdout 和 stderr 分离,并在解析回执前检查退出状态。显式执行或提交请参阅引擎与 Cloud 命令页面;离线预检不会附带执行或提交。

选择下一步

保留两个向量的 CPU 结果,作为快速安装检查。求值自己的设计时,每次更改一个输入,并保留完整请求和结果。更广泛的语言特性可能需要独立的 Google XLS 路径;CUDA 运行需要显式选择后端及可用设备。

进行图形化 RTL 工作,请继续阅读 DDS 首次 RTL 运行。编写脚本请使用 引擎命令。操作远程已保存文件时,请通过 原生 Cloud 身份验证 登录,并选择正确的组织/项目。