고정된 업스트림 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은 /usr/bin/curl로 HTTPS를 통해 릴리스 아카이브 xls-v0.0.0-10617-geb3151083-linux-x64.tar.gz를 다운로드하고 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는 요청, 소스, 파일, 출력, 결과, 시간, 파이프라인의 한도를 제공합니다.

모듈 테스트 실행하기

요청은 .x로 끝나는 상대 경로를 키로 하여 모든 모듈을 files에 담습니다. 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, 인수, 종료 코드, 출력과 함께 기록합니다. 엔트리 모듈과 가져오는 모듈을 파싱하고 타입을 검사하려면 operation 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를 생략하세요. operation convert를 사용하면 converted.ir과 interface.textproto 다음에서 멈추고, optimize를 사용하면 optimized.ir 다음에서 멈춥니다.

설치 또는 실행 수정하기

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 엔진 명령어