1.\" 2.\" Copyright (c) 2007 Seccuris Inc. 3.\" All rights reserved. 4.\" 5.\" This documentation was written by Robert N. M. Watson under contract to 6.\" Seccuris Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice(s), this list of conditions and the following disclaimer as 13.\" the first lines of this file unmodified other than the possible 14.\" addition of one or more copyright notices. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice(s), this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 20.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 23.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 29.\" DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd January 28, 2007 34.Dt SF_BUF 9 35.Os 36.Sh NAME 37.Nm sf_buf 38.Nd manage temporary kernel address space mapping for memory pages 39.Sh SYNOPSIS 40.In sys/sf_buf.h 41.Ft struct sf_buf * 42.Fn sf_buf_alloc "struct vm_page *m" "int flags" 43.Ft void 44.Fn sf_buf_free "struct sf_buf *sf" 45.Ft vm_offset_t 46.Fn sf_buf_kva "struct sf_buf *sf" 47.Ft struct vm_page * 48.Fn sf_buf_page "struct sf_buf *sf" 49.Sh DESCRIPTION 50The 51.Nm 52interface, historically the 53.Xr sendfile 2 54buffer interface, allows kernel subsystems to manage temporary kernel address 55space mappings for physical memory pages. 56On systems with a direct memory map region (allowing all physical pages to be 57visible in the kernel address space at all times), the 58.Vt "struct sf_buf" 59will point to an address in the direct map region; on systems without a 60direct memory map region, the 61.Vt "struct sf_buf" 62will manage a temporary kernel address space mapping valid for the lifetime 63of the 64.Vt "struct sf_buf". 65.Pp 66Call 67.Fn sf_buf_alloc 68to allocate a 69.Vt "struct sf_buf" 70for a physical memory page. 71.Fn sf_buf_alloc 72is not responsible for arranging for the page to be present in physical 73memory; the caller should already have arranged for the page to be wired, 74i.e., by calling 75.Xr vm_page_wire 9 . 76Several flags may be passed to 77.Fn sf_buf_alloc : 78.Bl -tag -width SFB_CPUPRIVATE 79.It Dv SFB_CATCH 80Cause 81.Fn sf_buf_alloc 82to abort and return 83.Dv NULL 84if a signal is received waiting for a 85.Vt "struct sf_buf" 86to become available. 87.It Dv SFB_NOWAIT 88Cause 89.Fn sf_buf_alloc 90to return 91.Dv NULL 92rather than sleeping if a 93.Vt "struct sf_buf" 94is not immediately available. 95.It Dv SFB_CPUPRIVATE 96Cause 97.Fn sf_buf_alloc 98to only arrange that the temporary mapping be valid on the current CPU, 99avoiding unnecessary TLB shootdowns for mappings that will only be accessed 100on a single CPU at a time. 101The caller must ensure that accesses to the virtual address occur only on the 102CPU from which 103.Fn sf_buf_alloc 104was invoked, perhaps by using 105.Fn sched_pin . 106.El 107.Pp 108Call 109.Fn sf_buf_kva 110to return a kernel mapped address for the page. 111.Pp 112Call 113.Fn sf_buf_page 114to return a pointer to the page originally passed into 115.Fn sf_buf_alloc . 116.Pp 117Call 118.Fn sf_buf_free 119to release the 120.Vt "struct sf_buf" 121reference. 122The caller is responsible for releasing any wiring they have previously 123acquired on the physical page; 124.Fn sf_buf_free 125releases only the temporary kernel address space mapping, not the page 126itself. 127.Pp 128Uses of this interface include managing mappings of borrowed pages from user 129memory, such as in zero-copy socket I/O, or pages of memory from the buffer 130cache referenced by mbuf external storage for 131.Xr sendfile 2 . 132.Sh SEE ALSO 133.Xr sendfile 2 , 134.Xr vm_page_wire 9 135.Sh AUTHORS 136.An -nosplit 137The 138.Vt "struct sf_buf" 139API was designed and implemented by 140.An Alan L. Cox . 141This manual page was written by 142.An Robert N. M. Watson . 143