Inspect, rename and review SystemVerilog locally

Index saved SystemVerilog, find and rename a symbol through a reviewed plan, review immediate assertions and read the reference catalogs.

Use Altifigence CLI 0.1.9 on Linux to inspect saved SystemVerilog files in a local project, rename a symbol through a reviewed plan, review immediate assertions and read the SVA and constrained-random reference catalogs.

Index a saved source file

Use a fresh local project for this example, with one saved SystemVerilog file. Run the commands as your ordinary user.

set -euo pipefail
WORK="$(mktemp -d)"
mkdir -p "$WORK/project/rtl"
PROJECT="$(cd "$WORK/project" && pwd -P)"
cat > "$PROJECT/rtl/top.sv" <<'SV'
module child(input logic a, output logic y);
  assign y = a;
endmodule

module top(input logic a, output logic y);
  child u_child(.a(a), .y(y));
endmodule
SV
alti sv frontend index --project "$PROJECT" rtl/top.sv > "$WORK/index.json"
jq '{schemaVersion, files, modules: [.modules[].name], diagnostics}' "$WORK/index.json"

Require exit status 0. The index has schemaVersion sv-index.v1. Each entry in files has path, bytes and lineCount. Each module has its ports, params, instances and loc.

Find a definition and its references

Positions use 1-based line and column numbers. Line 1, column 8 is the name child.

alti sv frontend definition --project "$PROJECT" rtl/top.sv 1 8 \
  > "$WORK/definition.json"
alti sv frontend references --project "$PROJECT" rtl/top.sv 1 8 \
  > "$WORK/references.json"
jq '{schemaVersion, definition}' "$WORK/definition.json"
jq '{schemaVersion, references: [.references[].loc]}' "$WORK/references.json"

The definition result has schemaVersion sv-definition.v1 with query, symbol and definition. The references result has schemaVersion sv-references.v1 and a references list. Each located symbol has name, kind and a loc with path, line and column. To resolve symbols across files, list the other saved files after the column.

Rename with a reviewed plan

Create a plan that renames child to leaf. Creating the plan does not change files.

alti sv frontend rename-plan --project "$PROJECT" rtl/top.sv 1 8 leaf \
  > "$WORK/rename.plan.json"
jq '{schemaVersion, edits}' "$WORK/rename.plan.json"
PLAN_SHA256="$(jq -r .canonicalSha256 "$WORK/rename.plan.json")"

The plan has schemaVersion sv-rename-plan.v1. Each edit has path, line, column, length and replacement. Review every edit, then apply the same rename with the reviewed canonicalSha256:

alti sv frontend rename-apply --project "$PROJECT" rtl/top.sv 1 8 leaf \
  "$PLAN_SHA256" > "$WORK/rename.receipt.json"
jq '{schemaVersion, reviewedPlanSha256, appliedCurrentRequest}' \
  "$WORK/rename.receipt.json"

Require exit status 0 and appliedCurrentRequest equal to true. The receipt has schemaVersion sv-rename-apply.v1. The apply step builds the plan again from the saved SystemVerilog files in the project and writes the edits only when that plan's digest equals the reviewed digest. Create the plan over all saved SystemVerilog files of the project so both plans cover the same sources.

Review immediate assertions

The review reads one SystemVerilog source from stdin and returns a structured assertion review.

cat > "$WORK/check.sv" <<'SV'
module check(input logic [3:0] count);
  always_comb begin
    assert (count != 4'hf) else $error("count overflow");
  end
endmodule
SV
alti sv review immediate < "$WORK/check.sv" > "$WORK/immediate.json"
jq . "$WORK/immediate.json"

Require exit status 0 and read the review result. alti sv review interprocess reads its source the same way and reviews inter-process synchronization.

Read the reference catalogs

List SVA catalog entries and show one of them:

alti sv library sva list --limit 5 > "$WORK/sva.json"
jq '{schemaVersion, totalMatches, truncated, ids: [.entries[].stableId]}' "$WORK/sva.json"
ENTRY_ID="$(jq -r '.entries[0].stableId' "$WORK/sva.json")"
alti sv library sva show "$ENTRY_ID"

Both catalogs have schemaVersion altifigence.sv-library-catalog.v1. A list has resultLimit, totalAvailable, totalMatches, truncated and entries. Each entry has stableId, category, name, summary, tags and attributes. For --category, use checker with sva, or item or control with constrained-random. Narrow a list with --filter text of 1 to 128 bytes, and with --limit from 1 to 64. The default limit is 64. Use alti sv library constrained-random list and show the same way.

Read the compiled UVM bridge contract with these queries. alti sv uvm readiness returns the signed fixed-component readiness receipt without loading or running the component.

alti sv uvm capabilities
alti sv uvm readiness

Recover from errors

If a query reports no symbol at rtl/top.sv:2:1, that position is not on a symbol name. Take a line and column from a loc in the index and run the query again.

If rename-apply reports reviewed SV rename plan changed: expected followed by two digests, the saved sources no longer produce the reviewed plan. Run rename-plan again, review the new edits and apply with the new canonicalSha256.

If rename-apply reports SV rename apply requires --project <absolute-workspace>, add --project "$PROJECT" and run it again.

If show reports that the SV library entry was not found, the command exits with status 2. Copy a stableId from a list result and run show again.

Inspect symbols, hover details and completions

After applying the rename, use the same saved rtl/top.sv fixture to inspect its symbols. symbols returns module symbols, references and resolution counts. symbols-v2 also includes constant values, widths and generate expansion.

alti sv frontend symbols --project "$PROJECT" rtl/top.sv > "$WORK/symbols.json"
alti sv frontend symbols-v2 --project "$PROJECT" rtl/top.sv > "$WORK/symbols-v2.json"
jq '{schemaVersion, modules: [.modules[].name]}' "$WORK/symbols.json"
jq '{schemaVersion, modules: [.modules[].name]}' "$WORK/symbols-v2.json"

{"schemaVersion":"sv-symbols.v1","modules":["leaf","top"]}
{"schemaVersion":"sv-symbols.v2","modules":["leaf","top"]}

Use hover at a symbol location and complete with a name prefix. Hover includes the queried symbol and its definition; completion items include label, kind and loc.

alti sv frontend hover --project "$PROJECT" rtl/top.sv 1 8 > "$WORK/hover.json"
alti sv frontend complete --project "$PROJECT" lea rtl/top.sv > "$WORK/complete.json"
jq '{schemaVersion}' "$WORK/hover.json"
jq '{schemaVersion, labels: ([.items[].label] | unique)}' "$WORK/complete.json"

{"schemaVersion":"sv-hover.v1"}
{"schemaVersion":"sv-completion.v1","labels":["leaf"]}

Require exit status 0 before using the returned locations. For no symbol at a location, choose a loc from a returned symbol and retry hover. If complete reports an invalid prefix, use 1 to 128 bytes, such as lea.

Inspect the UVM environment and ABI contracts

Save the environment and ABI reports alongside the capability and readiness reports. environment describes signed component discovery policy. abi lists the compiled C interface, return codes, export names and parameter types.

alti sv uvm environment > "$WORK/uvm-environment.json"
alti sv uvm abi > "$WORK/uvm-abi.json"
jq '{schemaVersion, authority: .discovery.authority}' "$WORK/uvm-environment.json"
jq '{schemaVersion, callingConvention}' "$WORK/uvm-abi.json"

{"schemaVersion":"altifigence.uvm-bridge-environment.v1","authority":"host-owned-signed-component-discovery"}
{"schemaVersion":"altifigence.uvm-bridge-abi.v1","callingConvention":"C"}

Review UVM simulation request contracts

Query the simulation contract and readiness receipts, then validate a saved-source descriptor and its resource ceilings with admit. The example below uses the saved fixture as a one-source descriptor. Record the returned requestSha256 with the descriptor you reviewed.

alti sv uvm simulation capabilities > "$WORK/uvm-simulation-capabilities.json"
alti sv uvm simulation readiness > "$WORK/uvm-simulation-readiness.json"
jq '{schema, admissionAvailable, preflightAvailable}' "$WORK/uvm-simulation-capabilities.json"

{"schema":"altifigence.uvm-simulation-capabilities.v1","admissionAvailable":true,"preflightAvailable":true}

BUNDLE_SHA256="$(sha256sum "$PROJECT/rtl/top.sv" | cut -d ' ' -f 1)"
SOURCE_BYTES="$(wc -c < "$PROJECT/rtl/top.sv")"
alti sv uvm simulation admit --bundle-id demo --bundle-sha256 "$BUNDLE_SHA256" \
  --source-count 1 --source-bytes "$SOURCE_BYTES" \
  --test smoke --top top --clock clk --period-ps 1000 --cycles 10 \
  --max-wall-time-ms 1000 --max-cpu-cores 1 \
  --max-memory-bytes 1048576 --max-artifact-bytes 1048576 > "$WORK/uvm-admission.json"
jq '{schema, admitted, sourceCount, cycleCount}' "$WORK/uvm-admission.json"

{"schema":"altifigence.uvm-simulation-admission.v1","admitted":true,"sourceCount":1,"cycleCount":10}

preflight also validates an attempt ID and the time remaining within its wall-time ceiling. It returns the admission, component and DPI readiness, and resource-authority assessment for that attempt. Save the complete receipt for review.

alti sv uvm simulation preflight --bundle-id demo --bundle-sha256 "$BUNDLE_SHA256" \
  --source-count 1 --source-bytes "$SOURCE_BYTES" \
  --test smoke --top top --clock clk --period-ps 1000 --cycles 10 \
  --max-wall-time-ms 1000 --max-cpu-cores 1 \
  --max-memory-bytes 1048576 --max-artifact-bytes 1048576 \
  --attempt-id review-1 --observed-at-unix-ms 1000 --deadline-unix-ms 1500 \
  > "$WORK/uvm-preflight.json"
jq '{schema, admitted: .admission.admitted}' "$WORK/uvm-preflight.json"

{"schema":"altifigence.uvm-simulation-preflight.v1","admitted":true}

For source bundle digest must be lowercase SHA-256, copy the 64-digit digest unchanged. For resource ceilings are outside v1 bounds, query capabilities and choose positive values within its maxima. For deadline is absent or exceeds the admitted wall-time ceiling, set a positive deadline within max-wall-time-ms of the observation time and repeat preflight. The attempt timestamps above are illustrative values.

CLI engine commands