콘텐츠로 이동

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
HaError HaVmmAllocatePool(uint64_t arena_bytes, int64_t block_bytes, uint32_t alignment, HaVmmPool *inout_pool, int64_t *out_block_stride);

예제

1
2
3
4
5
6
7
8
HaVmmBlockSegment seg[1];
HaVmmPool pool{seg, 1};             // in: capacity 1
int64_t block_stride = 0;
HaError err = HaVmmAllocatePool(pool_bytes, block_bytes, /*alignment=*/4096, &pool, &block_stride);
if (err != HaError::HaSuccess) {
  return err;
}
// out: one segment; seg[0].pa_start is the HW page base address for HaVmmInitBlocks()

HaVmmInitBlocks()보다 먼저 호출하며, 초기화 없이 호출할 수 있습니다. 세그먼트(HaVmmBlockSegment)에는 원래 할당의 기준 주소와 크기(raw_ptr / raw_size)가 들어 있고, 해제할 때는 이 값을 씁니다. pa_start는 raw_ptr을 alignment에 맞춰 올림한 주소입니다.


HaVmmDeinit

현재 디바이스의 VMM 상태를 해제합니다. 진행 중인 커널이 없을 때 호출해야 합니다.

Returns — 성공하면 HaSuccess, 아니면 오류 코드.

시그니처 · 예제
1
HaError HaVmmDeinit(void);

예제

1
2
HaVmmFreePool(pool);   // every request unmapped first
HaVmmDeinit();         // no kernels in flight past this point

호스트 쪽 상태만 해제하며, 풀은 해제하지 않습니다(HaVmmFreePool()을 쓰십시오). 초기화된 것이 없을 때 호출하면 아무 동작도 하지 않습니다.


HaVmmFreePool

HaVmmAllocatePool로 만든 풀의 세그먼트를 모두 해제합니다.

Parameter Direction Default Description
pool in — 해제할 풀 (세그먼트와 개수). 개수가 0이면 아무 동작도 하지 않습니다.

Returns — 성공하면 HaSuccess, 아니면 처음 실패한 세그먼트의 해제 오류. 실패해도 나머지 세그먼트는 해제합니다.

시그니처 · 예제
1
HaError HaVmmFreePool(HaVmmPool pool);

예제

1
2
3
4
5
// every request is unmapped by now
HaError err = HaVmmFreePool(pool);
if (err != HaError::HaSuccess) {
  return err;
}

각 세그먼트를 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
HaError HaVmmInitBlocks(int64_t *out_page_size, int64_t num_rows, int64_t max_num_blocks_per_row, int64_t num_attn_layers, int64_t num_kv_heads, int64_t block_size, int64_t head_dim, uint32_t elem_size_bits, HaDevicePtr pool_base = HA_DEVICE_PTR_NULL, uint64_t pool_bytes = 0, uint32_t page_size_in = 0, uint32_t shared_ch_in = 0);

예제

1
2
3
4
5
// after HaVmmAllocatePool: set the pool as the HW page base address
int64_t page_size = 0;
HaError err = HaVmmInitBlocks(&page_size, num_rows, /*max_num_blocks_per_row=*/1, num_attn_layers,
                              num_kv_heads, /*block_size=*/max_tokens, head_dim, elem_size_bits,
                              seg[0].pa_start, pool_bytes);   // page_size == 4096 (per channel)

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
HaError HaVmmMapBlocksBatchFromPool(const HaDevicePtr *vas, uint32_t va_count, const int64_t *row_indices, const int64_t *cached_block_ids, const int64_t *cached_blocks_per_req, HaVmmPool pool, const int64_t *new_block_ids, const int64_t *new_blocks_per_req, uint32_t num_reqs, int64_t block_size);

예제

1
2
3
4
5
6
7
8
// request slot 3 grows from 10 to 12 tokens
const HaDevicePtr vas[] = {k_va, v_va};
const int64_t row[] = {3};
const int64_t have[] = {10};
const int64_t add[] = {2};
const int64_t unused_ids[] = {0, 0};   // not read, but must be non-null
HaError err = HaVmmMapBlocksBatchFromPool(vas, 2, row, nullptr, have, pool, unused_ids, add,
                                          /*num_reqs=*/1, /*block_size=*/1);

요청마다 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
HaError HaVmmMapBlocksBatchFromPools(const HaDevicePtr *vas, uint32_t va_count, const HaVmmPool *pools, uint32_t num_pools, const HaVmmBlockId *block_ids, const int64_t *blocks_per_va, int64_t block_size);

페이지는 블록 수만으로 관리되므로 배치 위치 지정은 적용되지 않습니다. 풀과 블록 좌표는 무시되고, 각 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
HaError HaVmmReserveBlocks(HaDevicePtr *out_va, int64_t *out_block_stride_bytes, int64_t num_blocks, int64_t numel_per_block, uint32_t elem_size_bits);

예제

1
2
3
4
5
6
7
HaDevicePtr k_va = 0, v_va = 0;
int64_t k_stride = 0, v_stride = 0;
HaError err = HaVmmReserveBlocks(&k_va, &k_stride, num_blocks, numel_per_block, elem_size_bits);
if (err == HaError::HaSuccess) {
  err = HaVmmReserveBlocks(&v_va, &v_stride, num_blocks, numel_per_block, elem_size_bits);
}
v_va |= 1ull << 57;   // VALUE arena

상태를 갖지 않으므로 초기화 없이 언제든 호출할 수 있습니다. 돌려받은 주소는 예약이 아니므로 해제할 것이 없습니다.


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
HaError HaVmmUnmapBlocksBatchFromPool(const HaDevicePtr *vas, uint32_t va_count, const int64_t *row_indices, const int64_t *block_ids, const int64_t *block_offsets, const int64_t *blocks_per_req, uint32_t num_reqs, int64_t block_size);

예제

1
2
3
4
5
6
// request slot 3 finished with 12 tokens, after its kernels completed
const HaDevicePtr vas[] = {k_va, v_va};
const int64_t row[] = {3};
const int64_t done[] = {12};
HaError err = HaVmmUnmapBlocksBatchFromPool(vas, 2, row, nullptr, nullptr, done,
                                            /*num_reqs=*/1, /*block_size=*/1);

요청의 KEY·VALUE 페이지를 반환합니다. 풀은 필요하지 않습니다.