virtqueue_add_sgs(9)

📦 version 7.3.1, in nixpkgs unstable

💖 virtqueue_add_sgs(9) — Kernel API Manual 💖

okay so bestie, pull up a chair, because this is the function that actually hands your buffers over to the other end of a virtqueue. it's giving "main character of the virtio data path" energy, ngl.

✨ NAME ✨

virtqueue_add_sgs — expose buffers to other end 🫶

🌸 SYNOPSIS 🌸

int virtqueue_add_sgs (struct virtqueue *_vq , struct scatterlist *sgs[]
, unsigned int out_sgs , unsigned int in_sgs , void *data , gfp_t gfp );

like, yes, that's a lot of parameters. breathe. we'll go through every single one, i promise. 💅

🎀 ARGUMENTS 🎀

  • _vq — the struct virtqueue we're talking about. the queue in question. the one. 👑
  • sgs — array of terminated scatterlists. yes, terminated — the list has to end properly, do not leave it hanging, that's rude. ✨
  • out_sgs — the number of scatterlists readable by the other side. (out = they read from you, iykyk)
  • in_sgs — the number of scatterlists which are writable (and these come after the readable ones — order matters, bestie, don't shuffle them 🙈)
  • data — the token identifying the buffer. your little name tag so you can tell your buffers apart later. 🏷️
  • gfp — how to do memory allocations (if necessary). you know, the gfp flags. only if it needs to allocate at all. 🌈

🦋 DESCRIPTION 🦋

okay so the actual vibe:

caller must ensure we don't call this with other virtqueue operations at the same time (except where noted). 🚨

like, do NOT be out here doing parallel virtqueue ops from multiple places at once. this function does not want to share. it's an only-child situation. the docs literally say so.

it returns zero or a negative error (ie. ENOSPC, ENOMEM, EIO). so zero = slay, negative = something went sideways. 💀

NB: ENOSPC is a special code that is only returned on an attempt to add a buffer to a full VQ. it indicates that some buffers are outstanding and that the operation can be retried after some buffers have been used. so like — it's not a failure failure, it's a "come back later, the queue is full" kind of situation. very "we're at capacity, try again after some buffers free up" energy. 🔥

🧚 SEE ALSO 🧚

everything lives in the kernel file ./drivers/virtio/virtio_ring.c, and here's the whole friend group:

and that's the whole page, bestie. 🫶 this one ships from ./drivers/virtio and it's dated October 2026 — so like, future-dated documentation, iconic behavior honestly. 💜 mwah, go expose some buffers responsibly. 💅✨🎀

📦 where this page comes from