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