API Reference

This reference is auto-generated from the Doxygen comments in ubi.h.

Usage Notes

Lifecycle: A UBI device must be initialized with ubi_device_init() before any other operations. After ubi_device_deinit(), the handle is invalid.

Thread safety: All public functions acquire a per-device mutex. Multiple threads may safely call UBI functions on the same device concurrently. Do not call from ISR context.

Error model: All functions return 0 on success or a negative errno code on failure. Common error codes:

Code

Meaning

-EINVAL

NULL pointer or invalid parameter (bad vol_id, lnum out of range, invalid geometry).

-ENOSPC

No free PEBs available for the requested operation.

-ENOENT

Volume with given vol_id does not exist.

-EEXIST

A volume with the same name but different configuration already exists.

-EROFS

Device is in degraded read-only mode (reserved PEB redundancy lost).

-EIO

Flash I/O error (read, write, or erase failure).

-ENOMEM

Heap allocation failure (k_malloc returned NULL).

-ECANCELED

Operation not applicable (e.g., resize on static volume, or leb_count unchanged).

Typical API call sequence:

ubi_device_init()          -- initialize device
ubi_volume_create()        -- create one or more volumes
ubi_leb_write()            -- write data to a LEB
ubi_leb_read()             -- read data from a LEB
ubi_device_erase_peb()     -- reclaim dirty PEBs (call periodically)
ubi_volume_remove()        -- remove volumes when no longer needed
ubi_device_deinit()        -- shut down and free resources

Defines

UBI_VOLUME_NAME_MAX_LEN

Maximum length of a UBI volume name including the null terminator.

Data Structures

group UBI Data Structures

Enums

enum ubi_volume_type

Types of UBI volumes.

Values:

enumerator UBI_VOLUME_TYPE_STATIC

Static volume — LEB count fixed after creation.

enumerator UBI_VOLUME_TYPE_DYNAMIC

Dynamic volume — can be resized at runtime.

struct ubi_mtd
#include <ubi.h>

Memory technology device (MTD) descriptor.

Describes the underlying flash partition used by UBI, including its geometry (write and erase block sizes).

Public Members

uint8_t partition_id

Flash partition identifier (from FIXED_PARTITION_ID).

size_t write_block_size

Minimum write block size in bytes.

size_t erase_block_size

Erase block (sector) size in bytes.

struct ubi_device_info
#include <ubi.h>

UBI device information.

Snapshot of the current device state returned by ubi_device_get_info().

Public Members

bool read_only_degraded

True when reserved PEB redundancy is lost. Metadata mutations (create/resize/remove) return -EROFS. Call ubi_device_erase_peb() periodically to attempt self-healing recovery.

size_t reserved_peb_count

Sum of leb_count across all volumes (PEBs reserved by volume configuration).

size_t free_peb_count

Free PEBs available for allocation.

size_t dirty_peb_count

Dirty PEBs awaiting erasure.

size_t bad_peb_count

Bad PEBs detected and retired.

size_t ec_avg

Average erase counter across all data PEBs.

size_t total_peb_count

Total usable data PEBs on the device.

size_t leb_size

Usable data size per LEB in bytes.

size_t volume_count

Number of volumes on the device.

struct ubi_volume_config
#include <ubi.h>

Volume configuration.

Describes the parameters of a UBI volume, used during volume creation and returned by ubi_volume_get_info().

Public Members

char name[UBI_VOLUME_NAME_MAX_LEN]

Volume name.

enum ubi_volume_type type

Volume type.

size_t leb_count

Number of logical erase blocks.

Device Management

group UBI Device Management

Functions for device initialization, shutdown, statistics, and PEB reclamation.

Note

Thread safety: all functions in this group use a per-device mutex. They must NOT be called from ISR context.

Functions

int ubi_device_init(const struct ubi_mtd *mtd, const struct ubi_crypto_config *crypto_cfg, struct ubi_device **ubi)

Initialize a UBI device on the given flash partition.

Scans the flash partition, formats it on first use, and builds the in-memory PEB and volume tables. On success, *ubi points to the allocated device handle; on failure, *ubi is set to NULL.

Only one active handle per flash partition is allowed. A second call with the same partition_id while a handle is still alive returns -EBUSY.

If the reserved PEB area has lost redundancy (one copy damaged), initialization still succeeds but the device enters degraded read-only mode — check ubi_device_info.read_only_degraded.

Parameters:

  • mtd – [in] Flash partition descriptor (caller retains ownership).

  • crypto_cfg – [in] Crypto configuration for secure mode, or NULL for plain. When non-NULL the secure backend is selected; when NULL the plain backend is selected.

  • ubi – [out] Pointer to receive the UBI device handle. Set to NULL on failure.

Return values:

  • 0 – Success (device may be degraded — query info to check).

  • -EINVAL – NULL pointer or invalid flash geometry.

  • -EBUSY – A handle for this partition is already active.

  • -ENOMEM – Heap allocation failure.

  • -ENODEV – Flash device not ready.

  • -ENOTSUP – Secure backend requested but not available.

  • -EIO – Unrecoverable flash I/O error.

Pre:

mtd fields must be non-zero and geometrically consistent: write_block_size > 0, erase_block_size > 0, erase_block_size % write_block_size == 0, partition size % erase_block_size == 0, partition must hold at least UBI_DEV_HDR_NR_OF_RES_PEBS + 1 PEBs.

int ubi_device_get_info(struct ubi_device *ubi, struct ubi_device_info *info)

Query the current state of a UBI device.

Populates info with PEB counts, LEB geometry, volume statistics, and the degraded-mode flag. This is a lightweight operation that reads only cached in-memory state (no flash I/O).

Parameters:

  • ubi – [in] UBI device handle (must be initialized).

  • info – [out] Device information output (zeroed, then populated).

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer.

int ubi_device_erase_peb(struct ubi_device *ubi)

Reclaim one dirty PEB and attempt reserved PEB bank recovery.

Normal path: erases the highest-priority dirty PEB and moves it to the free pool. Also attempts to recover bad PEBs via erase torture.

Recovery path: when the device is in degraded read-only mode (read_only_degraded is true), this function additionally attempts to recover the reserved PEB bank after its normal maintenance cycle. If recovery succeeds (corrupt reserved PEB erased and rewritten from the surviving copy), the degraded flag is cleared and the device returns to read-write operation. The application should keep calling this function periodically (e.g. in a GC loop) so that transient flash errors can self-heal without a reboot.

If no dirty PEBs exist and the device is healthy, returns 0 immediately.

Parameters:

ubi – [in] UBI device handle.

Return values:

  • 0 – Success (or no dirty PEBs to reclaim).

  • -EINVAL – NULL pointer.

  • -EROFS – Blocked by test write-shutdown (test builds only).

  • -EIO – Flash erase/write failure.

int ubi_device_deinit(struct ubi_device *ubi)

Shut down a UBI device and release all resources.

Acquires the device mutex to wait for any in-flight operations to complete, then frees all in-memory structures. The handle must not be used after this call.

Parameters:

ubi – [in] UBI device handle (may be partially initialized).

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer.

Pre:

The caller must ensure no other thread will start new operations on this handle after calling deinit. In-flight operations that already hold the mutex will complete before teardown proceeds.

Volume Management

group UBI Volume Management

Functions to create, resize, remove, and query volumes.

Note

Thread safety: all functions in this group use a per-device mutex. They must NOT be called from ISR context.

Note

Volume create, resize, and remove modify on-flash metadata in the reserved PEB area. They will fail with -EROFS if the device is in degraded read-only mode (see ubi_device_info.read_only_degraded).

Functions

int ubi_volume_create(struct ubi_device *ubi, const struct ubi_volume_config *vol_cfg, int *vol_id)

Create a new UBI volume.

If a volume with the same name already exists and has an identical configuration (type and leb_count), the call succeeds and returns the existing volume’s identifier (idempotent create). If the name matches but the configuration differs, -EEXIST is returned.

Parameters:

  • ubi – [in] UBI device handle (must be initialized).

  • vol_cfg – [in] Volume configuration (name, type, LEB count).

  • vol_id – [out] Assigned volume identifier.

Return values:

  • 0 – Success (including idempotent duplicate).

  • -EINVAL – NULL pointer, invalid name, invalid type, or leb_count == 0.

  • -ENOSPC – Not enough free PEBs for the requested LEB count.

  • -EEXIST – A volume with the same name but different configuration exists.

  • -EROFS – Device is in degraded read-only mode.

  • -ENOMEM – Heap allocation failure.

Pre:

vol_cfg->name must be NUL-terminated within UBI_VOLUME_NAME_MAX_LEN bytes and non-empty.

Pre:

vol_cfg->type must be a valid ubi_volume_type enumerator.

Pre:

vol_cfg->leb_count must be > 0.

int ubi_volume_resize(struct ubi_device *ubi, int vol_id, const struct ubi_volume_config *vol_cfg)

Resize an existing UBI volume.

Only dynamic volumes may be resized. The new leb_count must differ from the current one. When growing, the additional PEBs are reserved but not mapped until written. When shrinking, mapped LEBs beyond the new count are unmapped and their PEBs reclaimed to the dirty pool.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • vol_cfg – [in] New volume configuration (only leb_count is used).

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer or leb_count == 0.

  • -ENOENT – Volume with given vol_id does not exist.

  • -ECANCELED – Static volume, or leb_count unchanged.

  • -ENOSPC – Not enough free PEBs to grow.

  • -EROFS – Device is in degraded read-only mode.

int ubi_volume_remove(struct ubi_device *ubi, int vol_id)

Remove an existing UBI volume.

Removes the volume’s on-flash header and reclaims all mapped PEBs to the dirty pool.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer.

  • -ENOENT – Volume with given vol_id does not exist.

  • -EROFS – Device is in degraded read-only mode.

int ubi_volume_get_info(struct ubi_device *ubi, int vol_id, struct ubi_volume_config *vol_cfg, size_t *alloc_lebs)

Query volume configuration and allocation.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • vol_cfg – [out] Returned volume configuration.

  • alloc_lebs – [out] Number of LEBs currently mapped (with data written).

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer.

  • -ENOENT – Volume with given vol_id does not exist.

LEB I/O

group UBI LEB Operations

Functions to map, unmap, read, write, and query logical erase blocks.

Note

Thread safety: all functions in this group use a per-device mutex. They must NOT be called from ISR context.

Functions

int ubi_leb_write(struct ubi_device *ubi, int vol_id, size_t lnum, const void *buf, size_t len)

Write data to a logical erase block (LEB).

Maps the LEB if not already mapped, then writes len bytes from buf. Works for both static and dynamic volumes. len must not exceed the LEB data size. Unaligned lengths are internally padded to mtd.write_block_size.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • lnum – [in] Logical block number (must be < vol_cfg.leb_count).

  • buf – [in] Data buffer to write (caller retains ownership).

  • len – [in] Number of bytes to write from buf.

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer, invalid vol_id, or lnum out of range.

  • -EIO – Flash write failure.

int ubi_leb_read(struct ubi_device *ubi, int vol_id, size_t lnum, size_t offset, void *buf, size_t len)

Read data from a logical erase block (LEB).

Reads len bytes starting at offset from the LEB into buf. The LEB must be mapped (written to) before reading.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • lnum – [in] Logical block number (must be < vol_cfg.leb_count).

  • offset – [in] Byte offset within the LEB to start reading.

  • buf – [out] Buffer to receive the data.

  • len – [in] Number of bytes to read.

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer, invalid vol_id, lnum out of range, or offset+len overflow.

  • -EIO – Flash read failure.

int ubi_leb_map(struct ubi_device *ubi, int vol_id, size_t lnum)

Map a logical erase block (LEB) to a physical block.

Allocates a free PEB for the given LEB. The PEB is erased and headers are written. If the LEB is already mapped, returns success.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • lnum – [in] Logical block number (must be < vol_cfg.leb_count).

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer, invalid vol_id, or lnum out of range.

  • -ENOSPC – No free PEBs available.

int ubi_leb_unmap(struct ubi_device *ubi, int vol_id, size_t lnum)

Unmap a logical erase block (LEB).

Reclaims the PEB backing the given LEB to the dirty pool. If the LEB is not mapped, returns success.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • lnum – [in] Logical block number (must be < vol_cfg.leb_count).

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer, invalid vol_id, or lnum out of range.

int ubi_leb_is_mapped(struct ubi_device *ubi, int vol_id, size_t lnum, bool *is_mapped)

Check whether a logical erase block is mapped.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • lnum – [in] Logical block number (must be < vol_cfg.leb_count).

  • is_mapped – [out] Set to true if the LEB is mapped, false otherwise.

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer, invalid vol_id, or lnum out of range.

int ubi_leb_get_size(struct ubi_device *ubi, int vol_id, size_t lnum, size_t *size)

Get the data size of a mapped LEB.

Returns the number of user data bytes stored in the LEB. The LEB must be mapped.

Parameters:

  • ubi – [in] UBI device handle.

  • vol_id – [in] Volume identifier.

  • lnum – [in] Logical block number (must be < vol_cfg.leb_count).

  • size – [out] Data size in bytes stored in the LEB.

Return values:

  • 0 – Success.

  • -EINVAL – NULL pointer, invalid vol_id, or lnum out of range.

Test API (CONFIG_UBI_TEST_API_ENABLE)

These functions are only available when CONFIG_UBI_TEST_API_ENABLE=y. Do not enable in production builds. They are included in the Device Management group above.