Check, evaluate and generate RTL with native XLS

Use Altifigence CLI 0.1.9 on Linux to work with inline DSLX and XLS IR functions. Start with alti xls capabilities to read the installed runner's supported operations. These examples select the CPU backend.

Evaluate a function

Save this request as eval.json. Input values follow the function's parameter order.

{
  "schema": "altifigence.xls.operation-request.v1",
  "operation": "eval",
  "input_kind": "dslx",
  "source": "fn compute(x: u8, y: u8) -> u8 { x + y }",
  "top": "compute",
  "backend": "cpu",
  "vectors": [
    [
      "255",
      "1"
    ],
    [
      "0x10",
      "0b11"
    ]
  ]
}

alti xls eval --request eval.json

The result has status "succeeded" and these outputs:

["bits[8]:0x0","bits[8]:0x13"]

The first sum wraps to the function's 8-bit width. The result includes the request, parameter widths and source and request digests. Native requests accept 1–64-bit functions and up to 256 vectors. Keep inline source within 8192 bytes and the request within 16384 bytes.

Check and optimize

Copy eval.json to check.json. Set operation to "check" and vectors to []. Save a second copy as optimize.json with operation "optimize" and vectors [].

alti xls check --request check.json
alti xls optimize --request optimize.json > optimized.json

Check returns the parsed function information. Optimize folds constants and removes unused pure nodes. Read compilation.ir and compilation.ir_top for the optimized IR and entry point. To evaluate it, put those values in a new request with input_kind "xls-ir".

Generate SystemVerilog

Save this request as codegen.json:

{
  "schema": "altifigence.xls.operation-request.v1",
  "operation": "codegen",
  "input_kind": "dslx",
  "source": "fn compute(x: u8, y: u8) -> u8 { x + y }",
  "top": "compute",
  "backend": "cpu",
  "vectors": [],
  "pipeline": {
    "stages": 2
  }
}

alti xls codegen --request codegen.json > generated.json

Read compilation.system_verilog for the RTL and compilation.rtl_top for its top module. This request produces xls_pipeline with latency_cycles 2 and interface "synchronous-reset-valid-delay". Choose 1 to 16 output register stages. For combinational RTL, omit pipeline; the top module is xls_top.

Run and reopen a local job

Save this complete CPU job request as job.json. Its digest binds the embedded XLS request.

{
  "schema": "altifigence.xls.job-request.v1",
  "job": {
    "schema": "altifigence.engine.job.v1",
    "job_id": "xls-example",
    "operation": {
      "engine_id": "xls-engine",
      "operation_id": "eval",
      "contract_id": "altifigence.xls.operation-request.v1"
    },
    "execution_placement": "local",
    "device_preference": {
      "selection": {
        "mode": "class",
        "value": "cpu"
      },
      "fallback": "deny"
    },
    "resources": {
      "cpu_slots": 1,
      "memory_bytes": 1048576,
      "device_slots": 0,
      "device_memory_bytes": 0,
      "max_wall_time_ms": 30000
    },
    "inputs": [
      {
        "artifact_id": "request",
        "role": "xls-request",
        "artifact_schema": "altifigence.xls.operation-request.v1",
        "uri": "workspace://inputs/request.json",
        "sha256": "fea82ea569518661ed34f31da0a1bd3df7387bd7d4b33e6c171a605bfe547325"
      }
    ],
    "cancellation": {
      "cancellation_id": "xls-example-cancel"
    }
  },
  "request": {
    "schema": "altifigence.xls.operation-request.v1",
    "operation": "eval",
    "input_kind": "dslx",
    "source": "fn compute(x: u8, y: u8) -> u8 { x + y }",
    "top": "compute",
    "backend": "cpu",
    "vectors": [
      [
        "255",
        "1"
      ],
      [
        "0x10",
        "0b11"
      ]
    ]
  }
}

alti xls run --project /home/me/design --request job.json

A successful outcome includes result.status "succeeded", the artifact and its reference in result.outputs. Copy its artifact_id into ARTIFACT_ID to reopen and replay the result:

alti xls artifact show --project /home/me/design ARTIFACT_ID

For a direct operation request, you can also save and list results with:

alti xls artifact store --project /home/me/design --request eval.json
alti xls artifact list --project /home/me/design

Correct a request

For an 8-bit input, "256" produces invalid-input. Replace it with an in-range bit pattern such as "255" and retry. For "command and request operation differ", set the JSON operation to the command you are running. Check, optimize and codegen use vectors []; evaluation contains at least one vector.

For "XLS request digest differs", update the job input SHA-256 to match compact UTF-8 JSON serialization of the embedded request in this field order: schema, operation, input_kind, source, top, backend, vectors, then pipeline when supplied. Run the corrected job again.

A job whose optional deadline_unix_ms has passed returns cancelled with exit code 3. Use a future deadline or omit the optional deadline before retrying.

CLI first success