.\"	$NetBSD: ubc.9,v 1.13 2017/04/06 09:52:32 abhinav 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 April 6, 2017
.Dt UBC 9
.Os
.Sh NAME
.Nm ubc
.Nd unified buffer cache
.Sh SYNOPSIS
.In uvm/uvm.h
.Ft void *
.Fn ubc_alloc "struct uvm_object *uobj" "voff_t offset" "vsize_t *lenp" \
"int advice" "int flags"
.Ft void
.Fn ubc_release "void *va" "int flags"
.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_alloc
creates a kernel mapping of
.Fa uobj
starting at offset
.Fa offset .
The desired length of the mapping is pointed to by
.Fa lenp ,
but the actual mapping may be smaller than this.
.Fa lenp
is updated to contain the actual length mapped.
.Fa advice
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
The possible
.Fa flags
are
.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.
.El
.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
.Fn ubc_release
frees the mapping at
.Fa va
for reuse.
The mapping may be cached to speed future accesses to the same region
of the object.
The flags can be any of
.Pp
.Bl -tag -offset indent -width "UVM_ADV_SEQUENTIAL" -compact
.It UBC_UNMAP
Do not cache mapping.
.El
.Pp
.Fn ubc_uiomove
allocates an UBC memory window, performs I/O on it and unmaps the window.
The
.Fa advice
parameter takes the same values as the respective parameter in
.Fn ubc_alloc
and the
.Fa flags
parameter takes the same arguments as
.Fn ubc_alloc
and
.Fn ubc_release .
Additionally, the flag
.Dv UBC_PARTIALOK
can be provided to indicate that it is acceptable to return if an error
occurs mid-transfer.
.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_release .
.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.