Zephyr NVS Sector Sizing: Reserve Space for Reclaim Before the Device Is Full

Size an NVS region for the live record set, record overhead, and the space needed to copy live records during reclaim. Raw partition bytes are not all available to application values. A configuration that stores every setting once can still fail after repeated replacements because its steady-state reclaim path has no useful headroom.

This worksheet and qualification plan target Zephyr v4.2.0 NVS. They address capacity and reclaim progress, rather than predicting flash lifetime. Keep the flash driver, erase geometry, write alignment, and data-CRC setting fixed while qualifying a layout. Changing those inputs can change the space calculation.

1. Establish legal sectors before counting records

The v4.2.0 NVS documentation requires a sector size that is a power of two and a multiple of the flash erase-page size. At least two sectors are required, with one kept empty for copying existing data. Therefore two sectors do not provide two sectors of steady-state payload capacity.

Read the actual driver-reported erase layout and compare it with the selected device’s documentation across the whole region. For example, the SST26VF064B/SST26VF064BA has a 4 Kbyte sector-erase operation in DS20005119K section 5.17. That device fact does not establish the erase layout exposed by every controller driver. Reject a region that crosses another partition or includes incompatible erase geometry.

Record sector size S, sector count N, partition offset, write-block size W, and whether payload CRC is enabled. Check the release implementation’s limits too, including the maximum individual record size. A large total partition cannot rescue an element that cannot fit into a sector under NVS’s rules.

2. Build a live-record ledger

List every record ID that can remain live simultaneously, its maximum serialized payload length, and its update pattern. Include optional features, calibration variants, provisioning records, and records retained during an upgrade. Do not budget only the factory-default image.

For a first screening calculation, round each payload plus any appended CRC to W and add the aligned allocation-table entry. NVS uses eight-byte metadata before write-alignment effects. The v4.2.0 implementation aligns stored data and metadata, reserves sector-control space, and keeps room for deletion. Treat this ledger as a screening tool, not an exact free-space oracle.

Ledger item	What to count	Common omission
Live values	Maximum stored representation of every simultaneously live ID.	Rarely enabled features and future-reserved growth.
Per-record overhead	Aligned metadata, optional CRC, and padding.	Assuming payload bytes equal physical consumption.
Sector overhead	Close, reclaim, and deletion-related reservations for the pinned release.	Multiplying the complete sector size by N.
Replacement headroom	Space for the next largest legal update while previous live records still exist.	Assuming the old value disappears before its replacement is committed.
Operational reserve	Expected growth and the tested churn envelope.	Shipping at the narrowest passing image size.

A useful early rejection test is that the live set alone must fit below the gross ceiling of (N − 1) × S. Passing this test proves little: the ceiling ignores overhead and record placement. Failing it is enough to reject the proposed layout without wearing the test device through repeated attempts.

3. Exercise reclaim with changing data

Prepare an authorized disposable partition or a faithful test image. Preserve valuable product data elsewhere before any initialization; do not use a field settings region as a capacity experiment. Populate the maximum live set, verify it, then repeatedly replace values with genuinely different payloads.

NVS avoids programming when an ID’s data is unchanged, so a loop writing the same value can substantially underexercise the storage path. That optimization is documented in the NVS design notes. Include hot IDs, cold long-lived IDs, maximum-size values, and updates that grow or shrink their serialized length.

1. Run through enough sector transitions to observe repeated reclaim of every sector, rather than stopping after initial fill.
2. Record each API result, erase event, write duration, and the live-set checksum after remount.
3. Insert the largest permitted replacement at different points in the churn cycle.
4. Delete and recreate representative optional records without assuming deletion instantly produces contiguous room.
5. Interrupt selected writes and reclaim transitions on a test fixture, then remount and verify the product’s accepted recovery states.

The NVS API provides free-space calculation, but documents that it can be expensive, especially on SPI flash. Use it as a diagnostic measurement outside a deadline-critical path. Do not treat a positive total as proof that the next particular record can be accepted.

4. Interpret failures by layer

A size-related invalid-argument result should first trigger a check of the individual record limit and configuration. A no-space result after repeated reclaim indicates that another pass cannot make useful room under the implementation’s rules; increasing retries does not create capacity. A flash I/O error requires a separate device, protection, power, or driver investigation.

In v4.2.0, the write path stops with -ENOSPC after reclaim has cycled through the configured sectors without finding room. This protects against endless erase attempts. See the bounded reclaim loop. Preserve the failing image and record sequence so that the problem can be reproduced before changing layout.

Hypothetical sizing decision

Suppose a product needs 120 live records, each with a maximum 40-byte payload. For an illustrative four-byte write alignment with payload CRC disabled, each needs 48 bytes before sector overhead: 5,760 bytes in total. Two 4,096-byte sectors fail the gross live-set test because only 4,096 bytes remain after reserving one sector. Three sectors pass that initial screen with an 8,192-byte gross ceiling.

Three sectors are not yet approved. The team must include control entries, the largest replacement, optional records, and the churn/recovery matrix. These numbers are hypothetical arithmetic, not measured capacity or a recommended configuration for a particular board.

Release the layout only with a maximum live-record ledger and evidence of sustained reclaim progress. If a future feature expands the record set, repeat the qualification. “It fit at first boot” is a provisioning observation, not a steady-state capacity guarantee.