Skip to main content

Runtime properties and counters

Mirrored from the FEMU repository

This page is hw/femu/docs/reference/runtime-properties.md at FEMU d8b29b1e0 (2026-11-16), licensed GPL-2.0-or-later. Send corrections to the FEMU repository.

QOM properties that a running device exposes. Read and set them through QMP at /machine/peripheral/<id>, where <id> is the id= given on -device:

{"execute": "qom-get", "arguments": {"path": "/machine/peripheral/cxl-ssd0", "property": "read-hits"}}
{"execute": "qom-set", "arguments": {"path": "/machine/peripheral/cxl-ssd0", "property": "stats-reset", "value": true}}

or in the HMP monitor with qom-get and qom-set. Event counters are cleared by stats-reset; gauges and totals keep their value. Descriptions are the ones -device <type>,help prints.

femu: NVMe controller​

Power loss trigger​

PropertyTypeDescription
simulate-power-lossboolWrite-only: setting true on a realized controller with power_loss=on drops the write buffer and resets the controller as a power cut would
plp-healthuint32with plp=on: the hold-up energy now, 0 to 65534 percent; the next check (at enable and every C6h minutes) fails the protection below 1, and a cut below 1 keeps nothing

ANA path state​

PropertyTypeDescription
ana-statestringwith ana=on: "g:s" sets the ANA state of group g (the namespace ID) through this controller: 1 Optimized, 2 Non-Optimized, 3 Inaccessible, 4 Persistent Loss; reading lists every group

Slow die​

PropertyTypeDescription
die-slowstringwith die_slow=on: "<ch>:<lun>:<pct>" sets the array time of one LUN to pct percent of nominal (100 to 10000), for ops booked from then on; reading lists the LUNs not at 100

femu-cxl-ssd: CXL Type-3 SSD​

Cache tunables (also accepted on -device)​

PropertyTypeDescription
cache-waysuint32Entries per cache set, non-zero and dividing cache-pages (1 is direct mapped); default 16, and a qom-set at run time writes back and rebuilds the cache
prefetch-degreeuint32Up to this many pages inserted into the cache after each demand miss, at most the media page count, with no NAND read; default 0, changeable with qom-set
prefetch-strideuint32Distance in pages from a missed page to the first prefetched page, at most the media page count; default 1, changeable with qom-set

Actions and control​

PropertyTypeDescription
der-ratiouint64Run time only: direct-map this fraction of pages, one of 0, 50, 75, 90, 95, 97, 98, 99, 995 (99.5%), 999 (99.9%) or 100 percent; needs der other than off and no uncached ranges, and der=memslot refuses a ratio whose unmapped gaps outnumber the free aliases
control-commanduint64Run time only: writing runs that experiment control command with control-argument before qom-set returns; reading gives the last command
control-argumentuint64Argument for the next control-command write; reading gives the last argument used, which a Get LSA control command also sets
control-statusuint64Read-only result of the last control command: 0 success, 1 error, 2 a Get LSA command still queued
flush-cacheboolWrite-only: true revokes direct mappings, writes dirty pages back, drops unpinned pages and waits for the modelled media time
stats-resetboolWrite-only: true copies the counters to the last-* properties, then clears the event counters
fast-loadboolAccesses skip only their wait for the modelled media time; the FTL, cache and counters still run. For warmup and loading, not for measurement. Setting false does not wait for the queued NAND work (see nand-idle-ns); default off, changeable with qom-set
fast-load-drain-nsuint64Read-only: the NAND backlog, in ns from when fast-load last went to false, including device DMA work queued before the switch; the switch does not wait for it. At least 1 until that work is booked
fast-load-switch-nsuint64Read-only: ns the last setting of fast-load to false took inside the device, for checking that the switch does not wait for the backlog; 0 before the first
nand-idle-nsuint64Read-only: ns until the NAND timelines and queued NAND work are idle, 0 when idle; poll it after fast-load=false before measuring. Never blocks

Cache counters​

PropertyTypeDescription
cache-entriesuint64Read-only gauge: pages resident in the cache, pinned ones included
cache-hitsuint64Read-only event counter: MMIO page lookups that found a resident page
cache-missesuint64Read-only event counter: MMIO page lookups that missed, including accesses with no cache
read-hitsuint64Read-only event counter: cache-hits caused by reads
read-missesuint64Read-only event counter: cache-misses caused by reads
write-hitsuint64Read-only event counter: cache-hits caused by writes
write-missesuint64Read-only event counter: cache-misses caused by writes
cache-insertsuint64Read-only event counter: pages admitted by demand misses, prefetch and PIN fills
cache-evictionsuint64Read-only event counter: pages the replacement policy removed, including those a flush or a cache-ways change drops
prefetch-insertsuint64Read-only event counter: pages inserted by prefetch

Snapshot counters​

PropertyTypeDescription
last-read-hitsuint64Read-only: read-hits at the last stats-reset or control command 1
last-read-missesuint64Read-only: read-misses at the last stats-reset or control command 1
last-write-hitsuint64Read-only: write-hits at the last stats-reset or control command 1
last-write-missesuint64Read-only: write-misses at the last stats-reset or control command 1
last-insertsuint64Read-only: cache-inserts at the last stats-reset or control command 1
last-evictionsuint64Read-only: cache-evictions at the last stats-reset or control command 1
last-entriesuint64Read-only: cache-entries at the last stats-reset or control command 1
last-prefetch-insertsuint64Read-only: prefetch-inserts at the last stats-reset or control command 1

Media counters​

PropertyTypeDescription
media-time-nsuint64Read-only: total modelled media time in ns returned by FTL requests, including contention
media-readsuint64Read-only: page reads the FTL performed for cache fills, uncached reads and PIN fills, not counting reads that cylon-first-touch-program turned into programs; stays 0 with ftl=off
media-writesuint64Read-only: user page programs counted by the FTL, garbage collection copies excluded, refreshed at each media request of this device, so writes from a linked NVMe controller appear after the next one
media-fulluint64Read-only: NAND programs that found no free page after garbage collection; the program is not timed but does not stop the eviction or insert, and the first one reports an error; the over-provisioning rule keeps it at 0, stats-reset keeps it, and a measurement is valid only while it is 0
gc-stallsuint64Read-only: media requests, linked NVMe and device DMA ones included, that waited for timed forced garbage collection to free a line; refreshed with media-writes; stats-reset keeps it
gc-stall-nsuint64Read-only: total ns from the start of those requests to the end of the collection they waited for, on every LUN; stats-reset keeps it
gc-stall-max-nsuint64Read-only: the longest of those waits in ns; one over a second warns once per device; stats-reset keeps it
dma-accessesuint64Read-only: accesses made inside another device's MMIO handler or bottom half, typically its DMA; served without waiting, they never fill the cache and are not cache hits or misses
dma-media-opsuint64Read-only: media operations queued for dma-accesses to uncached pages, one per run of consecutive accesses to a page within one MMIO handler or bottom half, plus one per run of writes to a page whose write-back is in progress; nobody waits for them; stays 0 with ftl=off
dma-media-time-nsuint64Read-only: modelled media time of dma-media-ops, not part of media-time-ns; a refused program counts in media-full

Direct mapping counters​

PropertyTypeDescription
der-activeboolRead-only: whether direct mapping is available on this device
der-probesuint64Read-only: probe attempts, one per realize with der=cylon
der-mappeduint64Read-only gauge: pages currently mapped for direct guest access
der-remapsuint64Read-only: direct page mappings installed
der-revocationsuint64Read-only: direct page mappings removed
der-quiet-revocationsuint64Read-only: Cylon revocations of entries whose accessed bit was clear, done without a TLB flush
der-replacementsuint64Read-only: memslot aliases displaced by a hotter page
der-fallbacksuint64Read-only: refused direct mapping attempts and device disablements
der-emul-exitboolRead-only: whether the host kernel returns Cylon accesses it cannot emulate to FEMU (KVM_CAP_CYLON_FAULT_EXIT)
der-emul-v2boolRead-only: whether version 2 of the Cylon fault exit is on for the VM (cylon-never-emulate)
der-fault-readsuint64Read-only: version 2 exits for a data read of a cold page; stats-reset keeps it
der-fault-writesuint64Read-only: version 2 exits for a data write to a cold page; stats-reset keeps it
der-fault-fetchesuint64Read-only: version 2 exits for an instruction fetch from a cold page; stats-reset keeps it
der-fault-page-walksuint64Read-only: version 2 exits for a guest page walk that read a cold page-table page; stats-reset keeps it
der-fault-emulateduint64Read-only: version 2 pages handed back to KVM's emulator for a data access: only pages that the caching API keeps uncached (uncached range, every way of the set pinned); stats-reset keeps it
der-fault-unprotecteduint64Read-only: version 2 protections released early because the instruction already held 64 pages; stats-reset keeps it
der-fault-conflictsuint64Read-only: fills refused because pages that the same instruction filled hold every way of the set; the page maps outside the cache (der-fault-overflows); stats-reset keeps it
der-fault-overflowsuint64Read-only: pages mapped without a cache way for one instruction: in version 2 every page that cannot keep a way, in version 1 an instruction the emulator cannot run whose pages do not fit in their set; stats-reset keeps it
der-fault-forceduint64Read-only: of der-fault-overflows, pages that the caching API keeps uncached, mapped because a guest page walk or an event delivery touched them, which the emulator cannot serve; stats-reset keeps it
der-fault-deliveriesuint64Read-only: version 2 exits made while the CPU delivered an interrupt or exception (KVM_CYLON_FAULT_DELIVERY; host kernel candidate 3); stats-reset keeps it
der-fault-marker-refuseduint64Read-only: version 2 emulation markers that FEMU refused to write because the rule allows them only for data accesses to uncached pages; nonzero is a defect, and the exit stops the VM; stats-reset keeps it
der-revoke-flushesuint64Read-only: TLB flushes that Cylon full revocations attempted (two, or one when KVM revoked every page first or the slot is deleted next), shared by every page a revocation takes; flushes after a KVM revocation found outside a full revocation are not counted; stats-reset keeps it
der-revoked-aheaduint64Read-only: version 2 pages whose mapping a revocation took before their own eviction; they stay cached; stats-reset keeps it
der-ahead-remapsuint64Read-only: of der-revoked-ahead, pages accessed and mapped again before their eviction; stats-reset keeps it
der-fault-bqluint64Read-only: Cylon fault exits that FEMU served under the BQL instead of the CXL lock alone (the first exit after an invalidation, a route through a switch or to another device); stats-reset keeps it
der-emul-fillsuint64Read-only: exits for an access KVM could not decode that FEMU served by a fill and a mapping, repeats and cache hits included; not instructions or unique pages; stats-reset keeps it
der-emul-fetch-fillsuint64Read-only: the der-emul-fills exits for code the guest executed from an unmapped page; stats-reset keeps it
der-emul-failuresuint64Read-only: such exits FEMU could not serve (unmappable page or no progress); each one stops the VM; stats-reset keeps it

Caching API counters​

PropertyTypeDescription
cca-commandsuint64Read-only event counter: caching API commands completed, whatever their status
cca-errorsuint64Read-only event counter: caching API commands completed with a non-zero status
cca-pinneduint64Read-only gauge: pages currently pinned in the cache
cca-uncacheduint64Read-only gauge: pages currently in caching API uncached ranges
cca-pin-fillsuint64Read-only event counter: pages PIN read from the media
cca-writebacksuint64Read-only event counter: dirty pages programmed by caching API commands
cca-droppeduint64Read-only event counter: resident pages dropped by INVALIDATE and CACHE_DISABLE
cca-pinned-set-missesuint64Read-only event counter: misses served from the media because every way of the set is pinned

Other counters​

PropertyTypeDescription
invalidationsuint64Read-only: generation count bumped by PCI configuration writes, component register writes, every mailbox command other than a control Get LSA, and reset; each revokes all direct mappings
nvme-dropsuint64Read-only: resident pages a linked NVMe write, copy or deallocate dropped or cleaned
log-droppeduint64Read-only: statistics appends refused, I/O logs closed at log-limit and SPT dumps truncated