Skip to content

TLB API

Static KV-cache TLB initialization and page management (Bertha DC EVT0), and low-level TLB configuration, page table range, and invalidation for the current device. See Memory Model.

Contents

API Description
HaAllocTlbPage Allocates memory in TLB/page units (low-level/compile path)
HaConfigureTlb Configures TLB behavior such as page size, shared channels, and automatic prefetch
HaDeallocTlbPage Frees memory allocated with HaAllocTlbPage()
HaFlushTlb Invalidates the entire TLB cache of the current device
HaInitTlb Initializes the TLB with the static KV-cache geometry (Bertha DC EVT0 only)
HaSetPageTableRange Sets the page table base address and size, and the effective VPN width

HaAllocTlbPage

Allocates memory at the TLB/page level (low-level/compile path).

Parameter Direction Default Description
page_alloc_info inout — Allocation request/response structure (required). See TLBAllocInfo.

Returns — Success or an error code.

Signature · Example
1
HaError HaAllocTlbPage(TLBAllocInfo *page_alloc_info);

Example

1
2
3
4
5
TLBAllocInfo alloc{};
alloc.req_id = request_id;
alloc.page_num = pages_needed;
alloc.page_type = PageType::KEY;
HaAllocTlbPage(&alloc);

Note

Use this when you need explicit page-level mapping instead of HaMemAlloc(). Details are defined by the fields in TLBAllocInfo.


HaConfigureTlb

Configures TLB behavior: page size, shared channels, and optional auto prefetch. Low-level control for the current device.

Parameter Direction Default Description
page_size in — Page size in bytes (platform constraints apply).
shared_channel_number in — Shared channel number/count (platform-dependent).
auto_prefetch_enable in 0 Enables auto prefetch.
auto_prefetch_len_x in 0 Prefetch length X.
auto_prefetch_len_y in 0 Prefetch length Y.
auto_prefetch_stride_y in 0 Prefetch stride Y.
transl_time_limit in 0 Translation time limit/timeout.

Returns — Success or an error code.

Signature
1
HaError HaConfigureTlb(uint32_t page_size, uint32_t shared_channel_number, uint8_t auto_prefetch_enable=0, uint16_t auto_prefetch_len_x=0, uint16_t auto_prefetch_len_y=0, uint16_t auto_prefetch_stride_y=0, uint32_t transl_time_limit=0);

Note

(Re)configuration always invalidates the TLB cache, because a changed page size makes cached translations stale. Use HaFlushTlb() when mappings changed but the configuration did not.


HaDeallocTlbPage

Frees memory allocated via HaAllocTlbPage().

Parameter Direction Default Description
page_dealloc_info inout — Deallocation structure describing what to free (required). See TLBDeallocInfo.

Returns — Success or an error code.

Signature · Example
1
HaError HaDeallocTlbPage(TLBDeallocInfo *page_dealloc_info);

Example

1
2
3
4
5
TLBDeallocInfo dealloc{};
dealloc.req_id = request_id;
dealloc.page_num = pages_to_release;
dealloc.page_type = PageType::KEY;
HaDeallocTlbPage(&dealloc);   // released when the request finishes

HaFlushTlb

Flushes (invalidates) the entire TLB cache for the current device. Call it when the page mapping changes (e.g. a KV-cache remap) and cached translations must be dropped. HaConfigureTlb() and HaSetPageTableRange() already invalidate, so call this only when neither of them is called.

Returns — Success or an error code.

Signature
1
HaError HaFlushTlb();

HaInitTlb

Initializes the TLB with static KV-cache geometry (Bertha DC EVT0 only). On EVT1, configure the TLB with HaConfigureTlb() and HaSetPageTableRange() instead.

Parameter Direction Default Description
info in — TLB init info (page size, base address, layer/head counts, value page mode, …). Required. See TLBInitInfo.

Returns — Success or an error code.

Signature · Example
1
HaError HaInitTlb(const TLBInitInfo *info);

Example

1
2
3
4
5
6
7
TLBInitInfo info{};
info.page_size = page_size;
info.base_addr = kv_base;
info.layer_num = num_layers;
info.head_num = num_kv_heads;
info.max_page_num = max_pages;
HaInitTlb(&info);

Note

This is the static KV-cache TLB path for Bertha DC EVT0. For KV-cache mapping, the VMM API, which wraps this TLB, is recommended. HaVmmInitBlocks() initializes the TLB, and map/unmap allocate and release per-request pages.


HaSetPageTableRange

Sets the page table base address, size, and effective VPN width for the current device.

Parameter Direction Default Description
page_table_base_addr in — Page table base address.
page_table_size in — Page table size in bytes.
effective_vpn_width in — Effective virtual page number (VPN) width in bits.
cache_invalidate in 1 Whether to invalidate the TLB cache once after updating the range. Pass 0 only when the caller flushes deliberately afterwards with HaFlushTlb().

Returns — Success or an error code.

Signature
1
HaError HaSetPageTableRange(size_t page_table_base_addr, size_t page_table_size, uint32_t effective_vpn_width, uint8_t cache_invalidate=1);