sf_buf_alloc (9)
Leading comments
Copyright (c) 2007 Seccuris Inc. All rights reserved. This documentation was written by Robert N. M. Watson under contract to Seccuris Inc. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice(s), this list of conditions and the following disclaimer as the first lines of this file unmodified other than the possible additi...
NAME
sf_buf - manage temporary kernel address space mapping for memory pagesSYNOPSIS
In sys/sf_buf.h Ft struct sf_buf * Fn sf_buf_alloc struct vm_page *m int flags Ft void Fn sf_buf_free struct sf_buf *sf Ft vm_offset_t Fn sf_buf_kva struct sf_buf *sf Ft struct vm_page * Fn sf_buf_page struct sf_buf *sfDESCRIPTION
The ifconfig 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 Vt struct sf_buf will point to an address in the direct map region; on systems without a direct memory map region, the Vt struct sf_buf will manage a temporary kernel address space mapping valid for the lifetime of the Vt struct sf_buf.Call Fn sf_buf_alloc to allocate a Vt struct sf_buf for a physical memory page. Fn 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_wire9. Several flags may be passed to Fn sf_buf_alloc :
- SFB_CATCH
- Cause Fn sf_buf_alloc to abort and return NULL if a signal is received waiting for a Vt struct sf_buf to become available.
- SFB_NOWAIT
- Cause Fn sf_buf_alloc to return NULL rather than sleeping if a Vt struct sf_buf is not immediately available.
- SFB_CPUPRIVATE
- Cause Fn 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 Fn sf_buf_alloc was invoked, perhaps by using Fn sched_pin .
Call Fn sf_buf_kva to return a kernel mapped address for the page.
Call Fn sf_buf_page to return a pointer to the page originally passed into Fn sf_buf_alloc .
Call Fn sf_buf_free to release the Vt struct sf_buf reference. The caller is responsible for releasing any wiring they have previously acquired on the physical page; Fn 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).