xa_alloc_cyclic_bh(9)

✨ xa_alloc_cyclic_bh(9) — the Kernel API Manual glow-up ✨

okay so bestie, buckle up, because this one is a whole mood. this is a page from the Kernel API Manual about xa_alloc_cyclic_bh, and the way that it literally just finds somewhere to store this entry in the XArray… iconic behaviour honestly. 🦋

---

🌸 NAME 🌸

xa_alloc_cyclic_bh — Find somewhere to store this entry in the XArray.

no fr, that's the entire job. it's giving "personal assistant for your XArray" energy. 💅

---

🎀 SYNOPSIS 🎀

int xa_alloc_cyclic_bh (struct xarray *xa , u32 *id , void *entry ,
       struct xa_limit limit , u32 *next , gfp_t gfp );

look at her. six arguments. main character energy fr fr. 👑

---

🫶 ARGUMENTS 🫶

• xa — the XArray. that's the whole vibe container, the xarray in question. 💖
• id — Pointer to ID. yeah, a pointer, capital letters, we're doing this.
• entry — New entry. the thing you're shoving in there.
• limit — Range of allocated ID. this is your "please stay between these numbers" situation.
• next — Pointer to next ID to allocate. this is where the cyclic-ness kicks in.
• gfp — Memory allocation flags. lowkey the most "adult" argument here.

---

💜 DESCRIPTION 💜

okay so here's the tea ☕ — this function finds an empty entry in xa between limit.min and limit.max, stores the index into the id pointer, then stores the entry at that index. 🎯

A concurrent lookup will not see an uninitialised id. we love a safe handoff, no cap. 🫶

The search for an empty entry will start at next and will wrap around if necessary. it's giving "loop back to the start like nothing happened" energy. 🔁

⚠️ big one, bestie: this must only be operated on an xarray initialized with flag XA_FLAGS_ALLOC set in xa_init_flags. do not come in here with some other xarray and expect slay behaviour. that's a vibe violation. 💀

Note that callers interested in whether wrapping has occurred should use __xa_alloc_cyclic instead. iykyk — different function, different little treat. 🌈

---

🧚 CONTEXT 🧚

Any context. literally any of them, she's flexible. 💅

Takes and releases the xa_lock while disabling softirqs. and yes she may sleep if the gfp flags permit — she's allowed to nap, we respect the nap. 😴✨

---

🔥 RETURN 🔥

• 0 — if the allocation succeeded. slay! 🎉
• -ENOMEM — if memory could not be allocated. the classic "no memory for u" moment. 😭
• -EBUSY — if there are no free entries in limit. the range said "full", the range meant it. 💀

---

👑 SEE ALSO 👑

Kernel file ./include/linux/xarray.h

and now, the friend group. every single one of them, in order, no skipping — this is the whole group chat: 🫶

xa_mk_value(9), xa_to_value(9), xa_is_value(9), xa_tag_pointer(9), xa_untag_pointer(9), xa_pointer_tag(9), xa_is_zero(9), xa_is_err(9), xa_err(9), struct xa_limit(9), struct xarray(9), DEFINE_XARRAY_FLAGS(9), DEFINE_XARRAY(9), DEFINE_XARRAY_ALLOC(9), DEFINE_XARRAY_ALLOC1(9), xa_init_flags(9), xa_init(9), xa_empty(9), xa_marked(9), xa_for_each_range(9), xa_for_each_start(9), xa_for_each(9), xa_for_each_marked(9), xa_store_bh(9), xa_store_irq(9), xa_erase_bh(9), xa_erase_irq(9), xa_cmpxchg(9), xa_cmpxchg_bh(9), xa_cmpxchg_irq(9), xa_insert(9), xa_insert_bh(9), xa_insert_irq(9), xa_alloc(9), xa_alloc_bh(9), xa_alloc_irq(9), xa_alloc_cyclic(9), xa_alloc_cyclic_irq(9), xa_reserve(9), xa_reserve_bh(9), xa_reserve_irq(9), xa_release(9), xa_is_sibling(9), xa_is_retry(9), xa_is_advanced(9), xa_update_node_t(9), XA_STATE(9), XA_STATE_ORDER(9), xas_error(9), xas_set_err(9), xas_invalid(9), xas_valid(9), xas_is_node(9), xas_reset(9), xas_retry(9), xas_reload(9), xas_set(9), xas_advance(9), xas_set_order(9), xas_set_update(9), xas_next_entry(9), xas_next_marked(9), xas_for_each(9), xas_for_each_marked(9), xas_for_each_conflict(9), xas_prev(9), xas_next(9)

like i said. the whole group chat. 💀💖

---

and that's the page, bestie! 🎀 this cutie lives in ./include/linux and the manual's dated October 2026 — so yeah, she's from the future, and she ate. periodt. 💅✨🔥