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