Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Split descriptions of UBC functions from uvm(9) into separate ubc(9) man page.

This commit is contained in:
rmind 2009-08-03 19:08:48 +00:00
parent a8420debfe
commit e403bed420
4 changed files with 147 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
distrib/sets/lists/comp/mi
View File

@ -1,4 +1,4 @@
# $NetBSD: mi,v 1.1288 2009/08/03 15:59:41 plunky Exp $
# $NetBSD: mi,v 1.1289 2009/08/03 19:08:48 rmind Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@ -9161,6 +9161,7 @@
./usr/share/man/cat9/uao_create.0 comp-sys-catman .cat
./usr/share/man/cat9/uao_detach.0 comp-sys-catman .cat
./usr/share/man/cat9/uao_reference.0 comp-sys-catman .cat
./usr/share/man/cat9/ubc.0 comp-sys-catman .cat
./usr/share/man/cat9/ubc_alloc.0 comp-sys-catman .cat
./usr/share/man/cat9/ubc_release.0 comp-sys-catman .cat
./usr/share/man/cat9/ubc_uiomove.0 comp-sys-catman .cat
@ -14525,6 +14526,7 @@
./usr/share/man/html9/uao_create.html comp-sys-htmlman html
./usr/share/man/html9/uao_detach.html comp-sys-htmlman html
./usr/share/man/html9/uao_reference.html comp-sys-htmlman html
./usr/share/man/html9/ubc.html comp-sys-htmlman html
./usr/share/man/html9/ubc_alloc.html comp-sys-htmlman html
./usr/share/man/html9/ubc_release.html comp-sys-htmlman html
./usr/share/man/html9/ubc_uiomove.html comp-sys-htmlman html
@ -20104,6 +20106,7 @@
./usr/share/man/man9/uao_create.9 comp-sys-man .man
./usr/share/man/man9/uao_detach.9 comp-sys-man .man
./usr/share/man/man9/uao_reference.9 comp-sys-man .man
./usr/share/man/man9/ubc.9 comp-sys-man .man
./usr/share/man/man9/ubc_alloc.9 comp-sys-man .man
./usr/share/man/man9/ubc_release.9 comp-sys-man .man
./usr/share/man/man9/ubc_uiomove.9 comp-sys-man .man

8
share/man/man9/Makefile
View File

@ -1,4 +1,4 @@
# $NetBSD: Makefile,v 1.283 2009/06/06 18:48:10 hubertf Exp $
# $NetBSD: Makefile,v 1.284 2009/08/03 19:08:48 rmind Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@ -54,7 +54,7 @@ MAN= accept_filter.9 accf_data.9 accf_http.9 \
vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
video.9 vme.9 \
vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
usbdi.9 uvm.9 \
ubc.9 usbdi.9 uvm.9 \
vmem.9 vmem_alloc.9 vmem_create.9 vmem_destroy.9 vmem_free.9 \
vmem_xalloc.9 vmem_xfree.9 \
wdc.9 \
@ -648,6 +648,7 @@ MLINKS+=tc.9 tc_intr_establish.9 \
tc.9 TC_PHYS_TO_UNCACHED.9
MLINKS+=todr.9 todr_gettime.9 todr.9 todr_settime.9 \
todr.9 clock_ymdhms_to_secs.9 todr.9 clock_secs_to_ymdhms.9
MLINKS+=ubc.9 ubc_alloc.9 uvm.9 ubc_release.9 uvm.9 ubc_uiomove.9
MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \
uvm.9 uvm_swap_init.9 uvm.9 uvm_map.9 uvm.9 uvm_unmap.9 \
uvm.9 uvm_map_pageable.9 \
@ -666,9 +667,6 @@ MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \
uvm.9 uvm_kernacc.9 uvm.9 uvm_vslock.9 \
uvm.9 uvm_vsunlock.9 uvm.9 uvm_meter.9 \
uvm.9 uvm_fork.9 uvm.9 uvm_grow.9 \
uvm.9 ubc_alloc.9 \
uvm.9 ubc_release.9 \
uvm.9 ubc_uiomove.9 \
uvm.9 uvn_findpages.9 \
uvm.9 uvm_loan.9 uvm.9 uvm_unloan.9
MLINKS+=vme.9 vme_probe.9 \

126
share/man/man9/ubc.9 Normal file
View File

@ -0,0 +1,126 @@
.\" $NetBSD: ubc.9,v 1.1 2009/08/03 19:08:48 rmind 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 August 3, 2009
.Dt UBC 9
.Os
.Sh NAME
.Nm ubc
.Nd unified buffer cache
.Sh SYNOPSIS
.In uvm/uvm.h
.Bl -ohang
.It Ft void *
.Fn ubc_alloc "struct uvm_object *uobj" "voff_t offset" "vsize_t *lenp" \
"int advice" "int flags"
.It Ft void
.Fn ubc_release "void *va" "int flags"
.It Ft int
.Fn ubc_uiomove "struct uvm_object *uobj" "struct uio *uio" "vsize_t todo" \
"int advice" "int flags"
.El
.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
.Fn uiomove
or
.Fn kcopy .
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_unmap .
Additionally, the flag
.Dv UBC_PARTIALOK
can be provided to indicate that it is acceptable to return if an error
occurs mid-transfer.
.Sh HISTORY
UBC first appeared in
.Nx 1.6 .
.Sh AUTHORS
Chuck Silvers
.Aq 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.

114
share/man/man9/uvm.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: uvm.9,v 1.97 2009/03/12 13:13:16 wiz Exp $
.\" $NetBSD: uvm.9,v 1.98 2009/08/03 19:08:48 rmind Exp $
.\"
.\" Copyright (c) 1998 Matthew R. Green
.\" All rights reserved.
@ -24,7 +24,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd March 12, 2009
.Dd August 3, 2009
.Dt UVM 9
.Os
.Sh NAME
@ -401,101 +401,6 @@ offset into the map the fault occurred, and
describing the type of access requested.
.Fn uvm_fault
returns a standard UVM return value.
.Sh MEMORY MAPPING FILES AND DEVICES
.Bl -ohang
.It Ft void
.Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" ;
.It Ft void *
.Fn ubc_alloc "struct uvm_object *uobj" "voff_t offset" "vsize_t *lenp" \
"int advice" "int flags" ;
.It Ft void
.Fn ubc_release "void *va" "int flags" ;
.It Ft int
.Fn ubc_uiomove "struct uvm_object *uobj" "struct uio *uio" "vsize_t todo" \
"int advice" "int flags" ;
.El
.Pp
.Fn uvm_vnp_setsize
sets the size of vnode
.Fa vp
to
.Fa newsize .
Caller must hold a reference to the vnode.
If the vnode shrinks, pages no longer used are discarded.
.Pp
.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
.Fn uiomove
or
.Fn kcopy .
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_unmap .
Additionally, the flag
.Dv UBC_PARTIALOK
can be provided to indicate that it is acceptable to return if an error
occurs mid-transfer.
.Sh VIRTUAL MEMORY I/O
.Bl -ohang
.It Ft int
@ -871,6 +776,8 @@ and should match what was used for previous call to
.It Ft void
.Fn uvn_findpages "struct uvm_object *uobj" "voff_t offset" "int *npagesp" "struct vm_page **pps" "int flags" ;
.It Ft void
.Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" ;
.It Ft void
.Fn uvm_swap_stats "int cmd" "struct swapent *sep" "int sec" "register_t *retval" ;
.El
.Pp
@ -984,6 +891,14 @@ causes any pages which do already exist to be skipped.
.Dv UFP_NORDONLY
causes any pages which are marked PG_READONLY to be skipped.
.Pp
.Fn uvm_vnp_setsize
sets the size of vnode
.Fa vp
to
.Fa newsize .
Caller must hold a reference to the vnode.
If the vnode shrinks, pages no longer used are discarded.
.Pp
.Fn uvm_swap_stats
implements the
.Dv SWAP_STATS
@ -1124,7 +1039,8 @@ will be renamed to
.Xr ddb 4 ,
.Xr options 4 ,
.Xr memoryallocators 9 ,
.Xr pmap 9
.Xr pmap 9 ,
.Xr ubc 9
.Sh HISTORY
UVM is a new VM system developed at Washington University in St. Louis
(Missouri).
@ -1164,5 +1080,3 @@ Chuck Silvers
.Aq chuq@chuq.com
implemented the aobj pager, thus allowing UVM to support System V shared
memory and process swapping.
He also designed and implemented the UBC part of UVM, which uses UVM pages
to cache vnode data rather than the traditional buffer cache buffers.