vringh_getdesc_user(9)

💖 vringh_getdesc_user — Kernel API Manual, bestie edition 💖

okay so this page is literally about vringh_getdesc_user(9) and it lives in the Kernel API Manual, and honestly? she's a whole vibe. grab a snack, we're getting descriptors from a userspace ring ✨

---

🌸 NAME 🌸

vringh_getdesc_user — get the next available descriptor from a userspace ring. that's it. that's the whole job. and she does it beautifully 💅

🦋 SYNOPSIS 🦋

int vringh_getdesc_user (struct vringh *vrh , struct vringh_iov *riov ,
struct vringh_iov *wiov , bool (*getrange)(struct vringh *vrh, u64 addr,
struct vringh_range *r) , u16 *head );

like yes, that's a lot of arguments. she's high-maintenance. we love her anyway 🫶

🎀 ARGUMENTS 🎀

• vrh — the userspace vring. this is the main character, the whole reason we're here 👑
• riov — where you put the readable descriptors (or NULL if you're not about that life)
• wiov — where you put the writable descriptors (or NULL, again, no pressure)
• getrange — the function you call to check ranges. yes it's a function pointer, yes it takes a struct vringh *vrh, a u64 addr, and a struct vringh_range *r. keep up bestie 💀
• head — the head index we received, for passing along to vringh_complete_user. don't lose it, it's important 🎯

✨ DESCRIPTION ✨

okay so the return values, listen up:

• returns 0 if there was no descriptor
• returns 1 if there was one
• or -errno if things went sideways 😭

ngl, on an error return you can actually tell the difference between an invalid ring and a single invalid descriptor: in the former case, *head will be vrh->vring.num. and like... you may be able to ignore an invalid descriptor, but there's not much you can do with an invalid ring. it's giving doomed fr fr 💀

and here's the cute part: you can totally reuse riov and wiov with subsequent calls 🎀 content gets overwritten and memory gets reallocated if more space is needed. sustainable queen behavior 🌈

⚠️ but when you don't have to use riov and wiov anymore, you should clean up them calling vringh_iov_cleanup to release the memory — even on error! like seriously, even on error. don't leave her hanging 😭

---

🧚 SEE ALSO 🧚

so much lore to explore, iykyk:

Kernel file ./drivers/vhost/vringh.c, plus:

vringh_kiov_advance(9), vringh_init_user(9), vringh_iov_pull_user(9), vringh_iov_push_user(9), vringh_complete_user(9), vringh_complete_multi_user(9), vringh_notify_enable_user(9), vringh_notify_disable_user(9), vringh_need_notify_user(9), vringh_init_kern(9), vringh_getdesc_kern(9), vringh_complete_kern(9), vringh_notify_enable_kern(9), vringh_notify_disable_kern(9), vringh_need_notify_kern(9), vringh_init_iotlb(9), vringh_init_iotlb_va(9), vringh_set_iotlb(9), vringh_getdesc_iotlb(9), vringh_iov_pull_iotlb(9), vringh_iov_push_iotlb(9), vringh_complete_iotlb(9), vringh_need_notify_iotlb(9)

---

that's the whole page, bestie, we ate and left no crumbs 🍓 this icon dropped from ./drivers/vhost back in October 2026 — stan forever, periodt 💜