Kconfig Reference

Enumerated reference for every Kconfig option exposed by the UBI library. The narrative guide (memory backend trade-offs, sizing worked example, log levels) lives in Configuration; this page is the lookup table.

Source of truth: lib/Kconfig, lib/Kconfig.plain, lib/Kconfig.secure.

Core options

These options are always available once CONFIG_UBI_ENABLE=y and apply to both plain and secure backends.

CONFIG_UBI_ENABLE

  • Type: bool

  • Default: n

  • Depends on: FLASH && FLASH_MAP && CRC

Master switch that pulls the UBI library into the build. Without this, no other UBI option has any effect.

See also: Quick Start.

CONFIG_UBI_MEM_BACKEND_STATIC

  • Type: bool (choice — mutually exclusive with UBI_MEM_BACKEND_HEAP)

  • Default: y (the default choice)

Allocate every UBI runtime structure (devices, volumes, rb-tree nodes, list nodes) from compile-time-sized k_mem_slab pools. Gives a deterministic RAM budget that is fully isolated from the application heap. Requires CONFIG_UBI_MAX_NR_OF_DEVICES, CONFIG_UBI_MAX_NR_OF_DATA_PEBS, and (for plain mode) CONFIG_UBI_MAX_NR_OF_VOLUMES to be tuned to the flash geometry.

See also: Configuration § Memory Backend and Memory Sizing Guide.

CONFIG_UBI_MEM_BACKEND_HEAP

  • Type: bool (choice)

  • Default: off

Use k_malloc/k_free from the global Zephyr heap for all UBI allocations. No compile-time pool sizing required, at the cost of sharing memory with the rest of the application.

See also: Configuration § Memory Backend.

CONFIG_UBI_MAX_NR_OF_DEVICES

  • Type: int

  • Default: 1

  • Range: 1–4

Upper limit on the number of UBI device handles that can exist simultaneously. Multiplies every static-backend slab pool size.

CONFIG_UBI_MAX_NR_OF_DATA_PEBS

  • Type: int

  • Default: 14

  • Range: 1–4096

Upper limit on the number of data PEBs (total PEBs minus reserved PEBs) for a single UBI device. Used by the static backend to size the small-item slab pool. Must be ≥ total_data_peb_count of every flash partition managed by UBI.

See also: Configuration § Memory Sizing Guide.

CONFIG_UBI_LOG_LEVEL_*

  • Type: Zephyr log-level choice

Standard Zephyr log-level family (OFF / ERR / WRN / INF / DBG) generated by subsys/logging/Kconfig.template.log_config for the ubi log module.

See also: Configuration § Log Level.

CONFIG_UBI_TEST_API_ENABLE

  • Type: bool

  • Default: n

Expose ubi_device_get_peb_ec() and ubi_device_check_invariants() from lib/include/ubi_test.h so ZTEST suites can inspect internal state. Do not enable in production builds — it widens the public API surface.

CONFIG_UBI_TEST_MEM_STATS

  • Type: bool

  • Default: n

  • Depends on: UBI_TEST_API_ENABLE && UBI_MEM_BACKEND_STATIC

When set, UBI logs slab-pool high-water marks during ubi_device_deinit() to help dimension the static backend.

CONFIG_UBI_TEST_FAULT_INJECTION

  • Type: bool

  • Default: n

  • Depends on: UBI_TEST_API_ENABLE

Wraps every memory allocation in a test-controllable hook that can be configured to fail after N calls. Used by the transactional-safety ZTESTs. Do not enable in production builds.

Plain mode options

Available unconditionally under CONFIG_UBI_ENABLE=y. None of these options depend on the secure backend.

CONFIG_UBI_DEV_HDR_NR_OF_RES_PEBS

  • Type: int

  • Default: 2

  • Range: 2–4

Number of PEBs reserved at the start of the partition for the device-header / volume-header dual-bank metadata. Two PEBs are always kept active (true dual-bank); additional PEBs are cold spares promoted when an active reserved PEB fails permanently. Increasing this reduces the data-PEB count.

See also: Architecture Guide § On-Flash Layout.

CONFIG_UBI_MAX_NR_OF_VOLUMES

  • Type: int

  • Default: 10

  • Range: 1–128

Upper limit on the number of volumes that can be created on a single UBI device. Each volume header occupies 48 bytes on the reserved PEBs, so the practical ceiling is also constrained by the erase-block size.

CONFIG_UBI_PEB_WRITE_RETRY_COUNT

  • Type: int

  • Default: 3

  • Range: 1–5

How many times the I/O layer retries a failed write on a data PEB (EC header, VID header, LEB data) before propagating the error. Set to 1 for a single attempt with no retry. Reserved-PEB writes use a separate multi-PEB fallback and are not subject to this knob.

CONFIG_UBI_BAD_PEB_TORTURE_CYCLES

  • Type: int

  • Default: 3

  • Range: 1–10

Maximum number of bad PEBs the torture pass processes per ubi_device_erase_peb() call. Bounds the worst-case latency of the erase / reclaim path.

CONFIG_UBI_BAD_PEB_TORTURE_MAX_PER_ERASE

  • Type: int

  • Default: 1

  • Range: 1–10

When a PEB is marked bad at runtime, the torture test attempts up to this many erases. If any erase succeeds the PEB is considered healthy and goes back to the free pool; if every attempt fails, the PEB stays bad permanently.

Secure mode options

All options below live behind CONFIG_UBI_SECURE=y.

CONFIG_UBI_SECURE

  • Type: menuconfig (bool)

  • Default: n

  • Depends on: UBI_ENABLE && MBEDTLS && MBEDTLS_PSA_CRYPTO_C && ENTROPY_GENERATOR && MBEDTLS_ENTROPY_POLL_ZEPHYR

  • Selects: PSA_WANT_ALG_CCM, PSA_WANT_ALG_HKDF, PSA_WANT_ALG_SHA_256, PSA_WANT_KEY_TYPE_AES

Enable the secure backend. When set, devices initialised with a non-NULL secure_cfg use AES-128-CCM authenticated encryption for every on-flash structure. Pulls in PSA Crypto via mbedTLS and requires a platform CSPRNG.

See also: Secure Architecture: Overview, Secure UBI Workflow.

CONFIG_UBI_SECURE_MAX_KEY_VERSIONS

  • Type: int

  • Default: 4

  • Range: 1–255

Upper bound on the number of distinct key versions active during a single attach session. Sizes per-key-version bookkeeping arrays and caps the length of ubi_secure_policy.allowed_key_versions.

CONFIG_UBI_SECURE_METADATA_COUNTER_BUDGET

  • Type: int

  • Default: 1000000

Maximum AEAD encrypt invocations for metadata headers (device, volume, EC, VID) per (domain, key_version) before a key-rotation event is triggered.

See also: Secure On-Flash Format Specification § 13 Key lifecycle, inventory, and retirement.

CONFIG_UBI_SECURE_METADATA_TOTAL_AUTH_BYTES_BUDGET

  • Type: int

  • Default: 100000000

Maximum cumulative authenticated bytes (AAD + plaintext) for metadata AEAD operations per (domain, key_version).

CONFIG_UBI_SECURE_LEB_WRITE_BUDGET

  • Type: int

  • Default: 1000000

Maximum AEAD encrypt invocations for LEB data records per (key_version, volume_id) before a key-rotation event is triggered.

CONFIG_UBI_SECURE_LEB_TOTAL_AUTH_BYTES_BUDGET

  • Type: int

  • Default: 100000000

Maximum cumulative authenticated bytes (AAD + plaintext) for LEB AEAD operations per (key_version, volume_id).

CONFIG_UBI_SECURE_ROTATE_SOON_PCT

  • Type: int

  • Default: 80

  • Range: 1–99

Soft rotation threshold. When usage reaches this percentage of any budget, the secure backend emits KEY_ROTATE_SOON. The application should prepare a replacement key.

See also: Secure UBI Workflow § Key rotation workflow.

CONFIG_UBI_SECURE_ROTATE_NOW_PCT

  • Type: int

  • Default: 95

  • Range: 1–100

Hard rotation threshold. When usage reaches this percentage of any budget, the secure backend emits KEY_ROTATE_NOW. If no replacement key is available, writes may be rejected.

CONFIG_UBI_SECURE_LEB_CHUNKED

  • Type: bool

  • Default: n

Use multiple AEAD tags per LEB for large PEB geometries (typically

4 KiB usable LEB area). Allows partial-LEB reads without authenticating the entire payload, at the cost of one 16-byte tag per chunk on flash.

See also: Secure On-Flash Format Specification § 7 Secure record formats (chunked layout).

CONFIG_UBI_SECURE_LEB_CHUNK_SIZE

  • Type: int

  • Default: 4096

  • Range: 256–65536

  • Depends on: UBI_SECURE_LEB_CHUNKED

Size in bytes of each independently authenticated chunk within a secure LEB record. Smaller values give finer-grained reads but inflate per-LEB overhead.

CONFIG_UBI_SECURE_PEB_CACHE

  • Type: bool

  • Default: y

Allocate a reusable eraseblock-sized buffer for AEAD encrypt / decrypt staging. Required by the secure read and write paths; disabling it is for very specific embedded scenarios only.

CONFIG_UBI_SECURE_PEB_CACHE_STATIC

  • Type: bool

  • Default: n

  • Depends on: UBI_SECURE_PEB_CACHE

Allocate the PEB staging buffer at compile time (statically) rather than at device-init time through the configured memory backend.

CONFIG_UBI_SECURE_FRESHNESS_SYNC_DELTA

  • Type: int

  • Default: 0

  • Range: 0–65535

Number of flash-mutating operations between sync_freshness callbacks. 0 means sync after every commit (smallest rollback window, most callbacks). Higher values reduce callback frequency at the cost of a larger worst-case rewind.

See also: Secure UBI Workflow § 4.3 Freshness store.

CONFIG_UBI_SECURE_STRICT_RO_ON_RNG_FAILURE

  • Type: bool

  • Default: y

When the platform RNG cannot produce a fresh salt, enter sticky read-only mode instead of just rejecting the current write.

CONFIG_UBI_SECURE_STRICT_RO_ON_POLICY_FAILURE

  • Type: bool

  • Default: y

When the check_freshness callback rejects at attach time, or a rollback policy mismatch is detected post-attach, enter sticky read-only mode.

CONFIG_UBI_SECURE_STRICT_RO_ON_FRESHNESS_SYNC_FAILURE

  • Type: bool

  • Default: n

When the sync_freshness callback returns non-zero, enter sticky read-only mode. The failing commit itself is not rolled back.

CONFIG_UBI_SECURE_TEST_FAULT_INJECTION

  • Type: bool

  • Default: n

  • Depends on: UBI_TEST_FAULT_INJECTION

Exposes test hooks for injecting failures into PSA crypto operations (AEAD encrypt/decrypt, HKDF, RNG, freshness callbacks). Used by secure-backend error-handling ZTESTs. Do not enable in production builds.