InfiniteMemory CLI (`xcena_cli im`)

CLI tools for configuring and monitoring InfiniteMemory at runtime. Five commands grouped under xcena_cli im:

Health — get-smart
Configuration — set-prefetch, set-dram-capacity, set-ssd-capacity, set-pin-threshold

Prerequisites

xcena_cli installed — part of the XCENA SDK. Refer to the XCENA SDK — Installation Guide.
InfiniteMemory firmware — the target device must be running the InfiniteMemory firmware (these commands are not exposed on devices running other firmwares shipped on the same hardware).

Hidden command group. im is not listed in xcena_cli --help. Use xcena_cli im --help to enumerate its commands:

$ xcena_cli im --help
Usage: xcena_cli im [OPTIONS] COMMAND [ARGS]...
   InfiniteMemory (IM) — configure and monitor InfiniteMemory.
Commands:
   get-smart           <device_id>: display InfiniteMemory health and runtime statistics
   set-dram-capacity   <device_id> <bytes|"max">: set DRAM capacity (bytes, 16 MiB multiple, or "max")
   set-pin-threshold   <device_id> <bytes|"max"|"default">: set the pin ceiling (bytes, 16 MiB multiple, "max", or "default")
   set-prefetch        <device_id> <mode>: set InfiniteMemory prefetch mode
   set-ssd-capacity    <device_id> <bytes|"max">: set SSD capacity (bytes, 1 GiB multiple, or "max")

CLI Summary

Command	Usage	Description
Get SMART	`xcena_cli im get-smart <device_id> [-v] [-h]`	NVMe SMART + InfiniteMemory runtime stats
Set Prefetch	`xcena_cli im set-prefetch <device_id> <mode>`	Set prefetch mode (`never` / `always` / `auto`)
Set DRAM Capacity	`xcena_cli im set-dram-capacity <device_id> <size>`	Set DRAM capacity for testing, min 16 GB, 16 MiB multiple (bytes or `max`)
Set SSD Capacity	`xcena_cli im set-ssd-capacity <device_id> <size>`	Set SSD capacity, 1 GiB multiple (bytes or `max`, requires reboot)
Set Pin Threshold	`xcena_cli im set-pin-threshold <device_id> <size>`	Set the device-wide pin ceiling, 16 MiB multiple (bytes, `max`, or `default`)

Run xcena_cli im --help (or xcena_cli im <command> --help) to see usage details for each command.

Health

`get-smart`

xcena_cli im get-smart <device_id> [-v] [-h]

Display SMART/health info of the attached NVMe SSD plus InfiniteMemory internal runtime statistics. Useful for monitoring SSD wear, temperature, and PXL command activity.

Output has two sections:

NVMe SMART / Health Information Log — standard NVMe SMART fields reported by the backing SSD (temperature, wear, endurance, error counters).
InfiniteMemory Statistics — device configuration and runtime state plus lifetime activity totals: a Config snapshot (SSD model, link, prefetch mode), a Memory snapshot (SSD/DRAM capacity, pin threshold), a Status snapshot (resident / dirty / pinned DRAM bytes), and Total (Cumulative) totals — page hit/miss counters, per-command invocation counts, and total bytes processed for each PXL command (prefetch, pin, …) and NVMe pass-through (nvme_read, nvme_write).

Parameters

Name	Description
`device_id`	Target device ID (integer, e.g., `0`, `1`, …)

Options

Option	Description
`-v`, `--verbose`	Also show each setting’s provisioning ceiling — the `*_max` rows
`-h`, `--human`	Render byte counts in IEC units (GiB / MiB) instead of raw bytes

--human only changes how a number is spelled, never its value: it picks the largest unit that still spells the byte count exactly, so a capacity is never rounded to look like its ceiling.

Example

$ xcena_cli im get-smart 0
[ OK ] im get-smart recv (status=Success 0x0)
NVMe SMART / Health Information Log:
  critical_warning            : 0x00
  composite_temperature       : 297 K (24 C)
  available_spare             : 100%
  available_spare_threshold   : 10%
  percentage_used             : 4%
  data_units_read             : 7989306188
  data_units_written          : 3079179371
  ...
  temperature_sensor_1        : 309 K (36 C)
  temperature_sensor_2        : 302 K (29 C)

InfiniteMemory Statistics:
  Config:
    ssd_model      : NVMe SSD 1920GB
    ssd_link_speed : Gen5
    ssd_link_width : x4
    prefetch_mode  : Auto
  Memory:
    ssd_capacity   : 3839700762624
    dram_capacity  : 248034361344
    pin_threshold  : 124017180672
  Status:
    used_dram_bytes   : 1579155456
    dirty_dram_bytes  : 1573388288
    pin_bytes         : 0
  Total (Cumulative):
    Counters:
      page_hit                : 192117487
      page_miss               : 36173
    Commands:
      prefetch                : 0
      pin                     : 0
      unpin                   : 0
      unpin_all               : 0
      unmap                   : 0
      ...
    Bytes:
      prefetch                : 0
      pin                     : 0
      unpin                   : 0
      unmap                   : 0
      ...

Under InfiniteMemory Statistics in the output above:

Config — device identity and mode, e.g. SSD model, PCIe link speed/width, and the current prefetch mode.
Memory — the capacities and thresholds you can set. Each row shows the applied value; if a change is staged but not yet active the row is annotated [pending <value>, reboot required] (see set-ssd-capacity).
Status — current DRAM occupancy: used_dram_bytes (resident), dirty_dram_bytes (modified, pending writeback), pin_bytes (pinned).
Total (Cumulative) — lifetime totals since boot: Counters (page_hit / page_miss), Commands (per-command invocation counts), and Bytes (cumulative byte volume the device actually processed for each command).

Verbose (-v)

-v adds detail rows that are hidden by default, such as each setting’s <name>_max:

$ xcena_cli im get-smart 0 -v
...
  Memory:
    ssd_capacity      : 3839700762624
    ssd_capacity_max  : 3839700762624
    dram_capacity     : 248034361344
    dram_capacity_max : 248034361344
    pin_threshold     : 124017180672
    pin_threshold_max : 239444426752
...

Human-readable sizes (-h)

$ xcena_cli im get-smart 0 -vh
...
  Memory:
    ssd_capacity      : 3576 GiB
    ssd_capacity_max  : 3576 GiB
    dram_capacity     : 231 GiB
    dram_capacity_max : 231 GiB
    pin_threshold     : 115.5 GiB
    pin_threshold_max : 223 GiB
  Status:
    used_dram_bytes   : 1506 MiB
    dirty_dram_bytes  : 1500.5 MiB
    pin_bytes         : 0 MiB
...

The unit is chosen per group so a value and its ceiling stay directly comparable, and it is only promoted when the byte count divides exactly — a size that would need rounding stays in the smaller unit.

Configuration

`set-prefetch`

xcena_cli im set-prefetch <device_id> <mode>

Set the InfiniteMemory internal prefetch mode — the device-side policy for automatically pulling SSD pages into DRAM ahead of host accesses. Distinct from pxl::prefetchMemory, which is a host-issued, region-specific prefetch request.

Mode	Behavior
`never`	Disable internal prefetch entirely.
`always`	Always run internal prefetch.
`auto`	Workload-aware — enable prefetch only when the device detects an access pattern that benefits from it.

Parameters

Name	Description
`device_id`	Target device ID (integer, e.g., `0`, `1`, …)
`mode`	One of `never`, `always`, `auto`

Example

$ xcena_cli im set-prefetch 0 never
[ OK ] im set-prefetch mode=never (status=Success 0x0)

$ xcena_cli im set-prefetch 0 always
[ OK ] im set-prefetch mode=always (status=Success 0x0)

$ xcena_cli im set-prefetch 0 auto
[ OK ] im set-prefetch mode=auto (status=Success 0x0)

`set-dram-capacity`

xcena_cli im set-dram-capacity <device_id> <bytes|"max">

Forcibly set the usable capacity of the Cache Region to a smaller value for testing.

Parameters

Name	Description
`device_id`	Target device ID (integer, e.g., `0`, `1`, …)
`<size>`	Capacity in bytes (positive integer, or with a `TiB`/`GiB`/`MiB` suffix), or the literal `max` to restore the device’s full DRAM capacity. `0` is not supported — use `max` to set the maximum capacity.

Behavior

max — restores the Cache Region to its maximum capacity (default).
Minimum supported capacity: 16 GB.
Maximum supported capacity: the Cache Region’s maximum.
A multiple of 16 MiB. The device splits DRAM evenly across its internal engines, so capacity is provisioned in 16 MiB steps. An unaligned request is rejected with InvalidValue.
Values outside this range return an error.
All pins are released. Re-pin after the call if needed.
max is exempt from the alignment rule — the device resolves it itself.

Example

$ xcena_cli im set-dram-capacity 0 17179869184
[ OK ] im set-dram-capacity capacity=17179869184 (status=Success 0x0)

$ xcena_cli im set-dram-capacity 0 max
[ OK ] im set-dram-capacity capacity=0 (status=Success 0x0)

`set-ssd-capacity`

xcena_cli im set-ssd-capacity <device_id> <bytes|"max">

Set the usable SSD capacity for InfiniteMemory to a smaller value for testing.

Reboot required. The new capacity is staged on the device — it only takes effect after the next device reboot. The active capacity does not change while the device is running.

Parameters

Name	Description
`device_id`	Target device ID (integer, e.g., `0`, `1`, …)
`<size>`	Capacity in bytes (positive integer, or with a `TiB`/`GiB`/`MiB` suffix), or the literal `max` to restore the device’s full SSD capacity.

Behavior

max — restores the SSD to its maximum capacity (default).
GB-aligned (rounded down). The requested size is truncated to the nearest 1 GB boundary; sub-GB remainders are dropped. Note this differs from set-dram-capacity and set-pin-threshold, which reject an unaligned request instead of truncating it.
Effective only after the next device reboot.

Example

$ xcena_cli im set-ssd-capacity 0 4294967296
[ OK ] im set-ssd-capacity capacity=4294967296 (status=Success 0x0)

$ xcena_cli im set-ssd-capacity 0 max
[ OK ] im set-ssd-capacity capacity=0 (status=Success 0x0)

`set-pin-threshold`

xcena_cli im set-pin-threshold <device_id> <bytes|"max"|"default">

Set the device-wide ceiling on how much DRAM may be pinned. Pinning beyond this budget returns ResourceExhaust — see pxl::pinMemory.

Parameters

Name	Description
`device_id`	Target device ID (integer, e.g., `0`, `1`, …)
`<size>`	Ceiling in bytes (or with a `TiB`/`GiB`/`MiB` suffix), or one of the literals `max` / `default`.

Behavior

max — the largest ceiling this device’s geometry accepts.
default — half the current DRAM capacity.
0 — blocks pinning entirely. Use it with care: no pages can be pinned at all until the ceiling is raised again.
A multiple of 16 MiB, the same step set-dram-capacity uses. An unaligned or oversized request is rejected with InvalidValue.
max and default are exempt from the alignment rule — the device resolves them itself.
The ceiling moves with DRAM capacity, so re-check it after set-dram-capacity. Read the applied value and its ceiling with xcena_cli im get-smart <device_id> -v (pin_threshold / pin_threshold_max).

Example

$ xcena_cli im set-pin-threshold 0 124017180672
[ OK ] im set-pin-threshold threshold=124017180672 (status=Success 0x0)

$ xcena_cli im set-pin-threshold 0 64GiB
[ OK ] im set-pin-threshold threshold=68719476736 (status=Success 0x0)

$ xcena_cli im set-pin-threshold 0 max
[ OK ] im set-pin-threshold threshold=max (status=Success 0x0)

$ xcena_cli im set-pin-threshold 0 default
[ OK ] im set-pin-threshold threshold=default (status=Success 0x0)

With max and default the device resolves the number itself; read back what it settled on with xcena_cli im get-smart <device_id>.

InfiniteMemory CLI (xcena_cli im)

Prerequisites

CLI Summary

Health

get-smart

Configuration

set-prefetch

set-dram-capacity

set-ssd-capacity

set-pin-threshold

InfiniteMemory CLI (`xcena_cli im`)

`get-smart`

`set-prefetch`

`set-dram-capacity`

`set-ssd-capacity`

`set-pin-threshold`