UBI on Zephyr

Unsorted Block Images (UBI) is a volume management layer for raw flash devices running Zephyr RTOS. It provides wear-leveling, bad block management, and multiple logical volumes on a single flash partition — similar to what LVM does for block devices.

Note

Release status: v1.0.0. The library API and the on-flash format (plain and secure) are stable; breaking changes require a major version bump. CI, coverage, and metrics badges live on the repository README. See the CHANGELOG for the full release history.

---

Where to start

Pick the card that matches what you came here to do.

📖 New here? Understand what UBI is and whether it fits your project. What is UBI? Comparison: UBI vs LittleFS vs NVS vs ZMS Concepts at a Glance	🔧 Want to integrate? Build, configure, and write your first volume. Quick Start Configuration Cookbook
🏗 How does it work? Read the design — plain UBI and Secure UBI explained. Architecture Guide Secure Architecture: Overview	📚 Looking up details? Reference material for implementers and auditors. API Reference Kconfig Reference Glossary Secure On-Flash Format Specification

---

Getting Started

• What is UBI?
  • In one paragraph
  • Where UBI sits in the stack
  • Why UBI on Zephyr?
  • Features
  • Non-goals
  • When to use UBI
  • When not to use UBI
  • What’s next
• Comparison: UBI vs LittleFS vs NVS vs ZMS
  • Where UBI sits in the storage stack
  • At a glance
  • Picking the right one
  • Decision shortcut
  • When the gap matters most
  • Encryption
  • See also
• Quick Start
  • Choose your path
  • 1. Initialise the workspace
  • 2. Build and run the sample on native_sim
  • 3. Your first volume — the 30-line version
  • What’s next
• Concepts at a Glance
  • Five key concepts
  • How it works in six steps
  • What’s next

User Guide

• Plain UBI Workflow
  • 1. When to use plain UBI
  • 2. Prerequisites checklist
  • 3. Lifecycle of a UBI handle
  • 4. Creating, using, removing volumes
  • 5. Reading and writing LEBs
  • 6. Garbage collection
  • 7. Error handling
  • 8. Degraded read-only mode
  • 9. Tear-down
  • 10. What’s next
• Secure UBI Workflow
  • 1. When to enable Secure UBI
  • 2. Prerequisites checklist
  • 3. Setting up secure_cfg
  • 4. Callback contracts
  • 5. Key rotation workflow
  • 6. Event handling
  • 7. Retirement
  • 8. What’s next
• Environment Setup
  • Prerequisites
  • 1. Initialize Workspace
  • 2. Code Formatting (Optional)
  • 3. Build
  • 4. Run Tests
  • 5. Flash Sample Application
  • 6. Measure Flash Usage
  • 7. Resource Reports
  • 8. Code Coverage
• Configuration
  • Kconfig Options
  • Flash Partition (DeviceTree)
  • Zephyr Module Integration
• Cookbook
  • 1. UBI on STM32U5 (b_u585i_iot02a)
  • 2. UBI on nRF5340
  • 3. A/B firmware slots with two static volumes
  • 4. Periodic garbage collection in a workqueue
  • 5. Implementing key rotation with PSA
  • 6. Implementing a freshness store with Zephyr Settings

Architecture

• Architecture Guide
  • 30-Second Summary
  • Core Invariants
  • Flash Storage Primer
  • Architecture Overview
  • On-Flash Layout
  • Header Structures
  • In-RAM Data Structures
  • PEB Lifecycle
  • Device Initialization
  • Erased-State Detection
  • Thread Safety
  • Wear-Leveling
  • Dual-Bank Mechanism
  • Volume Management
• Secure Architecture: Overview
  • 1. What Secure UBI is
  • 2. Threat model
  • 3. Key hierarchy
  • 4. Application contract
  • 5. Key lifecycle
  • 6. Resource profile
  • 7. What’s next

Reference

• API Reference
  • Usage Notes
  • Defines
  • Data Structures
  • Device Management
  • Volume Management
  • LEB I/O
  • Test API (CONFIG_UBI_TEST_API_ENABLE)
• Kconfig Reference
  • Core options
  • Plain mode options
  • Secure mode options
• Error Codes
  • Lookup table
  • Per-code notes
  • Cross-reference
• Glossary
  • See also
• Secure On-Flash Format Specification
  • 1. 30-second summary
  • 2. High-level picture
  • 3. Scope
  • 4. Terminology and invariants
  • 5. Cryptographic profile
  • 6. Key material and key hierarchy
  • 7. Secure record formats
  • 8. Nonce and AAD
  • 9. Freshness and recovery state
  • 10. Initialization and recovery
  • 11. Secure write paths
  • 12. Secure read paths
  • 13. Key lifecycle, inventory, and retirement
  • 14. Events, policy, and read-only transitions
  • 15. Kconfig surface
  • 16. API shape (summary)
  • 17. Cost model
  • 18. References
  • 19. Secure volume lifecycle
  • 20. Secure recovery scenarios
  • 21. Runtime policy
  • Appendix A. Illustrative API surface with Doxygen

Project

• Roadmap
• Contributing
• Test Strategy
• Changelog