SYNOPSIS

DESCRIPTION

The sf_buf interface, historically the sendfile(2) buffer interface,
allows kernel subsystems to manage temporary kernel address space
mappings for physical memory pages. On systems with a direct memory map
region (allowing all physical pages to be visible in the kernel address
space at all times), the structsf_buf will point to an address in the
direct map region; on systems without a direct memory map region, the
structsf_buf will manage a temporary kernel address space mapping valid
for the lifetime of the structsf_buf.
Call sf_buf_alloc() to allocate a structsf_buf for a physical memory
page. 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). 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 structsf_buf to become
available.
SFB_NOWAIT Cause sf_buf_alloc() to return NULL rather than sleeping
if a structsf_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().
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().
Call sf_buf_free() to release the structsf_buf reference. 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.
Uses of this interface include managing mappings of borrowed pages from
user memory, such as in zero-copy socket I/O, or pages of memory from the
buffer cache referenced by mbuf external storage for sendfile(2).