147 lines
4.2 KiB
Groff
147 lines
4.2 KiB
Groff
.\" $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.
|