The BlackBox FTL
This page is hw/femu/docs/design/ftl.md at FEMU d8b29b1e0 (2026-11-16), licensed GPL-2.0-or-later. Send corrections to the FEMU repository.
This chapter describes the flash translation layer (FTL) behind BlackBox mode
(femu_mode=1): how it maps logical pages to NAND pages, how it organises
NAND into lines and write pointers, how it collects garbage, and how its
write buffer, read cache, wear and refresh models work. It is written for
readers who want to know what the model does, where its time goes, and how
to change it. To run the mode, read the BlackBox guide
first; this chapter does not repeat its launch and guest steps.
The code lives in hw/femu/bbssd/. The same FTL serves CSD namespaces, which
build it through the same ssd_init(). KV namespaces call ssd_init() for
the geometry and NAND timing but run their own key-value FTL. A
femu-cxl-ssd builds a private instance on its own worker thread.
NAND operation timing (per-LUN timelines, the channel bus, suspend, ECC tiers) is the subject of the NAND timing chapter in this directory, and of the timing model. This chapter covers what the FTL asks of the NAND, not how long each operation takes.
Place in the hierarchy
guest NVMe driver
| SQ doorbell
v
+---------------------------+ copies the payload between guest memory
| femu-poller thread(s) | and the host memory backend, then hands
| nvme_rw(), nvme_dsm(),...| every I/O request to the FTL ring
+---------------------------+
| to_ftl[i] ^ to_poller[i]
v |
+---------------------------------------------------------------+
| FEMU-FTL-Thread: femu_ftl_thread() -> bb_ftl_process_req() |
| |
| +-------------+ +--------------+ +----------------------+ |
| | mapping | | write buffer | | read cache | |
| | page, dftl, | | (LPNs, LRU) | | (LPNs, timing only) | |
| | hybrid,fast | +--------------+ +----------------------+ |
| +-------------+ |
| +---------------------------------------------------------+ |
| | line management, write pointers, GC, read reclaim | |
| +---------------------------------------------------------+ |
+---------------------------------------------------------------+
| ssd_advance_status(): one read, program or erase
v
+---------------------------------------------------------------+
| NAND media layer (hw/femu/nand/nand-media.c) |
| per-LUN next-available times, optional channel bus |
+---------------------------------------------------------------+
Two things follow from this picture.
- The FTL models time and placement, not data. The poller copies the
payload to the host memory backend before the request reaches the FTL. The
FTL tracks which NAND page each logical page would occupy and how long each
operation takes, but it never stores the payload. The one exception is the
power-loss model (
power_loss=on), which runs the data copy on the FTL thread and keeps undo copies of buffered pages; see Power loss. - The FTL returns a duration. Each handler returns the time the request
spends in the device, measured from the request's arrival time
stime. The FTL thread adds it toreq->expire_time, and the poller completes the request when the host clock reaches that time.
The FTL thread and its queues
poller 1 FEMU-FTL-Thread poller 1
+---------+ to_ftl[1] +-------------------------+ to_poller[1] +-----------+
| SQ scan |------------->| |------------->| pq[1] |
+---------+ (rte_ring) | for i in 1..nr_pollers | | ordered by|
poller 2 | dequeue one request | | expire_ |
+---------+ to_ftl[2] | lat = femu_ftl_ | to_poller[2]| time; CQE |
| SQ scan |------------->| process_req(req) |------------->| posted |
+---------+ | expire_time += lat | | when now |
... | enqueue to_poller[i] | | >= expire |
+-------------------------+ +-----------+
|
| after every request:
v
background GC check (one victim)
- One thread per controller.
femu_ftl_thread()inhw/femu/femu.cstarts at realize when a namespace is bbssd, ZNS or CSD (or the controller shares a bbssd subsystem), after every namespace is built. It is joined at device removal. - One pair of rings per poller. Each poller
ifeedsto_ftl[i]and readsto_poller[i]. The FTL thread visits the rings in turn and takes one request from each non-empty ring per pass, so no poller can starve another. - Every I/O command goes through the ring, including Flush, Dataset
Management and commands that already failed in the I/O layer. A failed
request is not processed:
bb_ftl_process_req()returns 0 for it, and the poller posts the carried error status. - No lock protects the FTL state. The FTL thread is the only writer of
the mapping, the lines, the write buffer and the caches. With Streams on,
each request runs under
n->streams_lock; on a shared subsystem namespace it runs under the subsystem'sns_lock. An NVMe controller linked to afemu-cxl-ssdruns its requests on its own FTL thread against the medium's FTL, under the medium's lock, which also serializes the medium's worker. - Admin commands that change FTL state pause the dataplane.
nvme_pause_pollers()waits until the FTL thread is outside a request (theftl_in_sweepflag), so the run-time switch (admin opcode 0xEF), the volatile write cache feature, Format and Sanitize change FTL state with nothing in flight.
bb_ftl_process_req() in hw/femu/bbssd/ftl.c dispatches on the opcode:
| Opcode | Handler | What the FTL does |
|---|---|---|
| Read | ssd_read() | translate each page; buffer hit, read cache hit or NAND read |
| Write | ssd_write() | foreground GC, read reclaim, then buffer or program each page |
| Write Zeroes | ssd_write_zeroes() | with the Deallocate bit: unmap; without it: program the range |
| Dataset Management | ssd_trim() | deallocate each range |
| Copy | ssd_copy() | read every source range, then write the destination |
| Compare, Verify | ssd_read() | read the range as a Read does, without the injected read faults; also after a miscompare, or a protection error of a Verify |
| Flush | ssd_buffer_destage(ssd, 0, ...) | program everything the write buffer holds |
| I/O Management Send | ssd_fdp_update_ruhs() | FDP only: update reclaim unit handles |
Read and Write latency is the largest per-page latency of the request: pages on different LUNs proceed in parallel, and pages on one LUN queue on its timeline. Copy issues the destination write when the slowest source read ends, so it costs that read plus the write. A source in a NoSSD namespace costs nothing, and a Copy into a NoSSD namespace charges no source read. After the opcode handler, the thread runs one background GC step if the device is past the background watermark (Triggers).
Data structures
All of the FTL's state hangs off struct ssd (hw/femu/bbssd/ftl.h), one
per bbssd or CSD namespace.
Physical page address
A struct ppa packs a NAND location into 64 bits:
63 62 51 50 44 43 40 39 32 31 16 15 0
+---+--------------+----------+------+----------+----------------+----------------+
|rsv| ch (12) | lun (7) |pl (4)| sec (8) | pg (16) | blk (16) |
+---+--------------+----------+------+----------+----------------+----------------+
The field widths bound the geometry: at most 4096 channels, 128 LUNs per
channel, 16 planes per LUN, 65536 blocks per plane, 65536 pages per block and
256 sectors per page. bb_check_geometry() refuses larger values, and also
refuses a geometry whose total sector count exceeds INT_MAX, because the
derived totals in struct ssdparams are int. The FTL always addresses
whole pages; the sec field is unused by the mapping.
NAND state
ssd->ch[nchs]
.next_ch_avail_time
.lun[luns_per_ch]
.next_lun_avail_time <- the timeline every NAND op is bound by
.pl[pls_per_lun]
.blk[blks_per_pl]
.vpc, .ipc valid and invalid page counts
.erase_cnt P/E cycles of this block
.read_cnt reads since the last erase
.pg[pgs_per_blk].status FREE, VALID or INVALID
A page goes FREE -> VALID when it is programmed (mark_page_valid()),
VALID -> INVALID when its logical page is overwritten, deallocated or moved
by a log-block merge (mark_page_invalid()), and back to FREE when its block
is erased (mark_block_free()). A page that line GC relocates stays VALID
until its block is erased. Closing a stream's line marks its unwritten pages
INVALID directly.
Mapping tables
maptbl: logical page -> physical page rmap: physical page -> logical page
(one struct ppa per logical page) (indexed by ppa2pgidx(), one u64 each)
LPN PPA pgidx LPN
+-----+--------------------------+ +------------------------+-----+
| 0 | ch0 lun0 pl0 blk7 pg3 |---------->| ch0 lun0 pl0 blk7 pg3 | 0 |
| 1 | UNMAPPED | | ch1 lun0 pl0 blk7 pg3 | 5 |
| 2 | ch3 lun1 pl0 blk2 pg0 | | ... | ... |
| ... | ... | | (stale copy) | INV |
+-----+--------------------------+ +------------------------+-----+
maptbl is the forward map and rmap the reverse map that GC uses to find
which logical page a valid physical page holds. Both have one entry per NAND
page (tt_pgs), 8 bytes each: 32 MiB apiece for the default 16 GiB geometry.
Every mapping scheme keeps these two tables as the source of truth.
Lines
typedef struct line {
int id; /* the block index this line spans */
int ipc, vpc; /* invalid and valid pages over the whole line */
size_t pos; /* slot in the victim priority queue, 0 if none */
uint64_t close_time; /* when the line filled; age-based policies */
uint64_t close_seq; /* order in which lines filled; the FIFO key */
uint64_t stream_tag; /* Streams: the stream whose data it holds */
bool reclaiming; /* being rewritten by read reclaim */
...
} line;
struct line_mgmt keeps a free list (a FIFO), a victim priority queue keyed
by valid page count (by close_seq under gc_policy=fifo), and a full list.
Address mapping
Figure: The four BBSSD mapping schemes (mapping=): the full page table, DFTL's cache of map pages, BAST's log block per data block, and FAST's shared log pool.
From LBA to logical page
ssd_lpn_range() turns an LBA range into a range of logical page numbers
(LPNs). A page is secsz * secs_per_pg bytes. The byte offset is the LBA
times the LBA size, plus the namespace's offset in the backend:
LPN = (backend_offset + slba * lba_size) / page_size
So a namespace's LPNs start where its data starts in the backend. A
controller with Namespace Management on uses offset 0, because each managed
namespace has a private FTL. A request whose last LPN is at or beyond
tt_pgs fails with LBA Out of Range.
Page mapping (mapping=page)
The default. translate() returns maptbl[lpn]. A write invalidates the old
physical page, if any, and points the LPN at the new one. A read of an LPN
with no mapping costs no NAND time.
DFTL (mapping=dftl)
DFTL keeps the page-level mapping on NAND in translation pages (TPs) and
caches the TPs in use in a cached mapping table (CMT). The flat maptbl
still answers every lookup. Without FDP the TPs also live on flash, in
hw/femu/bbssd/ftl-map-tp.c:
DRAM (power-loss protected) NAND
CMT: whole TPs, CLOCK, dirty bit TP lines (line kind LINE_TP),
GTD: tp -> page of its current copy written only by the TP pointer
pending: changed TPs with no CMT slot rmap of a TP page: tag | tp
host read/write of lpn, tp = lpn / (page_size / 8)
CMT hit --> no NAND cost; a write makes the slot dirty
CMT miss --> evict a slot by CLOCK
dirty victim --> program it at the TP pointer, GTD = new
--> read the GTD copy of tp (none: no read), fill the slot
- A TP holds
page_size / 8mappings, 512 on a 4 KiB page. Withmapping_cache_mbleft at 0 the CMT is 4 MiB: 1024 TPs, 2 GiB of logical space on a 4 KiB page. - The CMT caches whole TPs. This is a DFTL variant with a TP-granularity cache, as many real FTLs use. It is not the entry-granularity CMT of Gupta et al. (ASPLOS '09).
- Every change of a mapping reaches the TPs through one interface,
tp_note(). A cached TP gets dirty. Any other TP goes pending, and the FTL publishes it later with one read and one program for all its changes. - Collection publishes at the end of each victim. A paced victim publishes when it is empty, and its budget counts those programs. The end of each request publishes what is left.
- DSM Deallocate and Write Zeroes with Deallocate publish at the end of the command, and the command pays for it. A cached TP they changed only gets dirty. An uncached TP takes one program, and one read first when it has a flash copy. At the forced reserve the TP stays pending for a later publication. Write Zeroes without Deallocate translates each page as a write.
- Format and Sanitize discard every TP with no write-back: their pages go invalid, and the GTD, the CMT and the pending set empty. A CSD namespace takes neither command.
- Collection takes TP lines and data lines from one victim queue. It moves each valid page by its owner: a TP through the TP pointer and the GTD, a data page through the data path. A TP line never moves by copyback.
- A TP program never takes one of the free lines that forced collection keeps, except to move a TP line. A dirty eviction or a publication with no page leaves the TP dirty or pending. So a host command does not fail for lack of TP space.
- The mapping DRAM is modelled as capacitor-backed, as on enterprise SSDs.
The pending changes stand for a log of changes in that DRAM. The model does
not size it: in the worst case it holds one entry per logical page, and
mapping_cache_mbdoes not bound it. A power loss keeps the GTD, the CMT and the pending TPs. Flush and FUA need no extra metadata barrier; ordinary evictions still run.
Timing. Each translation has a ready time: the end of the TP read, or the start of the access when the TP needs no read.
read of lpn: |-- TP read (tp's LUN) --|-- data read (lpn's LUN) --|
write of lpn: |-- TP read --|
|------------ data program -------------| ends at the later
hot/cold on: |-- TP read --|------------ data program -------------|
- A read starts its media read when the translation is ready, on any LUN. Translations of different TPs in one command run in parallel.
- A write programs at once, since placement does not need the old mapping;
it ends when both are done. With
hot_cold_sep, placement reads the old mapping, so the program waits for the translation. - A CMT hit is ready when the fill of its slot ends. A dirty eviction starts after the fill of the victim, and runs in parallel with the read.
- A TP read waits for a program of the same TP that is still running.
Under FDP, TPs stay timing only. A miss reads a placeholder page on LUN
tp_id % tt_luns, and a dirty eviction programs one. That traffic counts
in no counter, and collection and deallocate cost no TP access.
Space. With TPs on flash, realize keeps lines for the live TPs of the
namespace, rounded up to whole lines, and for the TP pointer. Forced
collection keeps at least two free lines. So the largest size a geometry
exposes falls with mapping=dftl, and realize refuses a size without room.
Counters. map-write-pages and map-read-pages (query-femu, C0h bytes 280
and 288) count TP programs and reads. The write amplification factor adds
the TP programs:
WAF = (nand_write_pages + gc_write_pages + map_write_pages + pad pages)
/ host_write_pages
Log-block mapping: BAST (mapping=hybrid) and FAST (mapping=fast)
The two log-block schemes write every page through a separate LOG write
pointer and model the merges a log-block FTL has to run. Like DFTL, they use
maptbl for correctness, so a read always finds the newest copy. A logical
block (LBN) is pgs_per_blk consecutive LPNs.
hybrid (BAST): one log per logical block fast (FAST): one sequential log
plus a shared random-write pool
pool of 16 logs SW log: one LBN, in-order run
+--------+--------+-----+--------+ +--------------------------+
| LBN 12 | LBN 40 | ... | free | | LBN 7: off 0,1,2,... |
| used 9 | used 256 | | +--------------------------+
+--------+--------+-----+--------+ RW pool: 16 blocks of pages,
| | any LBN, dirty LBN list
| +-- full: merge +--------------------------+
| | LBN 3, LBN 90, LBN 12... |
+-- pool exhausted: merge the fullest +--------------------------+
| pool full: merge two
merge: | dirty LBNs per pass
written in order (offset i at slot i)? v
yes -> switch merge: erase the old random merge: relocate each
data block, no copies live page of those LBNs
no -> full merge: relocate each live SW log full in order:
page of the LBN to DATA space switch merge, one erase
- hybrid follows BAST (Kim et al. 2002): one log per logical block, from a pool of 16. Each program consumes a log slot, overwritten or not; neither an overwrite nor a deallocate frees a slot, only a merge does. After every programmed page, if a log is full or every log in the pool is taken, the fullest log is merged. A log written strictly in order switch-merges for the cost of one erase. Any other log full-merges: every live page of its LBN is read and programmed into DATA-class space, counted as GC writes. Hybrid counts its merges for log page C0h. The scheme models merge cost, not BAST's physical block placement: logs of different LBNs share physical lines, and line GC still runs underneath and can add copies.
- fast follows FAST (Lee et al. 2007): a single sequential-write log for an in-order run that starts at offset 0 of an LBN, and a shared pool of 16 blocks' worth of pages for everything else. When the pool fills (or the dirty-LBN list reaches its 4095 limit), a reclaim relocates the live pages of up to two dirty LBNs, and repeats on later writes until the pool is no longer full. A full in-order sequential log switch-merges with one erase. The sequential log is released only when it fills in order; a broken run keeps holding it, and later sequential runs go to the shared pool. FAST reclaims once per request, not once per page, and its merge counts are not exported.
Merge reads, programs and erases are charged to the request that triggered the merge, and the relocated pages count in the write amplification factor.
Choosing a scheme
mapping | Models | Extra cost charged | Extra write pointer | Counters |
|---|---|---|---|---|
page | a full page map in DRAM | none | none | none |
dftl | a page map on NAND with a cache of translation pages | translation page read on a miss, program on a dirty eviction, publication of the changes collection and deallocate make | TP (without FDP) | C0h bytes 280 and 288 |
hybrid | BAST log blocks | switch and full merges per log | LOG | C0h bytes 88 to 111 |
fast | FAST log blocks | bounded random merges, sequential switch merges | LOG | none exported |
Streams and FDP need page or dftl.
Lines, superblocks and write pointers
A line is a superblock
A line is the block with the same index on every plane of every LUN of every
channel. There are blks_per_pl lines, each nchs * luns_per_ch * pls_per_lun blocks wide. By default a write pointer fills a line in this
order: channel first, then LUN, then plane, then page. plane_first
changes it for bbssd and CSD, as described below.
ch0 ch1 ch2 ... ch7
lun0 pg0 [ 0 ] [ 1 ] [ 2 ] [ 7 ] numbers are the order in
lun1 pg0 [ 8 ] [ 9 ] [10 ] [15 ] which the write pointer
... hands out pages of line N
lun7 pg0 [56 ] [57 ] [58 ] [63 ] (one plane per LUN)
lun0 pg1 [64 ] [65 ] ...
...
lun7 pg255 [16383] -> line full, take the next
free line
Consecutive pages land on different channels, then different LUNs, so a large write or a burst of small ones spreads over the whole device. With several planes, the pointer sweeps every channel and LUN on plane 0, then on plane 1, and so on, before the page index moves on.
plane_first (bbssd and CSD without FDP, off by default) moves the plane
to the front: plane, then channel, then LUN, then page. Pages in a row then
fill the planes of one LUN, so with mp_program two pages in a row are one
multi-plane program. The cost is less spread for short writes.
2 channels x 1 LUN x 2 planes, one page row
default: ch0 pl0 [0] ch1 pl0 [1] ch0 pl1 [2] ch1 pl1 [3]
plane_first: ch0 pl0 [0] ch0 pl1 [1] ch1 pl0 [2] ch1 pl1 [3]
\___ one multi-plane program __/
Why there are several write pointers
Each write pointer holds one line open and appends to it. Data written through one pointer shares lines, so the lines die together or not. Keeping data of different lifetimes apart is what makes GC victims mostly invalid. The FTL has these pointers:
| Pointer | In struct ssd | Takes | Opened |
|---|---|---|---|
| data | wp | host writes (only first writes with hot_cold_sep=on), GC relocations and read reclaim (not with gc_frontier=on), wear levelling copies, merge relocations | at init |
| hot | hot_wp | overwrites of mapped pages, with hot_cold_sep=on | on first use |
| collection | gc_wp | GC relocations, read reclaim and retention refresh of untagged data, with gc_frontier=on | on first use |
| log | log_wp | every host write under hybrid or fast | on first use |
| stream | stream_wp[i] | writes of open stream i | on first use |
| stream GC | stream_gc_wp | relocated pages of a released stream | on first use |
| reclaim unit | per handle | FDP placement; see FDP | FDP init |
When a hot, log or collection pointer cannot get a line, the write falls
back to the data pointer. With gc_frontier=on, forced collection keeps at
least 2 free lines, one for each frontier, and read reclaim seals an open
collection line for any reason, as it does a translation page line. Every open pointer pins a line, so bb_check_capacity() adds
one reserved line per pointer the configuration can hold open
(Capacity).
Hot/cold separation
With hot_cold_sep=on and page or DFTL mapping, prepare_write() sends a
write to the hot pointer when its LPN is already mapped. An overwrite is the
cheapest predictor of another overwrite, so hot lines fill with pages that
are invalidated together. GC relocations go through the data pointer, so
pages that survive a collection join the cold data. The log-block schemes
ignore the setting, but the extra reserved line is still counted. FDP
refuses it.
Line state machine
+-------------------------------------------------+
| |
v |
+---------+ a write pointer takes it +----------+ |
init ---->| FREE |--------------------------->| OPEN | |
| (FIFO) | | (curline)| |
+---------+ +----------+ |
^ | | |
| last page | | |
| programmed, | | |
| all valid | | |
| v | |
| +--------+ | |
| | FULL | | last page programmed,
| | (list) | | some invalid
| +--------+ | |
| first invalidation | | |
| v v |
| +----------------+ |
| | VICTIM | |
| | priority queue | |
| | keyed by vpc | |
| +----------------+ |
| selected by gc_policy | |
| v |
| +-------------+ |
+-------------------------| COLLECTING | |
relocate valid pages, | in no list | |
erase every block +-------------+ |
|
read reclaim: FULL or VICTIM -> COLLECTING (reclaiming=true) ---+
Streams: a released stream's partly written OPEN line has its
free pages marked invalid and joins VICTIM (or FREE if empty)
An open line belongs to no list; invalidations only lower its valid count.
When a line fills, close_time and close_seq are set. The free list is a FIFO: lines are
taken from the head and returned to the tail. The FTL has no explicit wear
levelling; the FIFO spreads erases over the free lines.
Garbage collection
Figure: BBSSD line states and garbage collection: when a line moves between the free, written, full and victim sets, when background and foreground GC run, and how each gc_policy picks a victim.
The code is in hw/femu/bbssd/ftl-line-gc.c.
Triggers and watermarks
The two watermarks are stored as free-line counts:
gc_thres_lines = (int)((1 - gc_thres_pcent/100) * tt_lines)
gc_thres_lines_high = (int)((1 - gc_thres_pcent_high/100) * tt_lines),
at least 1 with hot_cold_sep, Streams, or a hybrid
or fast mapping (bb_gc_forced_lines())
The floor matters below 20 lines, where the default high watermark rounds to zero. A second write pointer can then take the last free line while the data pointer, which GC writes into, is nearly full, and GC would have nowhere to put a victim's pages (with Streams, GC refuses such a victim outright). One free line always holds a whole victim. The floor costs those small geometries one line of exposable capacity.
| Kind | When | Where | Victim filter | How many |
|---|---|---|---|---|
| Background | free lines <= gc_thres_lines | after every request that reaches the FTL without an error, any opcode | the chosen line must have at least 1/8 of its pages invalid | one line |
| Foreground (forced) | free lines <= gc_thres_lines_high | at the start of a write, and before every page that a write, a write-back of the buffer, or Write Zeroes without Deallocate programs | none | repeats until above the watermark or no victim |
Forced GC runs per page, not once per command: one command can program more lines than the watermark keeps free, and a collection that starts after the last line is gone has nowhere to move pages to.
A GC step returns -1 when there is no victim, when the background filter rejects it, or when the victim's valid pages cannot all be moved; the forced loop then stops. With Streams on, a step also fails when it frees nothing, because lines of distinct retired streams cannot be combined, or when the victim holds valid pages and no line is free.
Victim policies
gc_policy selects one entry of femu_ftl_policies[]:
gc_policy | Chooses | Cost per choice |
|---|---|---|
greedy | the line with the fewest valid pages: the top of the priority queue | O(log n) |
random | a uniformly random line of the queue, drawn from the seeded generator; a background step puts it back if it fails the 1/8 filter | O(log n) |
cost-benefit | the largest age x (1 - u) / 2u, with u = vpc / pgs_per_line and age = now - close_time, compared in 128-bit integers; a line with no valid pages always wins | O(n) scan |
fifo | the line that filled first (lowest close_seq), whatever its valid count: the top of the queue, which this policy orders by close_seq | O(1) to find, O(log n) to remove |
d-choice | the fewest valid pages among 4 queue slots drawn from the seeded generator; a slot can be picked twice | O(1) sample |
Only lines in the victim queue are candidates. A line that closed with every
page valid stays in the full list until something invalidates one of its
pages. Under fifo the queue is keyed by close_seq, which does not change
while a line is queued, so an invalidation lowers the valid count without
moving the line.
random, d-choice and the FDP gc_strategy=2 (random) draw from a
splitmix64 generator in each namespace's FTL (ftl_gc_rand()), seeded from
gc_seed (default 0). The same configuration, seed and command sequence pick
the same victims and give the same write amplification; give each run a
different gc_seed to vary it. The other policies use no random numbers.
cost-benefit still reads the host clock for line age, so its picks depend
on when commands arrive.
Collecting a line
do_gc(force)
|
v
victim = policy->select_victim_line(force) -- none? return -1
|
v
move: for ch, lun, pl, each page of block (ch, lun, pl, victim->id):
if VALID:
new = next page of the data pointer (stream pointer for
(takes a free line if it has none) Streams data)
none? requeue the victim, return -1
NAND read at the old page (GC_IO)
lpn = rmap[old]
maptbl[lpn] = new, rmap[new] = lpn
old page -> INVALID, rmap[old] = none
NAND program at the new page (GC_IO)
gc_write_pages++
|
v
erase: for ch in 0..nchs-1, lun in 0..luns_per_ch-1:
mark each plane's block free: erase_cnt++, read_cnt = 0
one multi-plane erase of the LUN's blocks (GC_IO, tplebsy between
planes)
|
v
line -> free list tail
The relocated page goes wherever the data pointer is, not to the victim's
LUN, unless gc_copyback is on (next section). Every valid page is moved
before any block is erased. If the data pointer runs out of lines part way, the victim goes
back to the victim queue (or the full list, if nothing was moved from a full
line) holding the pages it still has, and nothing is erased. The pages that
were moved are already invalid in the victim, so its counts stay true and a
later step moves only what is left. Writes that then find no line fail with
Capacity Exceeded. The watermark floor, per-page forced GC and the capacity
reserve keep a valid configuration from getting there.
Copyback (gc_copyback)
Copyback reads a page into the die's page register and programs it into another block of the same die and plane. The data never crosses the channel. It is off by default.
A copyback skips ECC. ECC decode and correction run in the controller, and the data of a copyback never reaches the controller. On a real SSD the bit errors of the page are not corrected, so they can add up over repeated copybacks:
off-chip move: die --tR--> page register --channel--> controller (ECC decode,
correct) --channel--> page register --tPROG--> die
copyback: die --tR--> page register --tPROG--> die
(no channel, no ECC: bit errors move with the data)
FEMU models no ECC decode and no bit errors, so in FEMU a copyback changes only timing. Two rules exist because a copyback skips ECC:
- A page whose read has extra ECC time (
ecc_step_nswear or retention tier) moves off-chip, so the controller would correct it. - Read reclaim and retention refresh always move off-chip. They rewrite data so that the controller corrects it.
By default the data pointer steps to the next die on every page (channel
fastest, then LUN, then plane), so a victim walked in its own order meets its
destination die only once in nchs x luns_per_ch x pls_per_lun moves. With
plane_first it stays on one die for pls_per_lun pages. With gc_copyback
on, line collection walks the victim in the order of the destination dies:
while the victim holds valid pages:
dst = next page of the destination pointer
src = next valid victim page on dst's channel, LUN and plane
else next valid victim page in reclaim order
same channel, LUN and plane, and zero extra ECC time --> copyback
otherwise --> read + program
| Move | Charged |
|---|---|
| Copyback, staged channel | src cmd/addr, tR, status and program cmd/addr, tPROG; no data phase |
| Copyback, no channel model | tR then tPROG on the die |
| Off-chip | the ordinary GC read (with data-out) and program (with data-in) |
- The walk changes only which victim page goes to which destination page. The line, the pointer and the pages moved stay the same, so wear levelling still fills the worn line exactly.
- The ECC rules above are timing rules: FEMU stores no bit errors, and nothing limits how often one page moves by copyback. A line queued for refresh that collection takes first also moves off-chip.
- FDP collection uses the same walk, with the pointer of the unit it writes. For a Persistently Isolated handle that is the handle's own collection unit. For an Initially Isolated one it is the current unit of the last handle.
- The later bus phases of a channel share a queue of 32 bookings. A burst of collection fills it, and the channel is then held to the end of each new phase, as for an off-chip burst. Copyback books one window per move, where an off-chip move books two.
- An off-chip GC program does not wait for its own read; copyback chains the
two. The saving shows in the channel time, with
pg_xfer_latset. - Log page C0h offset 248 counts the pages moved by copyback, which offset 16 also counts.
Refused with gc_pace (its steps keep a cursor in reclaim order),
pe_suspend (a suspended read would not move the booked program command),
the hybrid and fast mappings (they merge), cxl_ssd, ns_mgmt and shared
namespaces (their FTL comes from another device), and namespace_modes.
How GC time is charged
GC operations enter the NAND model with stime = 0, which the media bridge
replaces with the current host time. Each one moves its LUN's
next-available time forward, and the latency it returns is discarded. GC
time therefore reaches the host only through the LUN timelines: a later host
read or program on a LUN that GC is using starts when GC is done with it.
LUN 3 timeline |--host W--|--GC R--|--GC W--|--GC W--|--erase-------|--host R--|
^ ^
GC starts at "now" a read that
arrived here
waits until
the erase ends
- In background GC the request that triggered it has already been timed, so it pays nothing. The requests that follow pay, on the LUNs GC occupied.
- In foreground GC the write itself waits, because its own programs queue behind the GC operations on the same LUNs.
- Admin opcode 0xEF code 2 turns GC timing off (
enable_gc_delay): GC still moves the pages and erases the blocks, but issues no NAND operations. Code 1 turns it back on.
The LUN field gc_endtime is updated as GC programs and erases, and the
channel field is never written; nothing reads either.
Paced collection (gc_pace)
A whole-line pass books every copy of the victim at one instant, so the next
writes wait for all of them. With gc_pace on, collection copies the victim
a few pages at a time instead, in step with host writes.
end of a request, free lines <= gc_thres_pcent line count, no paced line:
victim = policy->select_victim_line(false); mark it reclaiming
V0 = its valid pages; R = pages_per_line - V0 (the pages it frees)
each host page programmed (direct, write-back, Write Zeroes):
credit += V0
while credit >= R: copy the victim's next valid page; credit -= R
every step:
budget: pages left before free lines reach the forced threshold
if the copies left and the host pages they need do not fit: copy more now
victim has no valid page left:
erase it on every LUN (in parallel), then free or retire it
forced pass (free lines <= gc_thres_pcent_high):
finishes the paced victim first, then collects as before
The line is empty after about R host pages, which is the space it gives back. Each copy still enters the NAND model at "now", as other GC does, so a host write waits for about one copy instead of a whole line. The end of each request takes the place of the background pass: it chooses the victim, and it finishes one that deallocation or overwrites emptied. Only host programs earn credit. A copy that finds no room stops pacing until the next request.
Pacing spreads the work; it does not bound latency. A large write does its
share in one call, and read reclaim and wear levelling still move whole lines.
It uses the boundary of blk_pe_limit (one plane per LUN, one namespace, no
buffer, FDP, Streams, CXL, hot/cold or hybrid mapping). Log page C0h counts
the copies at offset 224, the lines it finishes at 232, and the lines the
forced pass or the budget had to finish at 240.
Idle collection (gc_idle_ms)
Collection otherwise runs only while host requests run, so a burst after a
pause starts with the free lines the last burst left. With gc_idle_ms, the
FTL thread collects in idle time, as a real drive does.
request tail (FTL thread): busy = max(busy, end of the request's media work)
FTL thread pass with no request:
due: now >= busy + gc_idle_ms and now >= fence (timestamps only)
inside the sweep flag, as a request:
free lines >= idle target --> nothing to do
else do_gc(ssd, false): one victim, every normal guard
fence = latest end of all media work (LUN, channel, DQ, CA)
no victim or no gain --> fence also moves to now + gc_idle_ms
The idle target counts free lines, in the unit of gc_thres_pcent:
target = (1 - gc_idle_pcent / 100) * lines (gc_idle_pcent 0: gc_thres_pcent)
A value below gc_thres_pcent makes idle time free more lines than the
write path does.
A host command that arrives during a step waits at most one victim's copies.
The fence keeps the next step behind the media work of the last one.
The first version takes one bbssd controller with one namespace of its own
and page mapping. It refuses shared namespaces, ns_mgmt, FDP, cxl_ssd,
gc_pace, Streams, power_loss, the pSLC tier and CSD. With the property
at 0, the FTL thread does no new work.
FDP reclaim units
With Flexible Data Placement the FTL places data in reclaim units, one line
each, through per-handle write pointers, and collects reclaim units instead
of lines (do_gc_fdp_style() in hw/femu/bbssd/ftl-fdp.c). gc_strategy
picks that victim policy, or gc_policy by name; the FTL knobs listed under
Interactions are refused. The FDP chapter
and the FDP guide describe
it.
Both collectors record a page move through one helper, ssd_gc_move_page(),
and time it through ssd_gc_charge_move(). Each keeps its own destination
and write frontier: line GC writes to the data or stream pointer, FDP to the
handle's collection reclaim unit.
Write buffer
Figure: The BBSSD write buffer with buffer_size=10 and buffer_thres_pcent=80: a write that finds the buffer at its watermark first programs the two oldest pages and pays for them.
The write buffer models DRAM in front of the NAND. It holds logical page
numbers, not data: a write it accepts costs a DRAM access, and the program
is charged later to whatever forces the page out. Repeated writes to a
buffered page cost one program. The code is in
hw/femu/bbssd/ftl-datapath.c. Under FDP each held page also keeps the
placement handle of its last write, and its write-back goes to that
handle's reclaim unit (fdp_buffer_destage() in
hw/femu/bbssd/ftl-fdp.c; see the FDP chapter).
host write, pages P..Q
|
v
forced GC if free lines <= high watermark; one read-reclaim step
|
v
buffer enabled, not FUA, not a stream write? ---- no ----+
| yes |
v v
for each page: drop buffered copies of
already held? -> move to tail, write hit these pages; if the cache
else if count >= watermark: was disabled, write back
write back `batch` pages from the head everything
(oldest first), cost charged to this |
write v
insert at tail program each page
| (NAND time)
v
latency = max(DRAM access, write-back cost)
watermark = max(1, (int)(buffer_size * buffer_thres_pcent / 100))
batch = max(1, buffer_size - watermark)
DRAM access = dram_hit_ns, or pg_rd_lat / 16 when it is 0
(1000 ns when pg_rd_lat is 0 too)
- Structure. A tail queue in order of last write, LRU (
write_buffer) and a GLib tree keyed by LPN (wb_tree) for lookup. Capacity isbuffer_sizepages. - Admission is per page. A command larger than the buffer cannot push it past its size: it writes back a batch whenever the buffer is at the watermark. If a write-back frees nothing because the device is out of lines, the write fails with Capacity Exceeded.
- Write-back (
ssd_buffer_destage()) takes pages from the head (the least recently written), runs forced GC as needed, charges the DFTL lookup and programs each page exactly as a direct write would. Hybrid merges after each page as usual; FAST merges once per batch. A page costs the same buffered or not; only the request that pays differs. - Reads. A read of a buffered page costs one DRAM access and does not reach NAND, even when the buffer has stopped accepting writes.
- FUA and stream writes program directly. Once a direct write places a page, it drops any buffered copy of that page, so an older version is never programmed after the newer one. If a page finds no place, the write fails with Capacity Exceeded and the buffered copy stays owed.
- Placement. A write-back takes the oldest page and removes it from the buffer only once the page has a new mapping and a booked program. A page that finds no place keeps its place at the head, and the write-back stops.
- Deallocate drops buffered copies before unmapping, so discarded data is never programmed later.
- Flush reaches the FTL like any other command and writes back the whole
buffer, charged to the Flush. It also waits for the programs that the idle
write-back (
buffer_low_pcent) or a cache disable booked. While one of them is due, the Flush waits for all booked media work, since a suspend can move a program past its booked end. If a page finds no line, the Flush fails with Capacity Exceeded. - Volatile write cache. With
vwc=1the controller advertises a cache. When the host turns it off with feature 06h, the buffer stops accepting writes and Set Features writes back every buffered page first. If a page finds no line, the cache stays on and Set Features fails with Capacity Exceeded. Withvwc=0the buffer still works, and the host has no way to turn it off; Linux sends no Flush to a controller that advertises no cache.
host_write_pages counts pages when the host writes them and
nand_write_pages when they are programmed, so a buffer that absorbs
overwrites makes the write amplification factor drop below 1.
Power loss
With power_loss=on, the poller no longer touches payload: the FTL thread
runs the whole I/O command (nvme_power_io()), so the data copy and the
buffer change together. The first time a page enters the buffer, the FTL
saves the page's previous bytes and per-LBA state as an undo record. When
the page is programmed the record is dropped. Setting the QOM property
simulate-power-loss (runtime properties)
resets the controller, restores every buffered page from its undo record,
empties the buffer and counts an unsafe shutdown, unless a shutdown had
completed (SHST 10b) before the cut.
In this mode a shutdown of any kind, turning the cache off and Sanitize first write back every namespace's buffer; Flush, Format, Dataset Management, Copy, Write Zeroes (except on a PI-formatted namespace) and Write Uncorrectable write back their own namespace's. If the device has no line to write to, they fail with Capacity Exceeded (a shutdown sets Controller Fatal Status instead) rather than claim the data is durable. An FUA write programs a whole NAND page, so buffered neighbours in that page become durable with it.
With durable_at_done=on a page is durable when its program ends, not
when the program is booked. Each booked host program keeps a generation:
the page's bytes and LBA states before it, and the program's end time.
per page, oldest first: durable | g1 (end d1) | g2 (end d2)
g2 ends: g1 and g2 go (programs end out of order)
cut at c: from the newest back, restore while d > c
- A direct write (FUA or cache off) keeps one too. When it replaces a buffered copy, the generation holds the bytes from before that copy.
- A Flush completes no earlier than the end of the last pending program, also when the buffer is empty. SHST 10b waits for it too.
- At most
buffer_sizeprotected programs overlap in device time. Each takes the journal slot that is free first and starts no earlier than that, so a full journal makes the write wait, as a full buffer does on a drive. The host sees the wait in the write's latency. - The before-images themselves are bounded at
max(8 * buffer_size, 1024). There the FTL thread waits in real time for the first pending program to end. The FTL idle pass drops the generations whose program ended.
slots f1 <= f2 <= ... (buffer_size of them)
program p: start = max(stime, f1), ends at d, f1 becomes d
- The mapping is not rolled back: only the payload and its LBA states.
- A cache disable writes the buffer back and completes when those programs end. Until then the admin queue runs no later command, so a second cache change waits in the queue. A reset or a power cut drops the held command.
- DSM, Write Zeroes with DEAC and Write Uncorrectable program nothing, so they are durable at once. Every pending before-image of their pages takes the change: DSM zeroes the LBAs and makes them unallocated, Write Zeroes with DEAC also clears their uncorrectable bit, and Write Uncorrectable makes them allocated and uncorrectable. A cut then rolls the other LBAs of a page back and keeps these.
- Format and Sanitize drop the history of the namespaces they erase.
- Copy and Write Zeroes without DEAC hand their bytes to the FTL as a write's payload: the gathered source bytes, or zeros. The FTL takes each destination page's before-image, then applies the bytes, as for a write. On a namespace with metadata both fail with Invalid Field: the before-image holds data bytes only.
- A deallocate unmaps only the NAND pages it covers in full. A page that keeps some of its LBAs keeps its mapping, so a read of those LBAs still costs a NAND read and GC still moves the page.
Power-fail atomicity (awupf_lbas)
The buffer holds whole pages, so a write inside one page is atomic at a cut. A write that spans two pages can tear: a later FUA write or a write-back can make one page durable while the other waits.
write of LBAs 7..8, page = 8 LBAs, then FUA to LBA 0
page 0 programmed (with LBA 7) --> kept at a cut
page 1 buffered (LBA 8) --> rolled back = torn
awupf_lbas=N (with power_loss) runs a Write, Write Zeroes or Copy
of at most N blocks that spans pages as one transaction. It skips the
buffer and keeps each page's before-image until every page is placed.
If one page finds no room, every page goes back and the command fails.
The FTL runs the whole command in one step, and a cut comes only
between steps. AWUN and AWUPF report N - 1. Not with durable_at_done
or err_write_fail_ppm.
Silent corruption faults (sdc)
sdc=on (with power_loss) adds media faults that leave wrong data.
The FTL thread draws one as each page of a write goes into the store:
x-sdc for one fault in a test, or sdc_ppm with sdc_seed.
flip the page goes in with one bit changed
lost the old bytes stay; the write still completes
misdirect the old bytes stay; the new ones go to the next page
after the command
each spoiled block is marked (bit 2 of the per-LBA state, so a
rollback restores the mark with the bytes)
Read, Copy source, Compare, Verify of a marked block:
e2e_check=on (default) --> 81h, C0h Detected Errors + 1
e2e_check=off --> the wrong data, with success
A write of a block clears its mark, and so does a deallocation. The
mark stands in for an LBA tag or version that no longer matches (OCP
E2E-5). FEMU corrects no fault, so C0h Corrected Errors reads 0. Not
with durable_at_done, persist_file or awupf_lbas: a misdirected
page lies outside the transaction it would have to roll back with.
Power-loss protection (plp)
plp=on gives the buffer hold-up energy, as on a data-center drive
(OCP 2.7, 7.8). A cut then writes the buffer back instead of rolling it
back. A FUA write completes from the buffer and a Flush does not wait
for the media (OCP NVMe-IO-3). vwc=0 keeps the buffer on; with
ocp=on it is required, since such a drive has no cache to disable.
Not with durable_at_done or rain_parity.
buffer volatile = power_loss and not (plp and the check passed)
CC.EN 0->1, then every C6h minutes (default 15):
plp_health < 1 --> failed, for the life of the device
Critical Warning bit 4, SMART reliability event, PEL entry
C2h 01b ROM: write the buffer back; new writes fail 82h (bit 3
too); a write fetched before programs first
C2h 10b WTM: write the buffer back; writes program first
C2h 11b normal: the buffer is volatile again
plp_healthis the energy in percent. C0h reports it as Capacitor Health; withoutplpthat field is FFFFh. Set it at run time with theplp-healthQOM property.- The energy, not the last check, decides a cut: below 1 a cut writes nothing back. Every cut counts in PLP Start Count (C0h bytes 175:160). A page with no room on the media at the cut rolls back.
- A failure lasts for the life of the device. The mode taken then stays, whatever C2h says later.
plp_fail_modesets the C2h factory value (ROM, ROWTM-1). Withocp=onand DP-CFG-6 A, Set Features C2h changes it. End of life is read-only in every mode.
RAIN (rain_parity)
rain_parity=1 keeps one parity page in each stripe of a line, as RAIN
does on a datacenter drive. A stripe is one row of the line: one page per
die at one plane and page index. The parity page rotates over the dies,
so no die holds all the parity.
t = lun * nchs + ch (write pointer order), row r = pg * pls_per_lun + pl
parity of row r at t = dies - 1 - r % dies
t0 t1 t2 t3
row 0: D D D P the pointer starts a line on data
row 1: D D P D and steps over every P
- The parity page takes space: a line holds
pgs_per_line * (dies - 1) / diesdata pages. The namespace size does not change, so the spare space drops and WAF rises. - The last data page of a row books the parity program on its die. The
XOR time
parity_xor_nscomes first. - A line that closes early (open-block read reclaim) books the parity of each row it ends inside.
- A failed die (
failed_die) is out of every line opened after it fails. A line opened after e failures has S = dies - e members, so it holdsrows * (S - 1)data pages. - A read of a page on the failed die reads the other members of its row at once. It reads those with data or parity, then adds the XOR time.
- Dies fail one at a time. One parity page per stripe takes one failed
member, so a new failure needs every live page on lines opened since
the last one.
rain_rebuild=onmoves the older lines: each write moves at most one, when lines are to spare. Otherwise only GC moves them, and the hook refuses the failure until they are gone. - Each failure takes spare space. SMART Available Spare reports
100 * (cap(F) - namespace) / (cap(0) - namespace), with cap(e) the data pages of the lines past the GC reserve at epoch e. Below the threshold (20) it also sets Critical Warning bit 0. - The rebuild is done when its moves are booked, as all FEMU timing is: the mapping moves at once, and the NAND programs end later. A failure after that point can come before those programs end.
- A rebuild step looks at eight lines at most. A line it moves costs one GC move of that line.
epoch 0: t0 t1 t2 t3 --fail t1--> epoch 1: t0 x t2 t3
rebuild moves the epoch 0 data --fail t0--> epoch 2: x x t2 t3
- A failed die makes the media less reliable: SMART Critical Warning bit 2 (and EGCWS bit 2) stays set. A failure at run time also raises a SMART event and a telemetry trigger. The first one adds a Persistent Event log record, which logs the bit when it turns on. Each degraded read counts in the OCP C0h XOR Recovery Count.
- After a failure, lines have two sizes. A GC victim that holds more live pages than the free room can take goes back to the queue, and the line with the fewest live pages goes instead. Without this, FIFO GC could stall on a large old line.
- A failure at run time (the qtest hook
x-rain-fail) needs room for GC: an old line can fill two new lines, so the forced GC reserve must hold two lines.
line opened after t2 failed (S = 3)
t0 t1 t2 t3
row 0: D D x P
row 1: D P x D
- In an open stripe the parity is not programmed yet. The controller holds it in RAM, so a degraded read costs NAND reads of the programmed members only.
- With
ocp=on, OCP event 0016h (NAND Die Offline) takesinject_dieoffline until NUME=0 or a power cycle. The die stays out of the failure list, and lines keep their layout. A read of its page takes the other members of its stripe, as for a failed die. - Every live stripe keeps one lost member at most, so no page becomes unreadable. Set Features C0h checks this with the FTL paused:
Set 0016h, die d
d already failed ---------------------------------> accepted
a line opened before the last failure holds data -> Invalid Field
otherwise ----------------------------------------> accepted
x-rain-fail of another die while 0016h is set or waits --> refused
Read-only when the spare runs out (rain_read_only)
A real drive with a die failure and too little spare goes read-only, and
the host keeps its data. rain_read_only=on models this. Off (the
default), such a failure is refused.
x-rain-fail(d) rain_read_only=off rain_read_only=on
d failed before accepted accepted
media read-only - refused
two members left, old live lines refused refused
no room for GC, or cap(F) < need refused read-only
Available Spare after it is 0 accepted read-only
otherwise accepted accepted
- Read-only is the end-of-life path of
eol_read_only: the reserve lines go to the allocator, and GC, the rebuild, read reclaim and refresh stop. New writes fail with Write to Read Only Media. - The reserve is sized for a line of two dies (one data page a row), as dies fail down to two members. So the writes admitted before a failure always find room.
- The failure check and Available Spare count the same lines: all lines less the spare pool, the forced GC lines, the open pointers, the reserve and the retired lines.
- Critical Warning reads 0Dh: bit 2 for the failure, bit 3 for read-only, bit 0 for no spare. Available Spare reads 0.
- Each old line keeps one lost member, so every page still reads.
- The default MDTS (4 MiB) needs a reserve larger than small devices
have, so the property is opt-in. It needs
eol_read_only=on; it does not work with the write buffer oriu_pagesabove 1, whose writes the admission does not count. - A device whose
failed_dieleaves no spare at start is refused. - A
cxl_ssdlink is refused too: the CXL device makes that FTL, without the reserve. - With the property on, the FTL thread reports the spare, reliability and read-only bits to the Persistent Event Log as they change, as with the wear model.
RAIN with the wear model (blk_pe_limit)
rain_parity works with blk_pe_limit, blk_pe_spread, spare_lines
and erase_fail_ppm. A die failure changes the wear model in four ways.
die d fails (x-rain-fail or failed_die)
erase of a line : live dies erase; d frees its pages, no count, no time
wear-out check : d is out; no erase failure, no spare, no retirement
floor : lines the namespace needs at the new line size,
+ forced GC lines + 2 (+1 with gc_frontier)
Available Spare : min(wear spare, RAIN spare)
- A failed die keeps its erase counts. Its worn-out blocks leave the count of blocks in service; the grown bad and sacrificed totals stay.
- The wear spare is the retirement room left against the room at realization. The floor rises at a failure, so the room falls with it.
- With an end of life (
eol_read_onlyorrain_read_only), a spare of 0 after a failure, a spare swap or a retirement sends the media read-only. - The end-of-life reserve is sized for a line of two dies whenever an end of life is on.
- Spare pool lines (
spare_lines) hold no data, so the failure check and the RAIN spare leave them out. - OCP 0016h offline injection is not a failure here: that die erases and wears as before.
Data loss at a second failure (rain_loss)
One parity page per stripe repairs one failed member. A real drive whose
second die fails before the rebuild ends loses the data of stripes with
two failed members. rain_loss=on (with rain_read_only) accepts such
a failure. Off (the default), the old-data rule refuses it.
x-rain-fail(d), lines from before the last failure hold data
x-ftl-hold=1 --> refused, no change
freeze admission, drain the FTL queues, pause (one 10 s deadline)
failure as above, then the loss scan:
row r of an old line, missing(r) = failed members programmed in r
missing(r) >= 2 --> each valid data page of r on a failed die:
unmap it; mark its allocated blocks
Notice 05h (component failure); resume; thaw
- A programmed page counts even when it is invalid now: its old data is still in the parity of the row. The parity page counts too.
- A lost block reads Unrecovered Read Error, as after Write Uncorrectable, until a write. Deallocate keeps the mark.
- The device keeps the cause of each mark. Get LBA Status 10h/11h gives a run with a lost block LBARS 001b, else 011b. A failed Read, Compare, Verify or Copy adds a media error only when its range holds a lost block.
- A block the host deallocated holds no data, so it loses nothing.
- The freeze stops the pollers from taking commands, and the drain lets the FTL finish the ones they took. So every write before the failure has its new mapping when the scan runs.
- query-femu reports
lost-pagesandlost-blocks. Both count up over the device's life; a rewrite does not lower them. persist_fileis refused: the file keeps no record of the cause.
Read cache
read_cache_mb adds a DRAM read cache in front of NAND reads
(hw/femu/bbssd/ftl-cache.c). Like the write buffer it holds LPNs only.
host read of a mapped lpn (not in the write buffer)
|
v
lookup in an open-addressed hash over capacity slots
hit: cost dram_hit_ns (or pg_rd_lat / 16), no NAND read, no block
read count
miss: insert (evict by cache_evict if full), then NAND read
- Capacity is
read_cache_mbMiB divided by the page size. - Only reads fill it. A host overwrite, a deallocate and a power cut remove the page's entry. A GC relocation does not, since the content is the same.
cache_evictpicks the victim:clock(second chance),random(a fixed-seed generator, so runs repeat),lru(exact, by scan) orarc, a scan-resistant 2Q variant that evicts pages read once before pages read twice. It is not full ARC.- Hit and miss counts are kept in
ssd->rcachebut not exported.
Deallocate, Write Zeroes, Format and Sanitize
- Dataset Management deallocate (
ssd_trim()) unmaps every LPN that a range covers in full: it drops the buffered copy, invalidates the physical page, clearsmaptblandrmap, and drops the read cache entry. A page that keeps some of its LBAs keeps its mapping, so the data of those LBAs stays readable and in its stripe. A log-block scheme does this through itstrim()hook. A range past the device is skipped. The latency istrim_lat_nstimes the number of ranges, or 0. - Write Zeroes with Deallocate unmaps the pages it covers in full in the same way and costs no time. Without Deallocate it programs the range directly, after forced GC if needed, and counts the pages as host writes.
- Format and Sanitize call
bbssd_deallocate_all()on BlackBox namespaces (not CSD), which unmaps every LPN of the namespace's FTL. The lines keep their wear.
ONCS bit 0x8 (Write Zeroes) and 0x100 (Copy) are on by default; oncs can clear them.
Wear, read reclaim and retention refresh
Program/erase cycles
Every erase increments the block's erase_cnt and the FTL-wide
total_erases. SMART Percentage Used is
percentage_used = min(255, total_erases * 100 / (tt_blks * rated_pe_cycles))
where rated_pe_cycles is pe_cycles_rated, or the rating of
nand_cell_type (SLC 100000, MLC 3000, TLC 1000, QLC 300), or 0, in which
case the field reads 0. With blk_pe_limit, the denominator is the sum of
every block's own erase limit at start, spare lines included, so the figure
only grows. nand_bad_blocks marks a number of blocks as
factory bad for SMART Available Spare only: 100 - bad * 100 / tt_blks.
Placement ignores them. With several namespaces the controller reports the
most worn namespace and the lowest spare.
With ecc_step_ns set, a block's erase count (one tier per 750 erases) and
the age of its line add time to each read. That model belongs to the NAND
timing chapter.
Read retry and soft decode (rber_ppb)
With rber_ppb, each host page read draws a decode outcome for each ECC
codeword. A failed attempt costs one more page read on the same LUN and
channel. The model is synthetic and not calibrated. It never changes
data. A codeword that no decode corrects fails the read with
Unrecovered Read Error, as on a drive. rber_timing_only=on keeps the
earlier rule: such a read passes and pays the time only.
p = rber_ppb * 1e-9 * 2^(PE/rber_pe_double + age/rber_age_double_sec
+ reads/rber_read_double)
lambda = min(p * 8 * ecc_cw_bytes, 4 * max(hard, soft), data bits)
lambda_k = lambda * (f + (1 - f) * rr_gain^-k) f = rr_floor_pct / 100
codeword: attempt k = 0 .. rr_steps passes when u < F(ecc_hard_bits; lambda_k)
no pass --> soft decode passes when u < F(ecc_soft_bits; lambda_rr_steps)
page: retries = deepest codeword; soft when any codeword needs it
time: each retry and soft pass is a page read after the last one ends,
then rr_soft_ns of controller time
F is the Poisson CDF, summed in log space. u is a draw from a generator
seeded with rber_seed. Each pass adds to the block read count, so read
stress and read reclaim see it. GC reads, translation reads and FDP map
reads are left out. Log page C0h counts the outcomes at offsets 296 to 320.
With rrl=on the host sets a Read Recovery Level (Feature 12h). The level
bounds the recovery of host reads; GC reads keep full recovery.
level 4 (default) attempts 0 .. rr_steps, then soft decode (as above);
a codeword still uncorrected fails the read
(with rber_timing_only it pays the time only)
level 9 attempts 0 .. rr_steps, no soft decode
level 15 (Fast Fail) attempt 0 only, per codeword
any level, a codeword left uncorrected --> Unrecovered Read Error with DNR
(Linux does not retry it), a SMART
media error; the page leaves the read cache
The level applies to host Read commands only: Compare, Verify and Copy
keep full recovery, and GC reads stay outside the retry model. Without
soft bits, levels 9 and 4 make the same attempts, but level 9 fails the
read where level 4 does not. Realize refuses rrl with persist_file:
the level must survive a power cycle, and the file does not keep it. Identify Controller sets CTRATT bit 3 and RRLS bits
4, 9 and 15. Feature 12h has NVM subsystem scope: it takes NSID 0 only,
and realize refuses rrl in a subsystem. It is not saveable, and the
level persists across resets. A Set of another level fails with Invalid
Field.
Read-only end of life (eol_read_only)
With blk_pe_limit, a block wears out on the erase that takes it to its
limit. The check runs after the erase of a collected line, when the line
holds no data:
erase of line L takes a block to its limit
spare in every plane that needs one --> swap blocks, L stays
eol_read_only=off --> retire L, or keep the block
(overworn, warning bit 2)
spare_lines > 0, a pool is empty --> READ-ONLY, L retires
no pools, U - 1 >= floor --> retire L
no pools, U - 1 < floor --> READ-ONLY, L retires
a host write finds no line to program --> READ-ONLY (write goes on)
U = lines - spare - reserve - retired
floor = namespace lines + forced collection lines + 2
Pollers change the backing store before the FTL sees a write, so a write that got past admission must be able to finish. Realize holds back reserve lines: enough pages for the largest command, which MDTS, WZSL and MCL bound. One 64-bit word holds the read-only bit, the admitted requests and the pages they may still program.
poller, before a write-class command changes data
cost = pages it may program (DSM, DEAC Write Zeroes, Write Uncorrectable: 0)
CAS on the word: read-only bit set --> fail 182h, nothing changed
pages + cost > reserve --> leave it in the queue
else add 1 request and cost pages
FTL thread
after the request, or nvme_free_sq() for a dropped one: subtract them
at the end of life: atomic OR of the read-only bit, then the reserve
lines join the free list
After the OR no admission succeeds, so the admitted writes hold no more pages than the reserve has. Collection, read reclaim, wear levelling, pacing and padding stop for good, so the drain needs no erase. Format NVM fails with Command Sequence Error while admitted requests wait for the FTL, since their cost was set in the old LBA format.
Read reclaim and retention refresh
host NAND read of block B in line L
|
+-- read_reclaim_limit set and B.read_cnt >= limit --+
+-- retention_limit_sec set and now - L.close_time >= -+--> queue L
limit (one line at
a time)
next host write:
|
v
do_read_reclaim(): queued line, high watermark not reached,
at least 2 free lines, L full or in the victim queue?
| yes
v
take L out of its list, reclaiming = true, collect L like GC
read_reclaims++ or retention_refreshes++
Every NAND read the FTL issues, host, GC or merge, increments its block's
read_cnt (GC reads are issued only while GC timing is on); an erase
resets it. Reads answered by the write buffer, the read cache or a DFTL
translation page do not count. The rewrite happens on a write, where
relocation already costs something, so the read that queued it does not
stall behind a whole line. One line is refreshed per write at most. Without maint_idle, a line
that nothing reads is never refreshed, and a workload that only reads
refreshes nothing. The request is dropped if GC collects the line first, or if the line is
still open for writing when the next write checks it.
Maintenance in idle time (maint_idle)
With gc_idle_ms and maint_idle=on, an idle step also runs the queued
reclaim and scans closed lines for retention age:
idle step due (gc_idle_ms rules) and no media work still booked:
a reclaim waits for free lines (high watermark, or < 2 free)
--> one collection victim first; the reclaim stays queued
else turns: queued reclaim, retention scan, idle collection
scan: 16 line ids from a cursor; a closed data line with valid
pages and ssd_data_age_ns() >= retention_limit_sec
--> queued with reason AGE and rewritten now
a step that neither copies nor erases waits gc_idle_ms
Idle reclaims and refreshes add to the same totals as the write path's;
query-femu also counts them apart (idle-reclaims, idle-refreshes).
A read that arrives while an idle step runs waits for that one line's
copies and erase. The scan keeps its own turn while a read reclaim is
queued, so new read stress cannot stop it.
One read reclaim is queued at a time, as before; open lines and frontiers
are not scanned, and static wear levelling stays on the write path.
Aging state across a restart (persist_ftl)
With persist_ftl, the FTL section of persist_file (schema 2) also keeps
the state of the aging models. A drive aged in one run goes on in the next:
run 1: blk_pe_limit, spare_lines, wl_spread, read_reclaim_limit,
retention_limit_sec, ecc_retention_sec or rber_ppb
--> clean end (unplug or quit) --> file, FTL section schema 2
run 2: the same properties --> load --> the same wear, ages, retirements
another aging property --> realize fails (digest)
| Kept | Fields |
|---|---|
| per block | erase count, read count, erase limit, overworn mark, at the block's slot after spare swaps |
| per plane | spare blocks used, which names the next spare slot |
| per line | free, open, full, victim, spare, held reserve or retired; close and open ages |
| wear | grown bad, sacrificed and overworn blocks, the endurance total, read-only media |
| maintenance | the line queued for a rewrite and its reason, read reclaims, retention refreshes, levelling credit, state and totals |
| RBER | the generator, the retry counters, recovered reads and failed reads |
Rules:
- A data age is the age at the save: the time QEMU is down does not age the media. When a saved age is above the host clock of the new run (as after a host reboot), the line-time clock moves ahead to keep it.
- A restart is a cold start: booked LUN, channel and bus times start empty.
- The digest covers the aging models and every property that changes what
their state means (spread and seed,
eol_read_only,age_scale, the ECC and read retry steps,mdts,mpsmin,nlbafand others), so a file loads only into a device that reads the state the same way. - A load checks the aging records against each other (spare slots against the count, retirements against the wear totals, the read-only bit, the queued line) before it changes anything.
- A file of schema 1 loads only into a device without an aging model. A file without FTL state fails realize on a device with one, so an aging history never starts again unseen.
- Session counters start again:
die_stats, the controller's host command counts, the Error Information log and pending notifications. A load sends no new wear notification; SMART reads its warnings from the loaded state. - The other features
persist_ftlrefuses stay refused (FDP, the write buffer, Streams, idle collection, open-block maintenance, the injected error rates and others; realize names the property).
Fault insertion
err_read_unc_ppm and err_write_fail_ppm turn a rate into a period,
1000000 / ppm, at least 1. Every Nth Read command completes with
Unrecovered Read Error (with DNR, as every Unrecovered Read Error in FEMU
is) and every Nth Write command with Write Fault. The
counters run per namespace FTL, so a run repeats exactly. The command is
still timed and, for a write, still programmed and mapped; only its status
changes. The injected counts feed SMART Media and Data Integrity Errors.
Write Zeroes and Copy are never failed.
Block death beyond the erase limit
Two opt-in models kill blocks before their erase limit. Both need
blk_pe_limit, so the spare swap, retirement and read-only end of life
handle the dead block. Each draw is a stateless hash of blk_pe_seed.
The same seed, block and erase count always give the same draw. The dead
blocks still depend on which erases run, so a run with another collection
order can lose other blocks.
early life at realize, per block:
hash A(seed, block) < blk_early_ppm
--> pe_limit = min(pe_limit, 1 + hash B(seed, block) % blk_early_pe)
erase fail after a line erase, per block alive before the erase:
hash C(seed, block uid, erase count) < erase_fail_ppm
--> block failed --> spare swap, else the line retires
--> spare pools set but one is empty --> read-only
--> no spare pools and no room to retire --> read-only
the host sees success; statistics log byte 328 counts erase failures
- A draw hits when
hash * 10^6 < ppm * 2^64. A rate of 0 never hits, and 1000000 always hits. - Early life changes only the fixed limits, so
persist_ftlkeeps it. The two early-life properties join the FTL digest when set. - A failed block keeps its erase limit. Its own flag makes it dead, and
it never stays in service as an overworn block:
erase_fail_ppmneedseol_read_only=on, which retires its line in every case. - The block uid moves with the block in a spare swap. A spare block that takes its place draws with its own uid.
erase_fail_ppmis refused with FDP and withpersist_ftl. The FTL section has no record of the failed flag yet.- The rates are synthetic fault injection, with no fit to a measured population.
- Program failure is not modelled. A faithful model must stop writes to the block and make every relocation commit only after its program succeeds.
Over-provisioning and capacity
The reserve
bb_check_capacity() in hw/femu/bbssd/bb.c refuses a namespace that would
leave GC no room. The reserve, in lines:
reserve = gc_thres_lines_high forced watermark, with its floor
+ 1 data pointer
+ 1 if hot_cold_sep hot pointer
+ 1 if mapping is hybrid or fast log pointer
+ streams.max + 1 if streams stream and stream GC pointers
usable = (blks_per_pl - reserve) * pages_per_line * page_size
refused when the namespace is larger than usable,
or when blks_per_pl <= reserve
Each namespace has its own FTL built from the whole geometry, so the check applies per namespace.
Sizing the namespace
Without op_pcent, the backend is devsz_mb MiB, split across the
namespaces, and the spare area is whatever the geometry has beyond that.
With op_pcent, the backend is the raw NAND capacity and each namespace
gets raw * 100 / (100 + op_pcent) / namespaces, rounded down to 512 bytes
(an even split unless namespace_sizes is given); devsz_mb is ignored.
Worked example: the default geometry
The default properties describe 8 channels x 8 LUNs x 1 plane x 256 blocks x 256 pages x 8 sectors x 512 bytes:
page = 8 x 512 = 4 KiB
NAND pages = 8 x 8 x 1 x 256 x 256 = 4,194,304
raw capacity = 4,194,304 x 4 KiB = 16 GiB
lines = blks_per_pl = 256
blocks per line = 8 x 8 x 1 = 64
pages per line = 64 x 256 = 16,384 (64 MiB)
background GC = (int)(0.25 x 256) = 64 free lines (75% used)
forced GC = (int)(0.05 x 256) = 12 free lines (95% used)
victim filter = 16,384 / 8 = 2,048 invalid pages
reserve = 12 + 1 = 13 lines
usable = 243 x 64 MiB = 15,552 MiB
devsz_mb=12288 (the launcher): 12 GiB = 192 lines of data
-> the data pointer holds a line from init, so free lines reach
64 and background GC starts as the last of the 192 lines is
opened, just before one full pass completes
op_pcent=25: 16 GiB x 100 / 125 = 13,107.2 MiB exposed
op_pcent=7: 16 GiB x 100 / 107 = 15,312.1 MiB exposed
host memory for the FTL: maptbl 32 MiB + rmap 32 MiB
+ page status 16 MiB + block and line arrays
With the default devsz_mb of 1024 the same geometry exposes 1 GiB, about
6% of the NAND, and GC barely runs. To give GC work on a small device,
shrink the geometry instead; this one has 512 MiB of NAND and exposes about
410 MiB:
-device femu,femu_mode=1,nchs=2,luns_per_ch=4,blks_per_pl=64,op_pcent=25
Run-time controls
Admin opcode 0xEF changes the FTL while the guest runs. Only a BlackBox controller accepts it. Codes 1 to 4 apply to every namespace with an FTL, with the dataplane paused; codes 5 to 7 act on the controller.
| CDW10 | Effect |
|---|---|
| 1 | GC operations take NAND time (the default) |
| 2 | GC operations take no NAND time |
| 3 | flat read, program, erase times back to 40 us, 200 us, 2 ms |
| 4 | flat read, program and erase times to 0 |
| 5 | reset the poller completion counters |
| 6, 7 | turn the per-request log lines on or off |
Codes 3 and 4 set the built-in flat times, not the values given on the
command line, and do not affect nand_cell_type tables. See
changing timing at run time.
Statistics
Vendor log page C0h
nvme_collect_media_stats() in hw/femu/nvme-admin.c sums the FTL counters
over the controller's bbssd, CSD and KV namespaces.
log-pages-and-counters.md
lists the offsets.
| C0h field | FTL counter | Moves when |
|---|---|---|
| WAF x 1000 | (nand + gc) x 1000 / host | after the first host write |
| host write pages | host_write_pages | Write, the destination of Copy, and Write Zeroes without Deallocate, per page, buffered or not |
| GC write pages | gc_write_pages | GC, read reclaim and log-block merges relocate a page |
| NAND write pages | nand_write_pages | a host page is programmed |
| max block reads | largest read_cnt | NAND reads; reset by erase |
| read reclaims, retention refreshes | read_reclaims, retention_refreshes | a queued line is rewritten |
| buffer reads and read hits | sp.read_cnt, sp.read_hit_cnt | host read pages, and those the buffer held |
| buffer writes and write hits | sp.write_cnt, sp.write_hit_cnt | host write pages, and those already buffered |
| hybrid switch, full merges, merge erases | struct femu_map_hybrid | mapping=hybrid only |
The buffer read and write counts move with or without a buffer, so their ratio is the hit rate. Telemetry log 07h captures the same 512 bytes.
SMART and Endurance Group
| Field | Source |
|---|---|
| Percentage Used | ssd_percentage_used(), and zns_percentage_used() for a zoned namespace; the most worn namespace |
| Available Spare | ssd_available_spare(), lowest namespace; below 20 sets the spare critical warning; 0 once the media is read-only |
| Critical Warning | bit 0 spare below 20, bit 1 temperature, bit 2 an overworn block, bit 3 media read-only; byte 6 (EGCWS) and the Endurance Group log repeat bits 0, 2 and 3 |
| Media and Data Integrity Errors | injected read and write faults (and ZNS write faults) |
| Data units, host commands | the pollers' host I/O counters, not the FTL |
| Endurance Group Media Units Written | (NAND + GC + translation + pad write pages) x page size, in units of 10^9 bytes rounded up; needs a femu-subsys |
Counters kept but not exported
DFTL hits and misses (ssd->cmt), read cache hits and misses
(ssd->rcache), FAST merge counts and the per-block erase_cnt stay inside
the FTL. debug_ftl=on prints hybrid and FAST merge counts to stdout.
Parameters
Every property is listed with its type, default and range in the property reference; this table says what each does inside the FTL and what it interacts with.
Geometry and capacity
NAND geometry, mode and capacity
| Property | Effect in the FTL | Interacts with |
|---|---|---|
secsz, secs_per_pg | page size; LPN = byte offset / page size | the LBA format; DFTL entries per translation page |
pgs_per_blk | pages per block and per line column; the log-block merge unit | at most 512 with nand_cell_type |
blks_per_pl | the number of lines | the watermarks and the reserve are fractions of it |
pls_per_lun, luns_per_ch, nchs | line width and write striping | parallelism; tplebsy for multi-plane erase; mp_program, mp_read for multi-plane program and read; plane_first for the write order |
devsz_mb, namespaces, namespace_sizes | the exposed capacity | must fit the usable lines per namespace |
op_pcent | exposes a fixed fraction of raw NAND | overrides devsz_mb; refused with cxl_ssd |
Garbage collection, mapping and caches
Garbage collection, mapping and caches
| Property | Effect in the FTL | Interacts with |
|---|---|---|
gc_thres_pcent | background GC watermark | must not exceed gc_thres_pcent_high |
gc_thres_pcent_high | forced GC watermark; sizes the reserve | lower values cost exposed capacity |
gc_policy | line victim selection | under FDP, the reclaim unit strategy; needs gc_strategy=0 |
gc_seed | seed for the random and d-choice policies and FDP random reclaim | no effect on the other policies |
gc_pace | paced collection: copies the victim in step with host writes (paced collection) | replaces the background pass; refused where blk_pe_limit is, and under FDP |
gc_idle_ms, gc_idle_pcent | idle collection (idle collection) | one namespace, page mapping; refused with FDP, gc_pace, Streams, the tier |
gc_strategy | reclaim unit victim selection | FDP only; a gc_policy other than greedy replaces it |
mapping | L2P scheme | hybrid and fast reserve a line and refuse Streams and FDP |
mapping_cache_mb | DFTL cache size | used only with mapping=dftl |
read_cache_mb, cache_evict | read cache size and eviction | hit time is dram_hit_ns, or pg_rd_lat / 16 at realize (1 ns at least) when that is 0; 0xEF does not change it |
hot_cold_sep | hot write pointer for overwrites | page or DFTL only; reserves a line; refused with FDP |
buffer_size, buffer_thres_pcent | write buffer capacity in pages, and the write-back watermark | vwc, power_loss; under FDP each page goes to its handle's unit |
fdp_trim_erase_all | FDP deallocate resets every reclaim unit | FDP only |
debug_ftl | prints invalid page transitions and merge counts | none |
Reliability and wear
| Property | Effect in the FTL | Interacts with |
|---|---|---|
pe_cycles_rated | Percentage Used denominator | overrides the nand_cell_type rating |
nand_bad_blocks | Available Spare | placement ignores it |
| wear events | the FTL thread sets a pending SMART warning bit when the spare crosses below 20, a block is overworn while none was, or the media goes read-only; the controller's event bottom half raises it if Asynchronous Event Configuration enables it. The FTL thread also writes the warning to the Persistent Event log at the change | once at each start of a condition; a controller reset drops a pending bit, not the log entry |
spare_lines | per-plane pool of replacement blocks: a worn-out block swaps its whole state with a spare block of its plane, so addresses do not change; Available Spare follows the emptiest plane | needs blk_pe_limit; the namespace must fit without the spare lines |
blk_pe_limit, blk_pe_spread, blk_pe_seed | per-block erase limit; after a line erase that takes a block to it, the line retires while usable lines stay at or above the namespace's lines + forced collection lines + 2; otherwise the media goes read-only (end of life) | refused with the settings the parameter manual lists |
eol_read_only | on (default): read-only end of life, reserve lines and page-credit admission; off: retirement also needs an open line and a free line, and a block that cannot retire stays in service (overworn) and sets SMART critical warning bit 2 | has an effect only with blk_pe_limit; on needs mdts 1 or more |
ecc_step_ns, ecc_retention_sec | read time grows with erase count and line age | under FDP, a line's age counts from the retirement of its reclaim unit |
pd_edge_wls, pd_edge_tiers, pd_open_tiers, pd_open_age | program disturb: extra ECC tiers for bottom wordlines and part-programmed blocks; age from the first program | chosen tier values; nand_block.wp counts programs since the erase; refused with ZNS, OCSSD, NoSSD, cxl_ssd and shared namespaces (NAND timing) |
pd_open_read_limit, pd_open_close_sec | program disturb actions: a lower read limit for part-programmed blocks, which takes the line out of its write frontier and rewrites it; pad and close a frontier left open too long | bbssd and CSD, also FDP units; checked at each request, served on the next Write; pads count in WAF and media bytes; refused with KV, mapping=fast or hybrid and the phase 1 refusals (NAND timing) |
err_read_unc_ppm, err_write_fail_ppm | fixed-period command failures | counted in SMART media errors |
read_reclaim_limit | read count that queues a line for rewrite | needs host writes to act; under FDP it refreshes the whole reclaim unit (FDP) |
wl_spread | static wear levelling (do_wear_level()): at a fresh data line, swap it for the most worn free line and move the least worn full line into it | no write pointer of its own; credit of one per host page programmed, four lines per move; the earlier attempts are described in the function comment |
age_scale | multiplies data age (ssd_data_age_ns()) for retention refresh and the ECC age tier | not for cost-benefit collection, whose order one factor on every age does not change |
retention_limit_sec | line age that queues a line for rewrite | same |
NAND timing the FTL charges
The FTL charges trim_lat_ns per deallocate range (also under FDP) and
issues a multi-plane erase per LUN during GC, whose inter-plane time is
tplebsy. All the other timing properties are applied by the NAND media
layer.
Controller properties the FTL reads
| Property | Where documented | Effect in the FTL |
|---|---|---|
vwc | controller identity | lets the host turn the write buffer off |
oncs | same | Write Zeroes and Copy reach the FTL only when enabled (the default) |
power_loss | power loss | undo records and simulate-power-loss |
streams, streams.max | same | per-stream write pointers; reserve streams.max + 1 lines |
Interactions and refusals
- FDP refuses a
gc_policyother thangreedytogether with agc_strategyother than 0. It refuseshot_cold_sepand thehybridandfastmappings with a message that says why: they write through pointers of their own, past the unit the placement handle names. - Unknown names for
mapping,gc_policyandcache_evictare refused at realize. - Watermarks outside [1, 100], or a high watermark below the low one, are refused.
- The write buffer is off when
power_loss=onandvwc=0, and while the host has the advertised cache turned off. - DFTL cache size has no effect under
page,hybridorfast.
Examples, each checked by check-doc-examples.py:
-device femu,devsz_mb=1024,femu_mode=1,mapping=dftl,mapping_cache_mb=8
-device femu,devsz_mb=1024,femu_mode=1,hot_cold_sep=on,gc_policy=cost-benefit
-device femu,devsz_mb=1024,femu_mode=1,buffer_size=4096,buffer_thres_pcent=75,vwc=1
-device femu,devsz_mb=1024,femu_mode=1,mapping=hybrid
Validation status
What the automated tests check:
| Area | Test | Checks |
|---|---|---|
| BAST merges | unit test test-femu-hybrid-oracle; qtests hybrid-oracle-*, hybrid-batch-occupancy, hybrid-destage-occupancy, hybrid-switch-trim-erase, hybrid-trim-occupancy | the unit test checks the reference model; the qtests compare FEMU's switch, full merge and erase counts against it, including deallocate and the write buffer |
| Victim queue | unit test test-femu-pqueue | priority queue operations, including random pop driven by the caller's number; pop, remove and random pop leave the detached element's index at 0; pop equals removing the top and random pop equals removing the drawn slot, slot for slot |
| Reproducible GC | qtests gc-seed-d-choice, gc-seed-random, gc-seed-fifo | two devices with the same configuration and 2048 random page writes report the same relocation count every 32 writes and the same WAF; a third with another gc_seed differs (FIFO: matches) |
| NAND timing | unit test test-femu-nand-media | the media layer the FTL calls |
| C0h counters | qtest media-counters | host and NAND page counts and the WAF move with writes |
| Write buffer | qtest buffer-counters, flush-without-vwc and power-loss-* | hit counts; Flush (also with vwc=0), FUA, write-back, cache disable, shutdown and power-cut rollback |
| Streams | qtest streams-gc and the other streams-* cases | stream placement and GC of stream lines |
| GC with no free line | qtests gc-no-destination, gc-no-destination-hot-cold, streams-gc-floor, gc-no-destination-fdp | on a geometry whose forced watermark rounds to zero, random single-page and 64-page writes never fail, no mapping names an erased page and no valid page is orphaned (read through the qtest-only x-ftl-check property) |
| Charged work for a fixed workload | qtests ftl-trace-bbssd, ftl-trace-hot-cold, ftl-trace-fdp | a seeded queue-depth-one write and read workload with collection gives exact command, host, NAND, relocated-page and erase counts and exact read, program and erase commands charged to the media layer, and a digest of the order in which lines or reclaim units were collected (qtest-only x-ftl-trace; the digest is the last field, a running FNV-style hash of each collected victim's id, updated once per collection, read reclaim included); a refactor of the allocator, collection or media charge must not move them. A different victim policy or a dropped or duplicated charge fails it. The modelled-latency sum depends on host load and is only held to 25%, so NAND timing values are left to test-femu-nand-media |
| Victim order of each policy | qtests ftl-trace-random, ftl-trace-d-choice, ftl-trace-fifo, ftl-trace-fdp-random, ftl-trace-fdp-noisy, ftl-trace-fdp-noisy-ii, ftl-trace-fdp-reread | the same workload under gc_policy=random, d-choice and fifo, and under FDP gc_strategy=2 and 4, gives exact counts, with a fixed gc_seed where the policy samples. The NOISY cases write two placement identifiers, so the per-handle heaps compare their tops; in -ii one handle is Initially Isolated and has no heap of its own. ftl-trace-fdp-reread reads a page after each overwrite, which adds background passes whose refusals move the greedy tie order. A changed draw, tie break or heap key fails the matching case: the victim digest catches a change that leaves the counts equal, such as FDP random with gc_seed=7 and each draw one higher; cost-benefit has no exact pin, because it reads the host real-time clock |
| Read reclaim | qtest ftl-trace-read-reclaim | with read_reclaim_limit=2 and a read after each overwrite, 83 lines are rewritten, some of them taken from the victim heap, and the trace counts are exact |
| Refused FDP strategies | qtest fdp-gc-strategy-refused | gc_strategy values other than 0, 1, 2 and 4 are refused at realize |
| Multi-plane program and read | qtests ftl-trace-mp-off, ftl-trace-mp-on, ftl-trace-mp-one-plane, ftl-trace-mp-fdp-off, ftl-trace-mp-fdp-read, mp-program-scopes-off, mp-program-scopes-on, multiplane-warnings, config-refused | with two planes per LUN and reads of 16 pages, mp_program=1,mp_read=1 keeps every command, page and erase count of the same workload with them off, issues fewer read and program commands, and models less time before collection starts, where that time is exact; with one plane the trace equals ftl-trace-bbssd; under FDP the trace with mp_read=1 equals the one without it; a full row written by Write Zeroes or by a buffer write-back takes 4 program commands instead of 8; a setting that changes nothing warns and a negative busy time is refused |
| Format, Sanitize | qtests format-ftl, sanitize | after Format, GC relocates nothing; Sanitize status and zeroed data (the FTL state is not checked) |
| Robustness | qtests io-fuzz, io-fuzz-fdp, config-refused | malformed I/O, refused configurations |
| Start-up | doc-examples | every tagged example on this page and the BlackBox guide starts and moves one block |
Apart from the exact counts above, no automated test checks the
behaviour of the cost-benefit policy, dftl and fast mapping, hot/cold
separation, the read cache, retention refresh, read and write
fault insertion on BlackBox, or the wear and spare figures. They are covered only by the
start-up examples and by guest runs during development; femu-test.sh
(guest-side tests) checks that the
counters move. FEMU's latencies and write amplification have not been
calibrated against a specific commercial drive.
Limits
- Data placement is modelled per page; the FTL never tracks sectors within a page, so writes smaller than a page cost a whole page program.
- GC relocations go through the data pointer (or a stream pointer for
stream data). Only line and FDP collection with
gc_copybackmove a page on its die; paced collection does not. GC runs on the FTL thread, one line at a time. - There is no explicit wear levelling, and bad blocks do not affect placement.
- Read reclaim and retention refresh act only on reads followed by writes.
cost-benefitGC uses the host clock for age, so it is not reproducible run to run.- An injected write fault still programs and maps the data.
- FAST merge counts and DFTL and read cache hit rates are not exported.
- Each namespace's FTL is built from the whole geometry, so host memory for the FTL grows with the namespace count.
Extending the FTL
Adding a GC victim policy
- Write
static struct line *select_victim_line_<name>(struct ssd *ssd, bool force)inhw/femu/bbssd/ftl-line-gc.c. Candidates are the lines inssd->lm.victim_line_pq; slots1tosize - 1ofpq->d[]hold them. - Apply the background filter: when
!forceand the line has fewer thanpgs_per_line / 8invalid pages, return NULL and leave the queue as it was. - Remove the chosen line with
pqueue_remove()(orpqueue_pop()for the top), which setsline->posto 0. The victim count is the queue size, so there is no counter to keep.reclaim_line()expects a line that is in no list. - Add
{ .name = "<name>", .select_victim_line = ... }tofemu_ftl_policies[].femu_ftl_policy_known()then accepts the name. - Describe it in the
gc_policydescription inhw/femu/femu-props.c, regenerate the property reference, and add a qtest that tells the policy apart from greedy.
Adding a mapping scheme
- Implement
struct femu_mapping_opsin a newftl-map-<name>.c: at leasttranslate,prepare_write,commit_writeandgc_relocate_commit. Keepmaptblandrmapcorrect:commit_writemust invalidate the old page and set both tables, because GC and reads depend on them. - Keep private state in
ssd->map_priv, allocated ininitand freed inexit. - Set
uses_log_classif writes go through the LOG pointer; the reserve then grows by one line and Streams are refused. Setuses_cmtto get the DFTL cost model. - For merges, provide
needs_reclaimandreclaim(ssd, budget).reclaim()charges its own NAND operations and returns the latency to add to the triggering request.reclaim_per_pageruns it after every page instead of once per request. Allocate a destination before invalidating the source, so a full device never loses the only copy. - Provide
trimif the scheme keeps per-page state. - Add the ops to
femu_mapping_extra[]inhw/femu/bbssd/ftl-map.c, declare them inftl-internal.h, and add the file to the FEMU source list inhw/femu/meson.build.
Run the unit tests and the qtests (testing guide), and check that the C0h counters move for the new code path: a counter that never changes in a mode means the mode is not reached.
Source map
| File | Contents |
|---|---|
hw/femu/bbssd/bb.c | mode registration, bb_check_capacity(), FDP refusals, the 0xEF switch, teardown |
hw/femu/bbssd/ftl.c | ssd_init(), bb_ftl_process_req(), Copy, counters, Percentage Used, Available Spare, ssd_free() |
hw/femu/bbssd/ftl.h | struct ssd, struct ppa, lines, write pointers, the mapping and policy ops |
hw/femu/bbssd/ftl-internal.h | address helpers, ssd_lpn_range(), GC watermark tests |
hw/femu/bbssd/ftl-geom.c | bb_check_geometry(), ssd_init_params(), NAND array allocation |
hw/femu/bbssd/ftl-datapath.c | read, write, write buffer, deallocate, Write Zeroes, power-loss rollback |
hw/femu/bbssd/ftl-line-gc.c | lines, write pointers, Streams pointers, GC, victim policies, read reclaim |
hw/femu/bbssd/ftl-map.c | maptbl, rmap, page and DFTL schemes, scheme registry |
hw/femu/bbssd/ftl-persist.c | persist_ftl: the FTL section of a persist file, its checks and its load |
hw/femu/bbssd/ftl-map-cmt.c | DFTL cached mapping table |
hw/femu/bbssd/ftl-map-tp.c | DFTL translation pages on flash: GTD, TP pointer, publication, TP moves, checks |
hw/femu/bbssd/ftl-map-hybrid.c | BAST log-block scheme and its C0h counters |
hw/femu/bbssd/ftl-map-fast.c | FAST log-block scheme |
hw/femu/bbssd/ftl-cache.c | read cache and its eviction policies |
hw/femu/bbssd/ftl-media.c | bridge to the NAND media layer, block read counts |
hw/femu/bbssd/ftl-fdp.c | FDP reclaim units, handles and their GC |
hw/femu/bbssd/ftl-exp.c | debug tracing of marked pages, off unless FEMU_EXP_LOG or FEMU_DUMP_LPN is set |
hw/femu/femu.c | the FTL thread, op_pcent sizing, simulate-power-loss |
hw/femu/nvme-admin.c | C0h, SMART and Endurance Group counters, Sanitize, the cache feature |
Related pages
- BlackBox guide: launch, guest use, refusals
- Timing model
- Architecture
- Measuring
- Log pages and counters
- Property reference