share/man/man9/ubc.9

   1 .\"     $NetBSD: ubc.9,v 1.2 2009/08/03 19:18:27 rmind Exp $
   2 .\"
   3 .\" Copyright (c) 1998 Matthew R. Green
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  20 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  21 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  22 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  23 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .Dd August 3, 2009
  28 .Dt UBC 9
  29 .Os
  30 .Sh NAME
  31 .Nm ubc
  32 .Nd unified buffer cache
  33 .Sh SYNOPSIS
  34 .In uvm/uvm.h
  35 .Ft void *
  36 .Fn ubc_alloc "struct uvm_object *uobj" "voff_t offset" "vsize_t *lenp" \
  37 "int advice" "int flags"
  38 .Ft void
  39 .Fn ubc_release "void *va" "int flags"
  40 .Ft int
  41 .Fn ubc_uiomove "struct uvm_object *uobj" "struct uio *uio" "vsize_t todo" "int advice" "int flags"
  42 .Sh DESCRIPTION
  43 .Fn ubc_alloc
  44 creates a kernel mapping of
  45 .Fa uobj
  46 starting at offset
  47 .Fa offset .
  48 The desired length of the mapping is pointed to by
  49 .Fa lenp ,
  50 but the actual mapping may be smaller than this.
  51 .Fa lenp
  52 is updated to contain the actual length mapped.
  53 .Fa advice
  54 is the access pattern hint, which must be one of
  55 .Pp
  56 .Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact
  57 .It UVM_ADV_NORMAL
  58 No hint
  59 .It UVM_ADV_RANDOM
  60 Random access hint
  61 .It UVM_ADV_SEQUENTIAL
  62 Sequential access hint (from lower offset to higher offset)
  63 .El
  64 .Pp
  65 The possible
  66 .Fa flags
  67 are
  68 .Pp
  69 .Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact
  70 .It UBC_READ
  71 Mapping will be accessed for read.
  72 .It UBC_WRITE
  73 Mapping will be accessed for write.
  74 .It UBC_FAULTBUSY
  75 Fault in window's pages already during mapping operation.
  76 Makes sense only for write.
  77 .El
  78 .Pp
  79 Once the mapping is created, it must be accessed only by methods that can
  80 handle faults, such as
  81 .Fn uiomove
  82 or
  83 .Fn kcopy .
  84 Page faults on the mapping will result in the object's pager
  85 method being called to resolve the fault.
  86 .Pp
  87 .Fn ubc_release
  88 frees the mapping at
  89 .Fa va
  90 for reuse.
  91 The mapping may be cached to speed future accesses to the same region
  92 of the object.
  93 The flags can be any of
  94 .Pp
  95 .Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact
  96 .It UBC_UNMAP
  97 Do not cache mapping.
  98 .El
  99 .Pp
 100 .Fn ubc_uiomove
 101 allocates an UBC memory window, performs I/O on it and unmaps the window.
 102 The
 103 .Fa advice
 104 parameter takes the same values as the respective parameter in
 105 .Fn ubc_alloc
 106 and the
 107 .Fa flags
 108 parameter takes the same arguments as
 109 .Fn ubc_alloc
 110 and
 111 .Fn ubc_release .
 112 Additionally, the flag
 113 .Dv UBC_PARTIALOK
 114 can be provided to indicate that it is acceptable to return if an error
 115 occurs mid-transfer.
 116 .Sh CODE REFERENCES
 117 This section describes places within the
 118 .Nx
 119 source tree where actual code implementing the
 120 .Nm
 121 subsystem
 122 can be found.
 123 All pathnames are relative to
 124 .Pa /usr/src .
 125 .Pp
 126 The
 127 .Nm
 128 subsystem is implemented within the file
 129 .Pa sys/uvm/uvm_bio.c .
 130 .Sh SEE ALSO
 131 .Xr pmap 9 ,
 132 .Xr uiomove 9 ,
 133 .Xr uvm 9 ,
 134 .Xr vnode 9 ,
 135 .Xr vnodeops 9
 136 .Sh HISTORY
 137 UBC first appeared in
 138 .Nx 1.6 .
 139 .Sh AUTHORS
 140 Chuck Silvers
 141 .Aq chuq@chuq.com
 142 designed and implemented the UBC part of UVM, which uses UVM pages
 143 to cache vnode data rather than the traditional buffer cache buffers.