1.\" $NetBSD: ubc.9,v 1.3 2009/09/28 14:11:56 joerg 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 44creates a kernel mapping of 45.Fa uobj 46starting at offset 47.Fa offset . 48The desired length of the mapping is pointed to by 49.Fa lenp , 50but the actual mapping may be smaller than this. 51.Fa lenp 52is updated to contain the actual length mapped. 53.Fa advice 54is 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 58No hint 59.It UVM_ADV_RANDOM 60Random access hint 61.It UVM_ADV_SEQUENTIAL 62Sequential access hint (from lower offset to higher offset) 63.El 64.Pp 65The possible 66.Fa flags 67are 68.Pp 69.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact 70.It UBC_READ 71Mapping will be accessed for read. 72.It UBC_WRITE 73Mapping will be accessed for write. 74.It UBC_FAULTBUSY 75Fault in window's pages already during mapping operation. 76Makes sense only for write. 77.El 78.Pp 79Once the mapping is created, it must be accessed only by methods that can 80handle faults, such as 81.Fn uiomove 82or 83.Fn kcopy . 84Page faults on the mapping will result in the object's pager 85method being called to resolve the fault. 86.Pp 87.Fn ubc_release 88frees the mapping at 89.Fa va 90for reuse. 91The mapping may be cached to speed future accesses to the same region 92of the object. 93The flags can be any of 94.Pp 95.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact 96.It UBC_UNMAP 97Do not cache mapping. 98.El 99.Pp 100.Fn ubc_uiomove 101allocates an UBC memory window, performs I/O on it and unmaps the window. 102The 103.Fa advice 104parameter takes the same values as the respective parameter in 105.Fn ubc_alloc 106and the 107.Fa flags 108parameter takes the same arguments as 109.Fn ubc_alloc 110and 111.Fn ubc_release . 112Additionally, the flag 113.Dv UBC_PARTIALOK 114can be provided to indicate that it is acceptable to return if an error 115occurs mid-transfer. 116.Sh CODE REFERENCES 117This section describes places within the 118.Nx 119source tree where actual code implementing the 120.Nm 121subsystem 122can be found. 123All pathnames are relative to 124.Pa /usr/src . 125.Pp 126The 127.Nm 128subsystem 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 137UBC first appeared in 138.Nx 1.6 . 139.Sh AUTHORS 140Chuck Silvers 141.Aq chuq@chuq.com 142designed and implemented the UBC part of UVM, which uses UVM pages 143to cache vnode data rather than the traditional buffer cache buffers. 144