1.\" $NetBSD: ubc.9,v 1.7 2011/06/14 00:19:20 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 June 14, 2011 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" \ 42 "int advice" "int flags" 43.Ft void 44.Fn ubc_purge "struct uvm_object *uobj" 45.Sh DESCRIPTION 46.Fn ubc_alloc 47creates a kernel mapping of 48.Fa uobj 49starting at offset 50.Fa offset . 51The desired length of the mapping is pointed to by 52.Fa lenp , 53but the actual mapping may be smaller than this. 54.Fa lenp 55is updated to contain the actual length mapped. 56.Fa advice 57is the access pattern hint, which must be one of 58.Pp 59.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact 60.It UVM_ADV_NORMAL 61No hint 62.It UVM_ADV_RANDOM 63Random access hint 64.It UVM_ADV_SEQUENTIAL 65Sequential access hint (from lower offset to higher offset) 66.El 67.Pp 68The possible 69.Fa flags 70are 71.Pp 72.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact 73.It UBC_READ 74Mapping will be accessed for read. 75.It UBC_WRITE 76Mapping will be accessed for write. 77.It UBC_FAULTBUSY 78Fault in window's pages already during mapping operation. 79Makes sense only for write. 80.El 81.Pp 82Once the mapping is created, it must be accessed only by methods that can 83handle faults, such as 84.Fn uiomove 85or 86.Fn kcopy . 87Page faults on the mapping will result in the object's pager 88method being called to resolve the fault. 89.Pp 90.Fn ubc_release 91frees the mapping at 92.Fa va 93for reuse. 94The mapping may be cached to speed future accesses to the same region 95of the object. 96The flags can be any of 97.Pp 98.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact 99.It UBC_UNMAP 100Do not cache mapping. 101.El 102.Pp 103.Fn ubc_uiomove 104allocates an UBC memory window, performs I/O on it and unmaps the window. 105The 106.Fa advice 107parameter takes the same values as the respective parameter in 108.Fn ubc_alloc 109and the 110.Fa flags 111parameter takes the same arguments as 112.Fn ubc_alloc 113and 114.Fn ubc_release . 115Additionally, the flag 116.Dv UBC_PARTIALOK 117can be provided to indicate that it is acceptable to return if an error 118occurs mid-transfer. 119.Pp 120.Fn ubc_purge 121disassociates all UBC structures from an empty UVM object, 122specified by 123.Fa uobj . 124.Sh CODE REFERENCES 125The 126.Nm 127subsystem is implemented within the file 128.Pa sys/uvm/uvm_bio.c . 129.Sh SEE ALSO 130.Xr pmap 9 , 131.Xr uiomove 9 , 132.Xr uvm 9 , 133.Xr vnode 9 , 134.Xr vnodeops 9 135.Rs 136.%A Chuck Silvers 137.%T "UBC: An Efficient Unified I/O and Memory Caching Subsystem for NetBSD" 138.%I USENIX Association 139.%B Proceedings of the FREENIX Track: 2000 USENIX Annual Technical Conference 140.%P 285-290 141.%D June 18-23, 2000 142.%U http://www.usenix.org/event/usenix2000/freenix/full_papers/silvers/silvers.pdf 143.Re 144.Sh HISTORY 145UBC first appeared in 146.Nx 1.6 . 147.Sh AUTHORS 148Chuck Silvers 149.Aq chuq@chuq.com 150designed and implemented the UBC part of UVM, which uses UVM pages 151to cache vnode data rather than the traditional buffer cache buffers. 152