STRUCT UBI_ATTACH_REQ(9)

👑 struct ubi_attach_req(9) — the kernel API manual, bestie edition ✨

okay so this is a page straight out of the Kernel API Manual and it's literally all about struct ubi_attach_req(9) — the little struct that tells UBI which MTD device to attach and how to do it. no cap, it's giving "setup instructions but make it ✨", so let's get into it 💅

---

🌸 NAME 🌸

struct ubi_attach_req — the attach MTD device request. that's it, that's the vibe 🎀

---

🦋 SYNOPSIS 🦋

here's the struct in all its glory, copy it exactly bestie, don't touch a thing:

struct ubi_attach_req {
    __s32 ubi_num;
    __s32 mtd_num;
    __s32 vid_hdr_offset;
    __s16 max_beb_per1024;
    __s8 disable_fm;
    __s8 need_resv_pool;
    __s32 wl_threshold;
    __s8 padding[4];
 };

---

💖 Members 💖

• ubi_num — the UBI device number you wanna create 🆕
• mtd_num — the MTD device number you're attaching 🔗
• vid_hdr_offset — the VID header offset (slap a 0 in here and UBI uses the defaults, easy peasy) ✨
• max_beb_per1024 — the maximum expected number of bad PEB per 1024 PEBs 😬
• disable_fm — whether to disable fastmap ⚡
• need_resv_pool — whether to reserve free pebs for filling pool/wl_pool 🏊
• padding — reserved for future, not used, and it has to be zeroed ⚠️ (yes really, zero it)

---

🔥 Description 🔥

so here's the whole situation: this data structure is what you use to specify the MTD device that UBI has to attach, plus all the parameters it has to use 🫶

the number that should be assigned to the new UBI device gets passed in ubi_num. but plot twist — UBI may automatically assign the number if UBI_DEV_NUM_AUTO is passed. in that case, the device number is returned in ubi_num 🔁 (so that field is doing double duty, iykyk).

most applications should pass 0 in vid_hdr_offset and let UBI use the default offset of the VID header within physical eraseblocks 💅 the default offset is the next min. I/O unit after the EC header. for example, it'll be offset 512 in the case of a 512 bytes page NAND flash with no sub-page support. or it'll be 512 in the case of a 2KiB page NAND flash with 4 512-byte sub-pages. cute, consistent, iconic ✨

but in rare cases, if this optimizes things, the VID header may be placed at a different offset 👀 for example, the boot-loader might do things faster if the VID header sits at the end of the first 2KiB NAND page with 4 sub-pages. since the boot-loader would not normally need to read EC headers (unless it needs UBI in RW mode), it might be faster to calculate ECC. this is a weird example, but it's a real-life example — not me making things up fr fr. so in this example, vid_hdr_offer would be 2KiB-64 bytes = 1984. note that this position is not even 512-bytes aligned, which is OK, because UBI is clever enough to realize this is the 4th sub-page of the first page and add the needed padding 🧚

now, max_beb_per1024 is the maximum amount of bad PEBs UBI expects on the UBI device per 1024 eraseblocks 🌈 this value is often given in another form in the NAND datasheet (min NVB, i.e. minimal number of valid blocks). the maximum expected bad eraseblocks per 1024 is then:

1024 * (1 - MinNVB / MaxNVB)

which gives 20 for most NAND devices 🔢 this limit is used in order to derive the amount of eraseblock UBI reserves for handling new bad blocks. if the device has more bad eraseblocks than this limit, UBI does not reserve any physical eraseblocks for new bad eraseblocks, but attempts to use available eraseblocks (if any). the accepted range is 0-768. if 0 is given, the default kernel value of CONFIG_MTD_UBI_BEB_LIMIT will be used 🌟

if disable_fm is not zero, ubi doesn't create a new fastmap even if the module param 'fm_autoconvert' is set, and an existed old fastmap will be destroyed after doing full scanning 💀 (dramatic but accurate, bestie)

wl_threshold defines the maximum difference between the highest and the lowest erase counter value of eraseblocks of this UBI device 👑 when this threshold is exceeded, UBI starts performing wear leveling by means of moving data from the eraseblock with a low erase counter to eraseblocks with a high erase counter. if wl_threshold is zero, the default kernel value of CONFIG_MTD_UBI_WL_THRESHOLD is used. the accepted range is 2-65536 🎚️

---

🎀 SEE ALSO 🎀

• kernel file ./include/uapi/mtd/ubi-user.h
• struct ubi_mkvol_req(9)
• struct ubi_rsvol_req(9)
• struct ubi_rnvol_req(9)
• struct ubi_ecinfo_req(9)
• struct ubi_leb_change_req(9)
• struct ubi_map_req(9)
• struct ubi_set_vol_prop_req(9)
• struct ubi_blkcreate_req(9)

go read them all, they're literally the rest of the friend group 🫶

---

and that's the whole page, bestie!! source is ./include/uapi/mtd, dated October 2026 — so go forth, zero your padding, and slay your attach requests 💜🦋✨