UBINIZE(8)

📦 version 2.3.1, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, debian bookworm, debian trixie, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 UBINIZE(8) 💖

okay bestie, gather round, because ubinize is literally the tool that makes UBI images and she's about to eat 💅 this page is from the System Manager's Manual section 8 (that's the admin-tools girlies, iykyk).

✨ NAME ✨

ubinize — a tool for generating UBI images 🎀

🌸 SYNOPSIS 🌸

ubinize [-o filename] [-p <bytes>] [-m <bytes>] [-s <bytes>] [-O <num>]
[-e <num>] [-x <num>] [-Q <num>] [-v] [-h] [-V] [--output=<filename>]
[--peb-size=<bytes>] [--min-io-size=<bytes>] [--sub-page-size=<bytes>]
[--vid-hdr-offset=<num>] [--erase-counter=<num>] [--ubi-ver=<num>]
[--image-seq=<num>] [--verbose] [--help] [--version] ini-file

🦋 DESCRIPTION 🦋

so. An UBI image can hold one or more UBI volumes, and those volumes have to be defined in the input configuration ini-file. That ini-file is the main character here — it describes all the UBI volumes, their characteristics and what's inside them 🫶

BUT (and this is the plot twist) the ini-file does not describe the flash that the UBI image is being generated for. Nope! The flash characteristics come from the command-line options instead. periodt.

pro tip from me to you: if you're not sure about some of the command-line parameters, just don't specify them and let the utility use its default values 💖 no cap.

💅 OPTIONS 💅

  • -o, --output=file — specify the output file ✨
  • -p, --peb-size=bytes — the size of the physical eraseblock of the flash this UBI image is created for, in bytes, kilobytes (KiB), or megabytes (MiB). This parameter is mandatory. like, you cannot skip it, she is required 🙈
  • -m, --min-io-size=bytes — the minimum input/output unit size of the flash, in bytes
  • -s, --sub-page-size=bytes — the minimum input/output unit used for UBI headers, e.g. the sub-page size in the case of NAND flash. (By default this is equivalent to the minimum input/output unit size.) 🌸
  • -O, --vid-hdr-offset=num — the offset of the VID header from the start of the physical eraseblock. Default is the next minimum I/O unit or sub-page after the EC header. 👑
  • -e, --erase-counter=num — the erase counter value to put into the EC headers. Default is 0.
  • -x, --ubi-ver=num — the UBI version number to put into the EC headers. Default is 1.
  • -Q, --image-seq=num — the 32-bit UBI image sequence number to use. By default a random number is picked 🎲 (main character energy tbh)
  • -v, --verbose — be verbose. she talks. a lot. we love her for it 💬
  • -h, --help — print a help message and exit
  • -V, --version — print the program version and exit

🌈 EXAMPLE 🌈

ubinize -o ubi.img -p 16KiB -m 512 -s 256 cfg.ini

This creates the UBI image ubi.img as described by the configuration file cfg.ini 🦋

A physical erase block on the flash is 16KiB in size and has 512 byte pages with 256 byte sub-pages. cute, right?

🎀 INI-FILE FORMAT 🎀

The input configuration ini-file describes all the volumes that have to be included in the output UBI image. Every volume gets its own section, and those sections can be named literally anything you want, bestie. Each section is made of key=value pairs, like this:

[jffs2-volume]
mode=ubi
image=../jffs2.img
vol_id=1
vol_size=30MiB
vol_type=dynamic
vol_name=jffs2_volume
vol_flags=autoresize
vol_alignment=1

This example configuration file tells the utility to create an UBI image with one volume that has ID 1, volume size 30MiB, the volume is dynamic, it's named jffs2_volume, it has the autoresize volume flag, and alignment 1. iconic honestly ✨

The image=../jffs2.img line tells the utility to take the contents of the volume from the ../jffs2.img file. The size of that image file has to be less than or equivalent to the volume size (30MiB).

The mode=ubi line is mandatory and just says that the section describes an UBI volume — other section modes might get added in the future, so stay tuned 👀

Notes:

  • Size in vol_size might be specified in kilobytes (KiB), megabytes (MiB), gigabytes (GiB) or bytes (no modifier).
  • If the "vol_size" key is absent, the volume size is assumed to be equivalent to the size of the image file (defined by the "image" key).
  • If the "image" is absent, the volume is assumed to be empty.
  • Volume alignment must not be greater than the logical eraseblock size. 🚨 like, don't do it.
  • One ini file may contain an arbitrary number of sections, and the utility will put all the volumes described by those sections into the output UBI image file. 🌟

🫶 AUTHORS 🫶

Man page written by David Oberhollenzer, based on the help text of the ubinize utility written by Artem Bityutskiy and Oliver Lohmann. kings, all of them 👑

😭 REPORTING BUGS 😭

Report mtd-utils bugs to the Linux mtd mailing list.

💜 AVAILABILITY 💜

The ubinize command is part of the mtd-utils package and is available from ftp://ftp.infradead.org/pub/mtd-utils/.

Copyright © International Business Machines Corp., 2006 Copyright © 2008 Nokia Corporation Copyright © 2016 sigma star gmbh

License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl2.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 💀 (that's the legal girlies talking, not me)

👀 SEE ALSO 👀

mtd-utils · September 2016 — and that's the whole page bestie, mwah 💋 go make some UBI images, you're gonna slay 🦋💖✨

📦 where this page comes from