hv_create_ring_sysfs(9)

💅 hv_create_ring_sysfs(9) — the kernel API manual, bestie edition

okay so this is a page from the kernel API manual (hv_create_ring_sysfs(9), yes that's the whole vibe) and it's literally about making a sysfs node appear so userspace can touch a channel's ring buffer. it's giving "backstage pass, but only if the bouncer says so." 🎀

---

✨ NAME ✨

hv_create_ring_sysfs — create the "ring" sysfs entry that corresponds to the ring buffers for a channel.

---

🌸 SYNOPSIS 🌸

int hv_create_ring_sysfs (struct vmbus_channel *channel , int
       (*hv_mmap_prepare_ring_buffer)(struct vmbus_channel *channel, struct
       vm_area_desc *desc) );

---

🦋 ARGUMENTS 🦋

• channel — pointer to the vmbus_channel structure 🫶
• hv_mmap_prepare_ring_buffer — a function pointer for initializing the function that gets called on the mmap of the channel's "ring" sysfs node, which is the node for that channel's ring buffer. the function pointer is of the type below:

int (*hv_mmap_prepare_ring_buffer)(struct vmbus_channel
*channel, struct vm_area_desc *desc))

so it takes a pointer to the channel and a pointer to vm_area_desc (used for mmap_prepare) as its arguments. no cap. ✨

---

🔥 DESCRIPTION 🔥

okay so here's the tea: the sysfs node for a channel's ring buffer gets created along with the other fields, but its visibility is disabled by default. and sysfs creation needs to be controlled depending on when the use-case is actually running.

for example (iconic example, honestly): an HV_NIC device is used either by uio_hv_generic or by hv_netvsc at any given point of time, and the "ring" sysfs is needed only when uio_hv_generic is bound to that device. so to avoid exposing the ring buffer by default, this function is the one responsible for enabling the visibility of the ring so userspace can use it. 💅

---

🌈 NOTE 🌈

race conditions can happen with userspace, and it is not encouraged to create new use-cases for this. 😭

this was added to maintain backward compatibility, while solving one of the race conditions in uio_hv_generic while creating sysfs. see the comments with vmbus_add_dynid and vmbus_device_register. 🫶

returns 0 on success or an error code on failure. simple as that, periodt.

---

👑 SEE ALSO 👑

• kernel file ./drivers/hv/vmbus_drv.c
• __vmbus_driver_register(9)
• vmbus_driver_unregister(9)
• hv_remove_ring_sysfs(9)
• vmbus_allocate_mmio(9)
• vmbus_free_mmio(9)

---

and that's the whole page, bestie 💖 this one lives at ./drivers/hv and it's dated October 2026 — so yeah, future-coded manual page, we stan. go forth and only expose your ring buffers responsibly ✨🎀🦋