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.Dd January 28, 2007 32.Dt SF_BUF 9 33.Os 34.Sh NAME 35.Nm sf_buf 36.Nd manage temporary kernel address space mapping for memory pages 37.Sh SYNOPSIS 38.In sys/sf_buf.h 39.Ft struct sf_buf * 40.Fn sf_buf_alloc "struct vm_page *m" "int flags" 41.Ft void 42.Fn sf_buf_free "struct sf_buf *sf" 43.Ft vm_offset_t 44.Fn sf_buf_kva "struct sf_buf *sf" 45.Ft struct vm_page * 46.Fn sf_buf_page "struct sf_buf *sf" 47.Sh DESCRIPTION 48The 49.Nm 50interface, historically the 51.Xr sendfile 2 52buffer interface, allows kernel subsystems to manage temporary kernel address 53space mappings for physical memory pages. 54On systems with a direct memory map region (allowing all physical pages to be 55visible in the kernel address space at all times), the 56.Vt "struct sf_buf" 57will point to an address in the direct map region; on systems without a 58direct memory map region, the 59.Vt "struct sf_buf" 60will manage a temporary kernel address space mapping valid for the lifetime 61of the 62.Vt "struct sf_buf". 63.Pp 64Call 65.Fn sf_buf_alloc 66to allocate a 67.Vt "struct sf_buf" 68for a physical memory page. 69.Fn sf_buf_alloc 70is not responsible for arranging for the page to be present in physical 71memory; the caller should already have arranged for the page to be wired, 72i.e., by calling 73.Xr vm_page_wire 9 . 74Several flags may be passed to 75.Fn sf_buf_alloc : 76.Bl -tag -width SFB_CPUPRIVATE 77.It Dv SFB_CATCH 78Cause 79.Fn sf_buf_alloc 80to abort and return 81.Dv NULL 82if a signal is received waiting for a 83.Vt "struct sf_buf" 84to become available. 85.It Dv SFB_NOWAIT 86Cause 87.Fn sf_buf_alloc 88to return 89.Dv NULL 90rather than sleeping if a 91.Vt "struct sf_buf" 92is not immediately available. 93.It Dv SFB_CPUPRIVATE 94Cause 95.Fn sf_buf_alloc 96to only arrange that the temporary mapping be valid on the current CPU, 97avoiding unnecessary TLB shootdowns for mappings that will only be accessed 98on a single CPU at a time. 99The caller must ensure that accesses to the virtual address occur only on the 100CPU from which 101.Fn sf_buf_alloc 102was invoked, perhaps by using 103.Fn sched_pin . 104.El 105.Pp 106Call 107.Fn sf_buf_kva 108to return a kernel mapped address for the page. 109.Pp 110Call 111.Fn sf_buf_page 112to return a pointer to the page originally passed into 113.Fn sf_buf_alloc . 114.Pp 115Call 116.Fn sf_buf_free 117to release the 118.Vt "struct sf_buf" 119reference. 120The caller is responsible for releasing any wiring they have previously 121acquired on the physical page; 122.Fn sf_buf_free 123releases only the temporary kernel address space mapping, not the page 124itself. 125.Pp 126Uses of this interface include managing mappings of borrowed pages from user 127memory, such as in zero-copy socket I/O, or pages of memory from the buffer 128cache referenced by mbuf external storage for 129.Xr sendfile 2 . 130.Sh SEE ALSO 131.Xr sendfile 2 , 132.Xr vm_page_wire 9 133.Sh AUTHORS 134.An -nosplit 135The 136.Vt "struct sf_buf" 137API was designed and implemented by 138.An Alan L. Cox . 139This manual page was written by 140.An Robert N. M. Watson . 141