SF_BUF(9)

💖 SF_BUF(9) 💖

okay bestie, gather round, because this is a Kernel Developer's Manual page (section 9, the cool section) and it's all about sf_buf — the girlies who manage temporary kernel address space mapping for memory pages ✨

---

🌸 NAME 🌸

sf_buf — manage temporary kernel address space mapping for memory pages

---

🎀 SYNOPSIS 🎀

#include <sys/sf_buf.h>

struct sf_buf *
sf_buf_alloc(struct vm_page *m, int flags);

void
sf_buf_free(struct sf_buf *sf);

vm_offset_t
sf_buf_kva(struct sf_buf *sf);

struct vm_page *
sf_buf_page(struct sf_buf *sf);

---

🦋 DESCRIPTION 🦋

so the sf_buf interface — historically known as the sendfile(2) buffer interface, ikyk — lets kernel subsystems manage temporary kernel address space mappings for physical memory pages. literally its whole job 💅

here's the tea on how it works, depending on your system:

• on systems with a direct memory map region (meaning all physical pages are visible in the kernel address space at all times), the struct sf_buf will point to an address in the direct map region
• on systems without a direct memory map region, the struct sf_buf will manage a temporary kernel address space mapping that's valid for the lifetime of the struct sf_buf

periodt. moving on 🫶

---

✨ allocating: sf_buf_alloc() ✨

call sf_buf_alloc() to allocate a struct sf_buf for a physical memory page.

⚠️ heads up bestie: sf_buf_alloc() is not responsible for arranging for the page to be present in physical memory. the caller should already have arranged for the page to be wired, i.e., by calling vm_page_wire(9). no cap, that's on you.

several flags may be passed to sf_buf_alloc():

• SFB_CATCH — cause sf_buf_alloc() to abort and return NULL if a signal is received waiting for a struct sf_buf to become available.
• SFB_NOWAIT — cause sf_buf_alloc() to return NULL rather than sleeping if a struct sf_buf is not immediately available.
• SFB_CPUPRIVATE — cause sf_buf_alloc() to only arrange that the temporary mapping be valid on the current CPU, avoiding unnecessary TLB shootdowns for mappings that will only be accessed on a single CPU at a time. the caller must ensure that accesses to the virtual address occur only on the CPU from which sf_buf_alloc() was invoked, perhaps by using sched_pin(). 👑 (main character CPU energy, we love to see it)

---

💜 the getters 💜

• call sf_buf_kva() to return a kernel mapped address for the page. 📍
• call sf_buf_page() to return a pointer to the page originally passed into sf_buf_alloc(). 🎯

---

🌈 freeing: sf_buf_free() 🌈

call sf_buf_free() to release the struct sf_buf reference.

😭 bestie listen: the caller is responsible for releasing any wiring they have previously acquired on the physical page. sf_buf_free() releases only the temporary kernel address space mapping, not the page itself. don't get it twisted.

---

🧚 where you'll see this queen in the wild

uses of this interface include:

• managing mappings of borrowed pages from user memory, such as in zero-copy socket I/O 🔥
• pages of memory from the buffer cache referenced by mbuf external storage for sendfile(2) ⭐

it's giving foundational, honestly.

---

👑 SEE ALSO 👑

sendfile(2), vm_page_wire(9)

---

💖 AUTHORS 💖

the struct sf_buf API was designed and implemented by Alan L. Cox. this manual page was written by Robert N. M. Watson.

---

🌸 and that's the whole page, bestie! this one came from the Debian edition of the Kernel Developer's Manual, dated January 28, 2007, filed under SF_BUF(9). slay, read responsibly, and don't forget to free your buffers 💅✨🎀