InfiniteMemory Host Commands (PXL API)

PXL (XCENA Programming Library) APIs invoked from the host:

• Cache Management — prefetchMemory, prefetchSyncMemory, pinMemory, unpinMemory, unpinAllMemory, unmapMemory
• Write-back — commitMemory, commitSyncMemory

PXL lets applications go beyond the default policy. When an application knows its access pattern in advance, it can instruct the device directly: prefetch a region before reads arrive, or pin a region so it cannot be evicted. This turns a reactive cache into a cooperative one, reducing latency spikes caused by cold misses.

Applications that modify device memory can also control when changes are written back to SSD: commit a region to write its dirty data back, without loading or evicting anything.

Prerequisites

A working PXL environment is required:

1. PXL installed — PXL runtime and headers must be installed on the host. PXL is provided as part of the XCENA SDK; refer to the XCENA SDK — Installation Guide.
2. InfiniteMemory firmware — the target device must be running the InfiniteMemory firmware (these APIs are not available on other firmwares shipped on the same hardware).

3. Header:

   #include <pxl/pxl.hpp>
   

4. Allocate / release — every command operates on a device-memory pointer obtained via pxl::allocateMemory, and the memory must be released with pxl::releaseMemory once you are done with it.

   auto* ptr = pxl::allocateMemory(deviceId, size);
   if (!ptr) {
       // Allocation failed
   }
   // ... call commands ...
   pxl::releaseMemory(ptr);
   

Command Summary

Command	PXL API	Description
Prefetch	prefetchMemory(ptr, size)	Async prefetch of a memory region into DRAM
PrefetchSync	prefetchSyncMemory(ptr, size)	Prefetch that returns only after the region is resident in DRAM
Pin	pinMemory(ptr, size)	Lock a memory region in DRAM
Unpin	unpinMemory(ptr, size)	Release a DRAM lock
UnpinAll	unpinAllMemory(deviceId)	Release all pins on the device at once
Unmap	unmapMemory(ptr, size)	Clear the internal mapping information for a region (also drops pins/prefetch and evicts from DRAM)
Commit	commitMemory(ptr, size)	Async write-back of a region’s dirty data to SSD (does not load or evict)
CommitSync	commitSyncMemory(ptr, size)	Write-back of a region’s modified data to SSD; waits for completion

Status Codes

Every command returns a MemoryStatus value.

Status	Value	Description
Success	0	Operation succeeded
ResourceExhaust	1	Device resource exhausted (e.g., pin threshold exceeded)
InvalidRequest	2	Invalid parameter or invalid pointer
NotSupported	3	Called on a device running a different firmware (not InfiniteMemory), or against IO Memory

Cache Management API

prefetchMemory

MemoryStatus pxl::prefetchMemory(const void* ptr, size_t size);

Asynchronously prefetches the given memory region into device DRAM.

• Reduces SSD read latency on subsequent host reads.
• Early Response — returns as soon as the request is issued; the actual load completes in the background.
• Prefetched pages may still be evicted by the standard cache policy. Use pinMemory if you need them to stay resident.
• Timing-dependent — if a host read hits the region before the prefetch completes, the benefit is reduced or lost.

Parameters

Name	Type	Description
ptr	const void*	Start pointer of the region to prefetch
size	size_t	Size of the region to prefetch, in bytes

Example — explicit prefetch

constexpr size_t kSize = 1024 * 1024;

// 1) Allocate device memory
auto* ptr = pxl::allocateMemory(0, kSize);
if (!ptr) {
    return -1;
}

// 2) Prefetch into DRAM
auto status = pxl::prefetchMemory(ptr, kSize);
if (status != pxl::MemoryStatus::Success) {
    pxl::releaseMemory(ptr);
    return -1;
}

// 3) Use the data ...

// 4) Release
pxl::releaseMemory(ptr);

prefetchSyncMemory

MemoryStatus pxl::prefetchSyncMemory(const void* ptr, size_t size);

Synchronous variant of prefetchMemory.

• Returns only after the region is resident in device DRAM (contrast prefetchMemory, which returns as soon as the request is issued).
• Use when subsequent reads must not miss — e.g., right before a latency-sensitive phase.
• Like prefetched pages, the region may still be evicted afterward by the standard cache policy. Use pinMemory to keep it resident.

Parameters

Name	Type	Description
ptr	const void*	Start pointer of the region to prefetch
size	size_t	Size of the region to prefetch, in bytes

pinMemory / unpinMemory / unpinAllMemory

MemoryStatus pxl::pinMemory(const void* ptr, size_t size);
MemoryStatus pxl::unpinMemory(const void* ptr, size_t size);
MemoryStatus pxl::unpinAllMemory(uint32_t deviceId);

Lock a memory region into device DRAM so it cannot be evicted.

• pinMemory — pin a single region. Already-pinned regions are skipped. Loads from SSD into DRAM if not already resident, and returns only after the DRAM load completes (synchronous; contrast with prefetchMemory, which returns early).
• unpinMemory — unpin a single region.
• unpinAllMemory — unpin all pinned regions on the device at once.
  • ※ Optional convenience API intended for idle-state cleanup (e.g., between workload phases). Not recommended during active workload; use unpinMemory for targeted release instead.
• Once unpinned, the region is again subject to the standard cache policy and may be evicted.
• Default pin budget: approximately 50% of total DRAM capacity. Exceeding the budget in effect returns ResourceExhaust.
• The budget is configurable and can be raised well above the default — see xcena_cli im set-pin-threshold. To read the value in effect, run xcena_cli im get-smart <device_id> and look at pin_threshold under Memory.

Parameters

Name	Type	Description
ptr	const void*	Start pointer of the region to pin/unpin
size	size_t	Size of the region to pin/unpin, in bytes
deviceId	uint32_t	Target device ID for unpinAllMemory

Example — alloc → pin → unpin → release

constexpr size_t kSize = 4096;

// 1) Allocate device memory
auto* ptr = pxl::allocateMemory(0, kSize);
if (!ptr) {
    return -1;
}

// 2) Pin into DRAM (prevent eviction)
auto status = pxl::pinMemory(ptr, kSize);
if (status != pxl::MemoryStatus::Success) {
    pxl::releaseMemory(ptr);
    return -1;
}

// 3) Use the data (this region will not be evicted) ...

// 4) Unpin when done
pxl::unpinMemory(ptr, kSize);

// (Note) Use unpinAllMemory to release all pins at once
// pxl::unpinAllMemory(0);

// 5) Release
pxl::releaseMemory(ptr);

unmapMemory

MemoryStatus pxl::unmapMemory(const void* ptr, uint64_t size);

Clears the internal mapping information for a region.

• Clearing the mapping also drops any state associated with the region: pins, prefetched pages, and any other command state are all released, and the region is removed from the DRAM cache.
• Constraint: ptr and size must be 1 GB aligned.

Parameters

Name	Type	Description
ptr	const void*	Start pointer of the region to unmap (1 GB aligned)
size	uint64_t	Size of the region to unmap, in bytes (1 GB aligned)

Write-back API

InfiniteMemory keeps recently written data in DRAM and writes it back to SSD under the standard cache policy. These commands let an application control when a region’s modifications are written back, rather than waiting for the cache policy to do it.

commitMemory / commitSyncMemory

MemoryStatus pxl::commitMemory(const void* ptr, size_t size);
MemoryStatus pxl::commitSyncMemory(const void* ptr, size_t size);

Write back a region’s modified (dirty) data to SSD, turning it clean. Commit only writes data out — it does not load the region into DRAM or keep it there. What stays cached is still decided by the standard cache policy; commit just makes sure the latest changes have reached SSD.

• commitMemory — returns as soon as the request is issued; the write-back completes in the background.
• commitSyncMemory — returns only after the write-back has completed. Use when you need the region’s data on SSD before proceeding.
• Only modified (dirty) data is written; clean regions complete with no SSD traffic.

Parameters (both)

Name	Type	Description
ptr	const void*	Start pointer of the region to write back
size	size_t	Size of the region to write back, in bytes

Example — write → commit → later clean eviction

constexpr size_t kSize = 1024 * 1024;

// 1) Allocate device memory
auto* ptr = pxl::allocateMemory(0, kSize);
if (!ptr) {
    return -1;
}

// 2) Write data (the region is now dirty in DRAM) ...

// 3) Commit: write back the dirty data to SSD. The region's data is now
//    clean; commit does not change what is resident in DRAM.
auto status = pxl::commitMemory(ptr, kSize);
if (status != pxl::MemoryStatus::Success) {
    pxl::releaseMemory(ptr);
    return -1;
}

// 4) Do other work ...

// 5) The region is now clean in cache. When it is later evicted by the
//    standard cache policy, no dirty write-back is needed (clean eviction).

// 6) Release
pxl::releaseMemory(ptr);