Runtime properties and counters
Mirrored from the FEMU repository
This page is hw/femu/docs/reference/runtime-properties.md at FEMU 39a55eeb6 (2026-10-02), 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
| Property | Type | Description |
|---|---|---|
simulate-power-loss | bool | Write-only: setting true on a realized controller with power_loss=on drops the write buffer and resets the controller as a power cut would |
femu-cxl-ssd: CXL Type-3 SSD
Cache tunables (also accepted on -device)
| Property | Type | Description |
|---|---|---|
cache-ways | uint32 | Entries 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-degree | uint32 | Up 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-stride | uint32 | Distance 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
| Property | Type | Description |
|---|---|---|
der-ratio | uint64 | Run 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-command | uint64 | Run time only: writing runs that experiment control command with control-argument before qom-set returns; reading gives the last command |
control-argument | uint64 | Argument for the next control-command write; reading gives the last argument used, which a Get LSA control command also sets |
control-status | uint64 | Read-only result of the last control command: 0 success, 1 error, 2 a Get LSA command still queued |
flush-cache | bool | Write-only: true revokes direct mappings, writes dirty pages back, drops unpinned pages and waits for the modelled media time |
stats-reset | bool | Write-only: true copies the counters to the last-* properties, then clears the event counters |
Cache counters
| Property | Type | Description |
|---|---|---|
cache-entries | uint64 | Read-only gauge: pages resident in the cache, pinned ones included |
cache-hits | uint64 | Read-only event counter: MMIO page lookups that found a resident page |
cache-misses | uint64 | Read-only event counter: MMIO page lookups that missed, including accesses with no cache |
read-hits | uint64 | Read-only event counter: cache-hits caused by reads |
read-misses | uint64 | Read-only event counter: cache-misses caused by reads |
write-hits | uint64 | Read-only event counter: cache-hits caused by writes |
write-misses | uint64 | Read-only event counter: cache-misses caused by writes |
cache-inserts | uint64 | Read-only event counter: pages admitted by demand misses, prefetch and PIN fills |
cache-evictions | uint64 | Read-only event counter: pages the replacement policy removed, including those a flush or a cache-ways change drops |
prefetch-inserts | uint64 | Read-only event counter: pages inserted by prefetch |
Snapshot counters
| Property | Type | Description |
|---|---|---|
last-read-hits | uint64 | Read-only: read-hits at the last stats-reset or control command 1 |
last-read-misses | uint64 | Read-only: read-misses at the last stats-reset or control command 1 |
last-write-hits | uint64 | Read-only: write-hits at the last stats-reset or control command 1 |
last-write-misses | uint64 | Read-only: write-misses at the last stats-reset or control command 1 |
last-inserts | uint64 | Read-only: cache-inserts at the last stats-reset or control command 1 |
last-evictions | uint64 | Read-only: cache-evictions at the last stats-reset or control command 1 |
last-entries | uint64 | Read-only: cache-entries at the last stats-reset or control command 1 |
last-prefetch-inserts | uint64 | Read-only: prefetch-inserts at the last stats-reset or control command 1 |
Media counters
| Property | Type | Description |
|---|---|---|
media-time-ns | uint64 | Read-only: total modelled media time in ns returned by FTL requests, including contention |
media-reads | uint64 | Read-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-writes | uint64 | Read-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-full | uint64 | Read-only: accesses whose NAND program found no free page; that program is not timed and the access completes uncached, though a fill read already issued is charged; stats-reset keeps it, and a measurement is valid only while it is 0 |
Direct mapping counters
| Property | Type | Description |
|---|---|---|
der-active | bool | Read-only: whether direct mapping is available on this device |
der-probes | uint64 | Read-only: probe attempts, one per realize with der=cylon |
der-mapped | uint64 | Read-only gauge: pages currently mapped for direct guest access |
der-remaps | uint64 | Read-only: direct page mappings installed |
der-revocations | uint64 | Read-only: direct page mappings removed |
der-quiet-revocations | uint64 | Read-only: Cylon revocations of entries whose accessed bit was clear, done without a TLB flush |
der-replacements | uint64 | Read-only: memslot aliases displaced by a hotter page |
der-fallbacks | uint64 | Read-only: refused direct mapping attempts and device disablements |
Caching API counters
| Property | Type | Description |
|---|---|---|
cca-commands | uint64 | Read-only event counter: caching API commands completed, whatever their status |
cca-errors | uint64 | Read-only event counter: caching API commands completed with a non-zero status |
cca-pinned | uint64 | Read-only gauge: pages currently pinned in the cache |
cca-uncached | uint64 | Read-only gauge: pages currently in caching API uncached ranges |
cca-pin-fills | uint64 | Read-only event counter: pages PIN read from the media |
cca-writebacks | uint64 | Read-only event counter: dirty pages programmed by caching API commands |
cca-dropped | uint64 | Read-only event counter: resident pages dropped by INVALIDATE and CACHE_DISABLE |
cca-pinned-set-misses | uint64 | Read-only event counter: misses served from the media because every way of the set is pinned |
Other counters
| Property | Type | Description |
|---|---|---|
invalidations | uint64 | Read-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-drops | uint64 | Read-only: resident pages a linked NVMe write, copy or deallocate dropped or cleaned |
log-dropped | uint64 | Read-only: statistics appends refused, I/O logs closed at log-limit and SPT dumps truncated |