vringh_getdesc_iotlb(9)

📦 version 7.3.1, in nixpkgs unstable

💅 vringh_getdesc_iotlb — the tea ☕

okay so this is a page from the Kernel API Manual, and bestie, it's literally about grabbing the next available descriptor off a ring that's got an IOTLB. yes, that kind of ring. sit down, we're doing this 🫶

✨ NAME ✨

vringh_getdesc_iotlb — get next available descriptor from ring with IOTLB. that's it, that's the whole vibe 💫

🌸 SYNOPSIS 🌸

int vringh_getdesc_iotlb (struct vringh *vrh , struct vringh_kiov *riov
, struct vringh_kiov *wiov , u16 *head , gfp_t gfp );

like, five whole arguments. she's high-maintenance but she slays 💅

🎀 ARGUMENTS 🎀

  • vrh — the kernelspace vring. the main character of this whole operation 👑
  • riov — where to put the readable descriptors (or NULL). no readable stuff? pass NULL, she's flexible ✨
  • wiov — where to put the writable descriptors (or NULL). same deal, NULL is totally fine 🌸
  • head — head index we received, for passing to vringh_complete_iotlb. hold onto this one, you'll need it later 🎀
  • gfp — flags for allocating larger riov/wiov. that's the grow-up budget 😌

🦋 DESCRIPTION 🦋

Returns 0 if there was no descriptor, 1 if there was, or -errno. three moods, pick one 💀

⚠️ okay so 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. so like, peek at *head, it's giving you a hint 🙈

and honestly? you may be able to ignore an invalid descriptor, but there's not much you can do with an invalid ring. one is an oopsie, the other is a whole situation 😭

💖 also: you can reuse riov and wiov with subsequent calls. content is overwritten and memory reallocated if more space is needed. she's recyclable, we love sustainability 🌈

but fr fr — when you don't have to use riov and wiov anymore, you should clean up them calling vringh_kiov_cleanup to release the memory, even on error! yes, even on error. especially on error. do not skip the cleanup, bestie, the memory will simply not be okay 🫶

👑 SEE ALSO 👑

Kernel file ./drivers/vhost/vringh.c — and the whole friend group:

and that's the whole page, periodt 💅✨

this little masterpiece lives in ./drivers/vhost, dated October 2026, and if you ever need to cite it in a group chat the full name is vringh_getdesc_iotlb(9) — mwah, bye 🍓🧚💜

📦 where this page comes from