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