.\"	$NetBSD: ubc.9,v 1.15 2018/05/12 15:03:19 jdolecek Exp $
.\"
.\" Copyright (c) 1998 Matthew R. Green
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 12, 2018
.Dt UBC 9
.Os
.Sh NAME
.Nm ubc
.Nd unified buffer cache
.Sh SYNOPSIS
.In uvm/uvm.h
.Ft int
.Fn ubc_uiomove "struct uvm_object *uobj" "struct uio *uio" "vsize_t todo" \
 "int advice" "int flags"
.Ft void
.Fn ubc_zerorange "struct uvm_bject *uobj" "off_t off" "size_t len" \
 "int flags"
.Ft void
.Fn ubc_purge "struct uvm_object *uobj"
.Sh DESCRIPTION
.Fn ubc_uiomove
allocates an UBC memory window, performs I/O on it and unmaps the window.
The
.Fa advice
parameter is the access pattern hint, which must be one of
.Pp
.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact
.It UVM_ADV_NORMAL
No hint
.It UVM_ADV_RANDOM
Random access hint
.It UVM_ADV_SEQUENTIAL
Sequential access hint (from lower offset to higher offset)
.El
.Pp
and the
.Fa flags
parameter is
.Pp
.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact
.It UBC_READ
Mapping will be accessed for read.
.It UBC_WRITE
Mapping will be accessed for write.
.It UBC_FAULTBUSY
Fault in window's pages already during mapping operation.
Makes sense only for write.
.It UBC_UNMAP
Do not cache mapping.
.It UBC_PARTIALOK
Indicate that it is acceptable to return if an error occurs mid-transfer.
.El
.Pp
UBC memory window is a kernel mapping of
.Fa uobj
starting at offset
.Fa offset .
.Pp
Once the mapping is created, it must be accessed only by methods that can
handle faults, such as
.Xr uiomove 9
or
.Xr kcopy 9 .
Page faults on the mapping will result in the object's pager
method being called to resolve the fault.
.Pp
Size of individual UBC memory window is limited to
.Va ubc_winsize .
.Fn ubc_uiomove
sequentially creates the UBC memory windows to eventually process
the whole range according to
.Fa offset
and
.Fa len
parameters.
.Pp
The mappings may be cached to speed future accesses to the same region
of the object, unless
.Dv UBC_UNMAP
was specified in
.Fa flags
parameter.
.Pp
.Fn ubc_zerorange
sets a range of bytes in a UVM object to zero.
The
.Fa flags
parameter takes the same arguments as
.Fn ubc_uiomove .
.Pp
.Fn ubc_purge
disassociates all UBC structures from an empty UVM object,
specified by
.Fa uobj .
.Sh CODE REFERENCES
The
.Nm
subsystem is implemented within the file
.Pa sys/uvm/uvm_bio.c .
.Sh SEE ALSO
.Xr kcopy 9 ,
.Xr pmap 9 ,
.Xr uiomove 9 ,
.Xr uvm 9 ,
.Xr vnode 9 ,
.Xr vnodeops 9
.Rs
.%A Chuck Silvers
.%T "UBC: An Efficient Unified I/O and Memory Caching Subsystem for NetBSD"
.%I USENIX Association
.%B Proceedings of the FREENIX Track: 2000 USENIX Annual Technical Conference
.%P 285-290
.%D June 18-23, 2000
.%U http://www.usenix.org/event/usenix2000/freenix/full_papers/silvers/silvers.pdf
.Re
.Sh HISTORY
UBC first appeared in
.Nx 1.6 .
.Sh AUTHORS
.An Chuck Silvers
.Aq Mt chuq@chuq.com
designed and implemented the UBC part of UVM, which uses UVM pages
to cache vnode data rather than the traditional buffer cache buffers.