Skip to main content

Log pages and counters

Mirrored from the FEMU repository

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

How to read FEMU's own counters from the guest. Device properties are in properties.md, and the counters of femu-cxl-ssd are QOM properties listed in runtime-properties.md.

Vendor log page C0h​

nvme get-log /dev/nvme0 --log-id=0xc0 --log-len=512 -b returns the emulator's own media counters, little-endian at these offsets (FemuStatsLog in hw/femu/nvme.h):

OffsetSizeField
04Write amplification factor, scaled by 1000: (pages programmed + pages relocated by garbage collection + pad pages at offset 264 + translation pages at offset 280) x 1000 / pages the host asked to program
88Pages the host asked to program
168Data pages relocated by garbage collection
248Pages actually programmed
328Reads of the most-read block since its erase
408Lines rewritten because of read stress (reclaim units under FDP)
488Lines rewritten because of retention age (reclaim units under FDP)
568Host read pages the write buffer saw
648Of those, pages the buffer held
728Host write pages the write buffer saw
808Of those, pages the buffer already held
888Log-block switch merges (mapping=hybrid only)
968Log-block full merges
1048Erases charged to log-block merges
1128Blocks in service past their erase limit (blk_pe_limit)
1208Worn-out blocks taken out of service
1288Lines taken out of service (under FDP, the lines of retired reclaim units)
1368Lines moved by static wear levelling (wl_spread)
1448Pages those moves copied (also counted at offset 16)
1528NAND pages host writes covered only in part (a device reads such a page to program it again; FEMU does not charge that read)
1608Plane reads charged to NAND (a multi-plane command counts each plane)
1688Plane programs
1768Plane erases
1848Energy in uJ: the three counts above times energy_read_nj, energy_prog_nj and energy_erase_nj
1928Host writes that waited for forced garbage collection to make room
2008Forced collection passes run inside those writes
2088Host writes that emptied a full write buffer to make room
2168Completions held because the host's completion queue was full (summed over pollers)
2248Pages paced collection copied (gc_pace; also counted at offset 16)
2328Lines paced collection finished, freed or retired
2408Paced lines the forced pass or the budget finished in one pass
2488Pages collection moved by copyback on their die (gc_copyback; also counted at offset 16)
2568Lines (reclaim units under FDP) rewritten for the open-block read limit (pd_open_read_limit); not counted at offset 40
2648Pages programmed with pad data to close lines or units left open (pd_open_close_sec)
2728Lines or units those pads closed
2808Translation pages programmed (mapping=dftl without FDP): dirty CMT evictions, published changes, and translation pages that collection, refresh or wear levelling moved
2888Translation pages read from flash (mapping=dftl without FDP)
2968Host page reads with at least one read retry (rber_ppb)
3048Read-retry page reads (rber_ppb)
3128Host page reads with a soft decode, passed or failed (rber_ppb)
3208Host page reads past the decode limit: soft decode failed, or failed with it off (rber_ppb)
3288Blocks an erase failure killed (erase_fail_ppm); each one also counts as a grown bad block when it leaves service

Bytes 4-7 and 336-511 are reserved and read as zero. The counters are summed over the controller's bbssd, CSD and KV namespaces (the block read count is the largest of them); other modes leave them zero. The write amplification factor stays zero until the host has written a page. Bytes 8 and 24 are equal when no write buffer is configured; a buffer that absorbs repeated writes to one page makes the factor drop below 1.

A KV namespace with kv_index=lsm adds its merge programs to offset 24. It adds the meta pages that value GC moves to offset 16. Thus its factor includes the index.

With value packing (kv_pack=on, the default), a KV namespace counts host data at offset 8. The count is the value bytes of its Stores, in whole pages, rounded down. At offset 24 it counts each packed page and each whole value page it programs. Thus the factor is programmed pages over host data, and it drops below 1 when the open page drops overwritten values. With kv_pack=off, offset 8 counts the pages of each value, as before (KV value packing).

They were previously written into the SMART log from byte 192, which NVMe Base 2.0 assigned to the composite temperature times, the temperature sensors and the thermal transition counts.

The host can read the same page counters per namespace without the guest, together with the line states, through the QMP command query-femu.

The same counters can be captured through the standard Telemetry Host-Initiated log (07h): nvme telemetry-log /dev/nvme0 --output-file=telemetry.bin takes a snapshot and saves it. Data Area 1 is one 512-byte block laid out as above, and it stays as captured until the next capture. The Controller-Initiated log (08h) holds a capture that a SMART warning or a temperature event started.

With telemetry_da4=on and ETDAS set in Host Behavior Support, each capture also has Data Area 4: one 512-byte block per namespace, in the same layout. Block 1 + NSID holds that namespace; the host command counters stay zero there. Realize refuses telemetry_da4 with FDP, whose namespaces share one FTL.

block 0 1 2 3 1 + NN
[header] [controller] [nsid 1] [nsid 2] ... [nsid NN]
DA1, DA2, DA3 end at block 1; DA4 ends at block 1 + NN

The Maximum Created Data Area field (MCDA, Get Log Page CDW10 bits 11:9) of log 07h then works too: 1 to 3 creates no Data Area 4.

nvme get-log /dev/nvme0 --log-id=0 --log-len=1024 -b lists every log page the controller answers, four bytes per identifier with bit 0 set for the ones it supports, so this page can be discovered rather than assumed.

Computational programs and reachability​

A CSD controller with csd_slm_size or csd_cp answers these pages (CP and SLM):

LIDPageCSINSIDContent
1AhReachability Groupsanyanyone group, RGID 1, with every namespace; LSP bit 0 (RGO) leaves out the NSIDs
1BhReachability Associationsanyanyone association, RASID 1, RAC 01h, holding RGID 1; LSP bit 0 (RAO) leaves out the RGIDs
82hProgram List04hthe compute namespace16 descriptors, one per PIND
83hDownloadable Program Types List04hthe compute namespaceC3h with csd_program_dir; C1h also with uBPF
84hMemory Range Set List04hthe compute namespaceRSID 0h, then every set by RSID; LSP bit 0 (RIO) leaves out the ranges

Both change counts of 1Ah and 1Bh stay 0h, because the groups never change.

Asynchronous events​

The controller completes an outstanding Asynchronous Event Request when one of these happens:

EventRaised whenLog page it names
SMART temperature warningthe host has enabled it with Async Event Configuration and the reported temperature (temperature, in Kelvin, default 323, which is 50 C) is at or above the over threshold (default 343 K, the warning temperature WCTEMP) or at or below the under threshold (default 0); with the thermal model on, also when the modelled temperature crosses oneSMART / Health (02h)
Errorthe host writes a doorbell that does not exist, or a value past the end of its queueError Information (01h)
Namespace Attribute Changedwith ns_mgmt=on, a namespace is attached, detached, deleted or formatted, and the host enabled the noticeChanged Namespace List (04h)
SMART spare below threshold (02h), reliability (00h)with blk_pe_limit: the spare falls below 20, the first block stays in service past its limit, or the media goes read-only; bit 0, 2 or 3 of Async Event Configuration enables eachSMART / Health (02h)
Zone Descriptor Changedan injected write fault (err_write_fail_ppm) made a ZNS zone read only, and the host enabled Zone Descriptor Changed notices (bit 27)Changed Zone List (BFh)

An event of a given type is reported once and then held back until the host reads the log page it named without Retain Asynchronous Event (RAE), so the same condition is not reported again before the host has looked. A controller reset drops anything outstanding. hw/femu/scripts/aer-probe.c checks the temperature path from inside the guest:

gcc -O2 -o aer-probe femu-scripts/aer-probe.c # inside the guest
sudo ./aer-probe /dev/nvme0

End of life​

With blk_pe_limit and eol_read_only (on by default), the media goes read-only when a worn-out block has no replacement. These fields then show it:

WhereFieldValue
SMART / Health (02h)Critical Warning bit 3 (All Media Read-Only)1
SMART / Health (02h)Available Spare0
SMART / Health (02h)Endurance Group Critical Warning Summary (byte 6)bits 0, 2 and 3 of the endurance group's warning; needs a femu-subsys
Endurance Group Information (09h)Critical Warning bit 3 (Endurance Group Read-Only)1
Identify Namespace, CNS 00h byte 99 and CNS 08h byte 8NSATTR bit 0 (Currently Write Protected)1
Asynchronous eventSMART, information 00h (reliability), log page 02honce, if bit 3 of Async Event Configuration is set
Persistent Event log (0Dh)hardware error event, code 06h (critical warning)once, with the warning byte when the media went read-only

Writes fail with Attempted Write to Read Only Range (status 182h, DNR). The same holds for Write Zeroes, Write Uncorrectable, Copy and a deallocating Dataset Management. The NVM Identify Controller (CNS 06h, CSI 00h) reports WZSL in byte 1, equal to MDTS, and VER 1.1 in bytes 23:20. ONCS bit 3 is clear, so WZSL is a hard limit.

Thermal model​

With thermal_tau_ms set, the composite temperature in the SMART log follows the NAND work instead of staying at temperature. Every constant comes from the user; FEMU has no built-in figures.

power (mW) = idle_mw + NAND energy since the last step / the step
(plane reads, programs, erases x energy_*_nj; bbssd, CSD, KV)
target (K) = temperature + power x thermal_r / 1000 (thermal_r: mK per mW)
every thermal_step_ms of virtual time:
T = target + (T - target) x exp(-step / thermal_tau_ms)
SMART temperature = T rounded to a Kelvin
T reaches the over threshold, or falls to the under threshold:
SMART critical warning bit 1, Persistent Event log entry,
and one SMART temperature event if the host enabled it
  • The clock is QEMU's virtual clock, so a paused VM does not cool. NAND work that FEMU does while the VM is paused counts in the first step after it.
  • The model does not throttle I/O, and the SMART time-over-threshold fields stay 0.
  • One event is raised each time the condition starts while the host has temperature events enabled, including when it enables them during an excursion. A SMART read without RAE discards queued SMART events, so an excursion that ends and starts again before the host reads the log is not reported twice.
  • Refused with namespace management, shared namespaces, cxl_ssd and -icount. thermal_tau_ms needs thermal_r; thermal_step_ms is 1 to 60000.

Power Measurement (log 25h, feature 25h)​

With power_meas=on the controller reports the Power Measurement capability (Base 2.3, 8.1.19.1): CTRATT bit 21, log page 25h and feature 25h. The power is an estimate from the same energy figures as the thermal model, so the log sets the Estimated Power Flag (EPF).

Set Features 25h, ACT 1h (Start), PMTS 0h:
PMC := 0, PMGN := PMGN + 1, PME := 1, SMTR := SMT
every 1 s of virtual time while PME = 1:
P = idle_mw + NAND energy booked in the interval / the interval
PMC + 1; average and maximum of P; MIPWRT := the Timestamp now
SMT minutes of intervals, or Set Features 25h, ACT 0h (Stop):
PME := 0, SMTR := 0, SMTS := the Timestamp now
Get Features 25h, Dword 0: SMTR (31:16), PMGN (15:8), PME (0)
  • The only measurement type is 0h, the NVM subsystem total power. PMTS 1h to Fh and ACT values other than 0h and 1h fail with Invalid Field.
  • Power fields use scale 01b (0.0001 W) while the value fits in 16 bits, else 10b (0.01 W). With PMC 0 they read 0 in scale 01b. IPWRPE is 255 (not reported).
  • There is no histogram: NPHDS and NPHD are 0, PHBS is 250, PHDS is 8.
  • IPMSR is 1 s (one sample an interval); MSMT is 0, so any SMT is taken.
  • Intervals start on fixed one-second boundaries from Start. A tick that fires after a boundary counts each whole interval it passed and spreads their energy evenly.
  • Feature 25h takes NSID 0 only; log 25h takes NSID 0 or FFFFFFFFh. Other values fail with Invalid Field.
  • Energy is booked when the FTL books an operation, so an interval can carry the energy of an operation that ends in the next one.
  • The state stays across a controller reset and a power cut, and collection does not stop at a shutdown, so NCPDF stays 0.
  • One controller per femu-subsys. Refused with persist_file, namespace management, shared namespaces, cxl_ssd and -icount. The Power Threshold feature (24h) is not offered.

Persistent Event log retention​

The Persistent Event log (0Dh) lives in memory and is lost when QEMU exits. Set pel_file=/absolute/path/events.pel on a femu device to keep it across QEMU runs. A missing file starts an empty history. A corrupt or incompatible file refuses device creation and is left unchanged.

The file holds the encoded events, the log generation and the power cycle count. Each realize adds one power cycle, a power-on event and a SMART snapshot. The PEL header's power cycle count (PWRCC), the Controller Power Cycle and SMART Power Cycles all use the retained count. Reporting contexts, the other SMART counters, namespace data and power-on hours are not retained.

The file is written on the main loop after events and generation changes, and again at controller reset, device removal and normal process exit. Each write goes to a temporary file in the same directory, which is synced, renamed over the old file, and followed by a sync of the directory. At normal exit, event collection closes under the log mutex before the last write: events added before that point are saved, and later ones, including completions of outstanding I/O, are dropped. The exit path does not wait for the pollers, whose MMIO DMA may need the main thread's lock. Killing QEMU abruptly can lose changes still queued for the main loop. A write error is printed to stderr, and the next event or lifecycle save tries again.

Use one file per device and one QEMU writing it. The file is not a way to share a log between devices or to migrate one.