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

Every command on this page is also available from the command line as xcena_cli im <name> — see InfiniteMemory CLI. The CLI takes a zero-based device address where the API takes a host pointer; the behavior documented here is otherwise the same.

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.
• 4 GiB of the capacity is always kept evictable and can never be pinned, so the pin ceiling is the capacity minus 4 GiB. At the 4 GB minimum the ceiling is 0 and pinning is unavailable — see set-dram-capacity.
• Default pin budget: approximately 50% of total DRAM capacity, capped by that ceiling — below 8 GiB the default is the ceiling instead. 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);