share/man/man9/sf_buf.9

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