VMM API¶
Paged KV 캐시 가상 메모리 API입니다. 이 문서의 호출 순서와 값은 현재 하드웨어 리비전(엔지니어링 샘플) 기준입니다. 런타임이 HW 페이지를 설정합니다. KV 주소에는 요청 슬롯과 KEY/VALUE 비트가 들어 있고, 요청마다 페이지가 블록 수에 맞춰 늘어나고, 요청이 끝나면 해제됩니다. 호출 순서는 메모리 모델의 가상 메모리 및 HW 페이지 관리를 따르십시오. 모든 호출은 호출 스레드의 현재 디바이스로 라우팅되며, 가상 주소 값으로 디바이스가 선택되지는 않습니다.
Contents¶
| API | 설명 |
|---|---|
HaVmmAllocatePool |
물리 KV 풀 할당 |
HaVmmDeinit |
현재 디바이스의 VMM 상태 해제 |
HaVmmFreePool |
풀의 세그먼트 해제 |
HaVmmInitBlocks |
풀과 블록 지오메트리로 HW 페이지 초기화 |
HaVmmMapBlocksBatchFromPool |
요청별 KV 페이지를 블록 수에 맞게 늘림 |
HaVmmMapBlocksBatchFromPools |
여러 VA에 블록 수만큼 KV 페이지를 한 번에 할당 (다중 풀 형식) |
HaVmmReserveBlocks |
KV 아레나(KEY 또는 VALUE) 하나의 기준 주소 반환 |
HaVmmUnmapBlocksBatchFromPool |
요청별 KV 페이지 해제 |
HaVmmAllocatePool¶
물리 KV 풀을 할당합니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
arena_bytes |
in | — | 할당할 풀의 크기(바이트). |
block_bytes |
in | — | 블록 하나의 바이트 크기. |
alignment |
in | — | 기준 주소 정렬. 2의 거듭제곱 또는 0이어야 하며, 주어진 값을 그대로 씁니다. 정렬이 필요 없으면 0. |
inout_pool |
in/out | — | HaVmmPool 구조체. 입력: segments는 호출자 버퍼를, num_segments는 그 용량을 가리킵니다. 출력: segments[0]에 풀 세그먼트가 채워지고, num_segments는 버퍼에 쓴 세그먼트 수입니다 (항상 1). |
out_block_stride |
out | — | 블록이 차지하는 바이트 수 (block_bytes). |
Returns — 성공하면 HaSuccess, 아니면 오류 코드. 용량이 부족하면 실패합니다.
시그니처 · 예제
1 | |
예제
1 2 3 4 5 6 7 8 | |
HaVmmInitBlocks()보다 먼저 호출하며, 초기화 없이 호출할 수 있습니다. 세그먼트(HaVmmBlockSegment)에는 원래 할당의 기준 주소와 크기(raw_ptr / raw_size)가 들어 있고, 해제할 때는 이 값을 씁니다. pa_start는 raw_ptr을 alignment에 맞춰 올림한 주소입니다.
HaVmmDeinit¶
현재 디바이스의 VMM 상태를 해제합니다. 진행 중인 커널이 없을 때 호출해야 합니다.
Returns — 성공하면 HaSuccess, 아니면 오류 코드.
시그니처 · 예제
1 | |
예제
1 2 | |
호스트 쪽 상태만 해제하며, 풀은 해제하지 않습니다(HaVmmFreePool()을 쓰십시오). 초기화된 것이 없을 때 호출하면 아무 동작도 하지 않습니다.
HaVmmFreePool¶
HaVmmAllocatePool로 만든 풀의 세그먼트를 모두 해제합니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
pool |
in | — | 해제할 풀 (세그먼트와 개수). 개수가 0이면 아무 동작도 하지 않습니다. |
Returns — 성공하면 HaSuccess, 아니면 처음 실패한 세그먼트의 해제 오류. 실패해도 나머지 세그먼트는 해제합니다.
시그니처 · 예제
1 | |
예제
1 2 3 4 5 | |
각 세그먼트를 raw_ptr 기준으로 해제합니다.
페이지가 매핑된 풀을 해제하지 마십시오
모든 요청을 먼저 언매핑하십시오. 페이지가 매핑된 채로 해제하면 풀 메모리가 드라이버로 반환되고, 다음 할당이 그 메모리를 그대로 재사용할 수 있습니다. 설정된 HW 페이지 기준 주소는 여전히 그 메모리를 가리킵니다. 해제 대상은 raw_ptr이며, 정렬된 기준 주소인 pa_start는 해제 대상이 아닙니다. 다른 곳이 소유한 세그먼트(예: torch 풀 텐서)는 여기서 해제하지 마십시오.
HaVmmInitBlocks¶
현재 디바이스의 HW 페이지를 풀과 블록 지오메트리로 초기화하고, 페이지 크기를 out_page_size에 씁니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
out_page_size |
out | — | 채널당 페이지 크기(바이트). |
num_rows |
in | — | 요청 슬롯 수입니다. vLLM의 max_num_seqs와 비슷한 개념이며, 요청 슬롯은 현재 최대 1024개입니다. 토큰 길이가 아닙니다. |
max_num_blocks_per_row |
in | — | 요청 하나가 가질 수 있는 최대 블록 수. block_size와 곱한 값이 요청당 최대 토큰 수입니다. |
num_attn_layers |
in | — | attention 레이어 수. |
num_kv_heads |
in | — | KV 헤드 수. |
block_size |
in | — | 블록 하나에 담기는 토큰 수. max_num_blocks_per_row와 곱한 값이 요청당 최대 토큰 수입니다. 현재 매핑 단위는 블록 하나가 토큰 하나입니다(map·unmap의 block_size는 1). |
head_dim |
in | — | 헤드당 차원 수. |
elem_size_bits |
in | — | 원소 하나의 비트 크기 (mxfp4=4, fp8=8, bf16=16). numel*bits는 바이트 단위로 나누어떨어져야 합니다. |
pool_base |
in | HA_DEVICE_PTR_NULL |
필수. 물리 KV 풀의 기준 주소 (HaVmmAllocatePool()이 돌려준 segments[0].pa_start), 4 KiB 정렬. |
pool_bytes |
in | 0 |
필수. 물리 KV 풀의 바이트 용량. 최대 토큰 수에서 요청 하나의 KEY·VALUE 페이지를 담을 수 있어야 합니다. |
page_size_in |
in | 0 |
쓰이지 않습니다 (페이지 크기는 채널당 4096으로 고정). |
shared_ch_in |
in | 0 |
쓰이지 않습니다. |
Returns — 성공하면 HaSuccess, 아니면 오류 코드.
시그니처 · 예제
1 | |
예제
1 2 3 4 5 | |
pool_base를 HaVmmAllocatePool()에서 받으므로 그 다음에 호출하십시오. 다시 호출하면 기존 상태를 먼저 해제합니다.
pool_base와 pool_bytes는 시그니처상 기본값이 있지만, 현재는 넣지 않으면 에러입니다.
HaVmmMapBlocksBatchFromPool¶
요청마다 KEY·VALUE 페이지를 새 블록 수를 담을 만큼 늘립니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
vas |
in | — | KEY·VALUE 아레나 기준 주소 배열 ({KEY, VALUE}). |
va_count |
in | — | 아레나 수 (2: KEY, VALUE). |
row_indices |
in | — | 요청별 슬롯, 0..1023. 가상 주소의 비트 56:47에 들어갑니다. 필수. |
cached_block_ids |
in | — | 읽지 않습니다. null이어도 됩니다. |
cached_blocks_per_req |
in | — | 요청별로 이미 매핑된 블록 수. |
pool |
in | — | 읽지 않습니다 (풀은 HaVmmInitBlocks()에서 등록됨). segments는 null이어도 됩니다. |
new_block_ids |
in | — | 읽지 않지만, 매핑할 것이 있으면 null이 아니어야 합니다. |
new_blocks_per_req |
in | — | 요청별로 새로 매핑할 블록 수. |
num_reqs |
in | — | 요청 수. |
block_size |
in | — | 블록당 토큰 수. 반드시 1. |
Returns — 성공하면 HaSuccess, 아니면 오류 코드.
시그니처 · 예제
1 | |
예제
1 2 3 4 5 6 7 8 | |
요청마다 KEY·VALUE 페이지를 이미 매핑된 블록 수(cached_blocks_per_req)와 새로 매핑하는 블록 수(new_blocks_per_req)의 합에 맞게 늘립니다. 매 스텝 이미 매핑된 정확한 블록 수(cached_blocks_per_req)를 넘기십시오. 이전 스텝의 커널이 끝난 뒤에만 호출하십시오.
HaVmmMapBlocksBatchFromPools¶
여러 VA에 블록을 한 번에 매핑하는 명시적 다중 풀 형식입니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
vas |
in | — | VA 기준 주소 배열 (va_count개). 각 VA에는 요청 슬롯(비트 56:47)과 KEY/VALUE 비트(비트 57)가 이미 들어 있어야 합니다. |
va_count |
in | — | VA 수. 0이면 아무 동작도 하지 않습니다. |
pools |
in | — | 풀 배열. 읽지 않습니다. null이어도 됩니다. |
num_pools |
in | — | 풀 수. 읽지 않습니다. |
block_ids |
in | — | (pool_idx, block_idx) 좌표(HaVmmBlockId) sum(blocks_per_va)개를 VA 순서로 이어 붙인 배열. 값은 읽지 않지만, 매핑할 블록이 있으면 null이 아니어야 합니다. |
blocks_per_va |
in | — | VA별로 매핑할 블록 수 (0 이상). |
block_size |
in | — | 블록당 토큰 수. 반드시 1. |
Returns — 성공하면 HaSuccess. vas나 blocks_per_va가 null이거나, block_size가 1이 아니거나, blocks_per_va에 음수가 있거나, 매핑할 블록이 있는데 block_ids가 null이면 HaMemoryInvalidArgument. 그 밖에는 오류 코드.
시그니처
1 | |
페이지는 블록 수만으로 관리되므로 배치 위치 지정은 적용되지 않습니다. 풀과 블록 좌표는 무시되고, 각 VA의 이미 매핑된 블록 수를 0으로 보아 blocks_per_va[v]개를 담을 만큼 요청 페이지를 할당합니다. 이미 페이지가 있는 요청을 늘릴 때는 HaVmmMapBlocksBatchFromPool()을 쓰십시오.
HaVmmReserveBlocks¶
KV 아레나(KEY 또는 VALUE) 하나의 기준 주소를 돌려줍니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
out_va |
out | — | 아레나 기준 주소. 상수 1 << 58(주소 변환 사용)이며, 물리 메모리는 할당되지 않습니다. VALUE 아레나는 호출자가 비트 57을 1로 설정합니다. |
out_block_stride_bytes |
out | — | 블록 사이의 가상 주소 간격(바이트). block_bytes와 같습니다 (블록이 연속으로 놓임). |
num_blocks |
in | — | 아레나가 걸치는 전체 블록 수. |
numel_per_block |
in | — | 블록당 원소 수. |
elem_size_bits |
in | — | 원소 하나의 비트 크기 (mxfp4=4, fp8=8, bf16=16). numel*bits는 바이트 단위로 나누어떨어져야 합니다. |
Returns — 성공하면 HaSuccess, 아니면 오류 코드.
시그니처 · 예제
1 | |
예제
1 2 3 4 5 6 7 | |
상태를 갖지 않으므로 초기화 없이 언제든 호출할 수 있습니다. 돌려받은 주소는 예약이 아니므로 해제할 것이 없습니다.
HaVmmUnmapBlocksBatchFromPool¶
끝난 요청마다 KEY·VALUE 페이지를 반환합니다. HaVmmMapBlocksBatchFromPool에 대응하는 언매핑 함수입니다.
| Parameter | Direction | Default | Description |
|---|---|---|---|
vas |
in | — | KEY·VALUE 아레나 기준 주소 배열 ({KEY, VALUE}). |
va_count |
in | — | 아레나 수 (2: KEY, VALUE). |
row_indices |
in | — | 요청별 슬롯, 0..1023. 필수. |
block_ids |
in | — | 읽지 않습니다. null이어도 됩니다. |
block_offsets |
in | — | 읽지 않습니다. null이어도 됩니다. |
blocks_per_req |
in | — | 요청에 매핑된 블록 수 전체. |
num_reqs |
in | — | 요청 수. |
block_size |
in | — | 블록당 토큰 수. 반드시 1. |
Returns — 성공하면 HaSuccess, 아니면 오류 코드.
시그니처 · 예제
1 | |
예제
1 2 3 4 5 6 | |
요청의 KEY·VALUE 페이지를 반환합니다. 풀은 필요하지 않습니다.