Kernel Optimizer
Kernel Optimizer는 Furiosa Optimizer 커널을 위한 빌드, 테스트, 실행, 직접 컴파일 워크플로를 제공합니다. cargo-furiosa-opt 명령이 이러한 워크플로의 진입점입니다.
cargo-furiosa-opt는 Furiosa NPU 컴파일러 툴체인을 위한 cargo의 얇은 래퍼입니다. cargo furiosa-opt는 NPU 빌드이며, 일반 cargo 호출은 CPU에서 빌드하고 실행합니다. 모든 cargo 인수는 그대로 전달되며, 래퍼는 빌드에 필요한 커널을 컴파일합니다.
설치 방법은 설치와 첫 프로그램을 참고하십시오.
첫 명령
CPU에서 바이너리를 실행한 다음, 매핑을 확인하고, 오라클과 값을 비교하고, 스케줄 데이터를 내보내십시오.
cargo run --release --bin gemm
cargo furiosa-opt compile
cargo test --release --bin gemm
cargo furiosa-opt compile gemm_kernel --dump-schedule schedule.json
빠른 시작에서는 이 명령들을 맥락(컨텍스트) 속에서 소개합니다. 이 절에서는 cargo-furiosa-opt 명령의 전체 레퍼런스를 제공합니다. 컴파일, CPU, NPU, 스케줄 결과를 해석하려면 커널 검증을 참고하십시오.
사용법
cargo furiosa-opt <command> [args]
cargo furiosa-opt compile [FILTER]... [options]
첫 번째 형식은 cargo 패스스루입니다. <command>는 임의의 cargo 하위 명령(build, test, run, …)이며, [args]는 변경 없이 cargo에 전달되어 NPU용으로 컴파일됩니다. 두 번째 형식은 커널을 직접 컴파일합니다. 직접 컴파일을 참고하십시오.
일반 cargo build/cargo test/cargo run은 CPU 빌드입니다. 커널이 호스트에서 실행되며, NPU 하드웨어나 SDK가 필요하지 않습니다.
래퍼가 추가하는 기능
일반 cargo와 비교하면, cargo furiosa-opt는 cargo 호출을 전후로 두 가지 작업을 수행합니다.
- NPU를 대상으로 합니다. 커널이 실제 하드웨어로 디스패치됩니다. 물리 NPU와 Furiosa SDK가 필요합니다.
- 필요한 커널을 자동으로 빌드합니다. 빌드 결과 바이너리가 런타임에 로드할 수 있도록 cargo 빌드 전에 필요한
#[device]함수를 컴파일합니다. 자동 커널 빌드를 참고하십시오.
작업 중심의 개요는 빠른 시작: Kernel Optimizer를 참고하십시오.
자동 커널 빌드
cargo furiosa-opt는 cargo에 넘기기 전에 커널 사전 컴파일 단계를 실행합니다. 사전 단계는 필요한 경우에만 실행됩니다. 다음 조건을 모두 만족하지 않으면 이 단계를 건너뜁니다.
- cargo 하위 명령이 코드를 빌드하거나 실행하는 명령(
build,check,test,run,bench,doc)입니다. - 호출이
-h/--help조회가 아닙니다.
사전 단계가 실행되면 빌드에 실제로 필요한 커널만 컴파일합니다.
- cargo의 유닛 그래프를 읽고, 지정한
-p/--package및 워크스페이스 선택을 반영하여 커널 패키지를 찾습니다. 크레이트의Cargo.toml이[package.metadata.furiosa-opt]를 선언하면 그 크레이트는 커널 패키지입니다. - 명령이 테스트, 예제, 바이너리 같은 특정 실행 대상으로 해석되면 컴파일러는 각 대상을 스캔하여 그 대상에서 도달할 수 있는
#[device]함수만 컴파일합니다. - 그렇지 않으면 선택된 패키지의 모든 커널을 컴파일하는 방식으로 대체합니다.
컴파일 결과는 커널별로 캐시되므로 변경되지 않은 커널은 다음 실행 시 다시 컴파일되지 않습니다. 산출물은 출력 디렉터리 아래에 기록됩니다(FURIOSA_OPT_OUT_DIR 참조).
직접 컴파일: cargo furiosa-opt compile
cargo furiosa-opt compile은 cargo 패스스루 없이 #[device] 함수를 직접 컴파일합니다.
# Compile every #[device] function in every kernel package.
cargo furiosa-opt compile
# Compile only the functions matching a filter, in one package.
cargo furiosa-opt compile transpose_simple -p my_kernels
# Compile a single function and dump its schedule for the Schedule Viewer.
cargo furiosa-opt compile transpose::transpose_simple \
--dump-schedule schedule.json
컴파일 파이프라인과 덤프 옵션
아래 덤프 플래그는 각각 커널 컴파일 파이프라인의 서로 다른 지점을 캡처하며, 이 파이프라인은 세 단계로 실행됩니다.
- 1단계 — MIR → vISA.
- 2단계 — vISA → LIR.
- 3단계 — LIR → EDF(커널 바이너리).
공개된 각 덤프 플래그는 하나의 단계를 대상으로 하며 특정 사용처를 위한 산출물을 내보냅니다. 모든 덤프 플래그는 단일 커널 옵션입니다.
--dump-visa: 컴파일러/백엔드 검사를 위한 1단계 vISA 텍스트입니다.--dump-ir: 컴파일러 도구를 위한 bincode 바이너리 형식의 2단계 LIR입니다.--dump-dfg: 그래프 검사를 위해 컴파일러 IR 바이너리 데이터로 직렬화되어 요청한 파일에 기록되는 1단계 vISA 데이터 흐름 그래프입니다.--dump-graph: IR 그래프 Viewer에서 사용할 수 있도록 2단계 LIR 그래프를 JSON으로 출력합니다.--dump-summary: 요청한 디렉터리에 기록되는 3단계 LIR→EDF 컴파일 요약입니다.--dump-schedule: LIR이ResourceLir로 로워링된 후의 3단계 스케줄링으로, Schedule Viewer를 위한 JSON 형식으로 출력됩니다.
[FILTER]...
컴파일할 #[device] 함수의 집합을 지정합니다. 필터는 전체 경로(abc::def::foo)로 표현된 #[device] 함수 이름에 대해 부분 문자열로 매칭됩니다. 함수가 필터 중 하나에라도 매칭되면 컴파일됩니다. 생략하면 모든 디바이스 함수가 컴파일됩니다.
-p, --package name
컴파일 대상을 지정한 이름의 커널 패키지로 제한합니다. 이 옵션을 반복 지정하여 여러 커널 패키지를 선택할 수 있습니다. 생략하면 모든 커널 패키지가 컴파일됩니다.
--message-format format
컴파일러에 전달되는 진단 형식(예: json)으로, 도구가 커널 컴파일 실패 진단을 기계적으로 파싱할 수 있게 합니다.
--dump-visa file
중간 vISA를 파일로 덤프합니다. 단일 커널을 컴파일할 때만 사용해야 합니다.
--dump-ir file
중간 LIR(Low-Level IR)을 bincode 바이너리 형식으로 파일에 덤프합니다. 단일 커널을 컴파일할 때만 사용해야 합니다.
--dump-schedule file
LIR을 ResourceLir로 낮춘 뒤, 그 결과로 생성된 스케줄을 Schedule Viewer용 JSON으로 덤프합니다. 단일 커널을 컴파일할 때만 사용해야 합니다.
--dump-dfg file
1단계 vISA 데이터 흐름 그래프를 파일로 덤프합니다. 단일 커널을 컴파일할 때만 사용해야 합니다.
--dump-graph file
IR 그래프 Viewer에서 사용할 수 있도록 2단계 LIR 그래프를 JSON으로 덤프합니다. 단일 커널을 컴파일할 때만 사용해야 합니다.
--dump-summary dir
진단 도구에서 사용할 수 있도록 3단계 LIR-to-EDF 컴파일 요약을 디렉터리에 덤프합니다. 단일 커널을 컴파일할 때만 사용해야 합니다.
환경 변수
FURIOSA_OPT_OUT_DIR
커널 출력 디렉터리입니다. 기본값은 <workspace target>/furiosa-opt/kernel입니다.