From be5d36919ae4d3072f7951244e694c31ec3dc7a5 Mon Sep 17 00:00:00 2001 From: Ameer Hamza Date: Thu, 5 Mar 2026 20:26:12 +0500 Subject: [PATCH] man: Update L2ARC documentation for depth cap and write budget fairness Reviewed-by: Brian Behlendorf Reviewed-by: Alexander Motin Signed-off-by: Ameer Hamza Closes #18289 --- man/man4/zfs.4 | 12 +++++++----- man/man7/zpoolconcepts.7 | 18 +++++++----------- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/man/man4/zfs.4 b/man/man4/zfs.4 index 509b3109a..5ec9d045e 100644 --- a/man/man4/zfs.4 +++ b/man/man4/zfs.4 @@ -108,12 +108,14 @@ and only applicable in related situations. Seconds between L2ARC writing. . .It Sy l2arc_headroom Ns = Ns Sy 8 Pq u64 -How far through the ARC lists to search for L2ARC cacheable content, +How far through the ARC lists to search for L2ARC cacheable content per cycle, expressed as a multiplier of the effective write size. -ARC persistence across reboots can be achieved with persistent L2ARC -by setting this parameter to -.Sy 0 , -allowing the full length of ARC lists to be searched for cacheable content. +Setting to +.Sy 0 +disables the per-cycle headroom limit. +Scan depth is also bounded by +.Sy l2arc_ext_headroom_pct +when persistent markers are active. . .It Sy l2arc_headroom_boost Ns = Ns Sy 200 Ns % Pq u64 Scales diff --git a/man/man7/zpoolconcepts.7 b/man/man7/zpoolconcepts.7 index 07b78dda2..1571bc6b8 100644 --- a/man/man7/zpoolconcepts.7 +++ b/man/man7/zpoolconcepts.7 @@ -430,19 +430,15 @@ is updated even if no metadata structures are written. L2ARC operates in one of two modes depending on total cache capacity. When total L2ARC capacity is less than twice .Sy arc_c_max , -L2ARC uses exclusive caching, -writing buffers to cache as they are evicted from ARC. +L2ARC writes buffers to cache as they are evicted from ARC. When total capacity is at least twice .Sy arc_c_max , -L2ARC switches to inclusive caching with persistent markers -that track scan positions, -attempting to duplicate ARC contents as much as write throughput allows. -Setting -.Sy l2arc_headroom Ns = Ns Sy 0 -will result in scanning the full-length ARC lists for cacheable content to be -written in L2ARC (persistent ARC). -In inclusive mode, markers progress toward the head across iterations, -naturally covering the full list. +L2ARC uses persistent markers that track scan positions across iterations, +writing cacheable content as write throughput allows. +A depth cap +.Pq Sy l2arc_ext_headroom_pct +limits how far markers advance from the tail, keeping them focused on +buffers soon to be evicted where caching adds the most value. .Pp If a cache device is added with .Nm zpool Cm add ,