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.
This is a from-scratch implementation targeting resource-constrained embedded systems. On b_u585i_iot02a (STM32U5 Cortex-M33), the sample application build reports about 8.5 KB of flash for lib..__ubi__lib.a and 24 bytes of static RAM in that library (partition guard). See Introduction for methodology and test-build figures.
Start Here
New to UBI? Read these pages first:
Overview — key concepts (PEB, LEB, EC, VID) and how UBI works in 6 steps.
Introduction — why UBI exists, what it provides, and resource usage.
Getting Started — build, run tests, and evaluate on the simulator in minutes.
Understanding UBI
- Why UBI matters on Zephyr
- 1. Short version
- 2. What Zephyr provides today
- 3. The missing layer in the Zephyr stack
- 4. What plain UBI gives that Zephyr does not currently give as a subsystem
- 5. Why UBI is not redundant with NVS, ZMS, FCB, or LittleFS
- 6. What secure UBI adds on top of plain UBI
- 7. Why plain UBI is a good foundation for a filesystem
- 8. Why plain UBI is a good foundation for an LSM-tree database
- 9. Where UBI should not be used
- 10. Why this is a strong upstream candidate for Zephyr
- 11. References
- Overview
- Introduction
- Architecture Guide
- UBI Secure Architecture Guide
- 1. 30-second summary
- 2. High-level picture
- 3. What SECURE mode gives and what it does not
- 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
- Appendix A. Illustrative API surface with Doxygen
- Appendix B. Suggested roadmap items outside this spec
- Appendix C. Release checklist for SECURE
- Secure Volume Lifecycle
- Secure Recovery Notes
- Recovery Principles
- Scenario:
unmap → reboot(before erase) - Scenario:
unmap → erase → reboot - Scenario:
shrink → reboot(before erase) - Scenario:
shrink → erase → reboot - Scenario:
remove all volumes → reboot → create - Scenario: anchor migration during erase
- Scenario: stale anchor after reboot
- Emergency Reserve
- Dual-Bank Reserved Metadata
- Secure Runtime Policy
Using UBI
Quality and Testing
Project