a man page for buffer cache interfaces.
(an incomplete page is better than no page)
This commit is contained in:
yamt
parent
5a759ef06c
commit
ad7083055f
@ -1,10 +1,10 @@
|
||||
# $NetBSD: Makefile,v 1.142 2003/04/07 07:09:47 gmcgarry Exp $
|
||||
# $NetBSD: Makefile,v 1.143 2003/09/06 18:12:39 yamt Exp $
|
||||
|
||||
# Makefile for section 9 (kernel function and variable) manual pages.
|
||||
|
||||
MAN= altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \
|
||||
bitmask_snprintf.9 bcmp.9 bcopy.9 bzero.9 \
|
||||
bufq.9 bus_dma.9 bus_space.9 \
|
||||
buffercache.9 bufq.9 bus_dma.9 bus_space.9 \
|
||||
callout.9 cardbus.9 chooseproc.9 cnmagic.9 config.9 cons.9 copy.9 \
|
||||
cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 cpu_exit.9 cpu_idle.9 \
|
||||
cpu_fork.9 \
|
||||
@ -57,6 +57,19 @@ MLINKS+=autoconf.9 config_search.9 \
|
||||
autoconf.9 config_interrupts.9 \
|
||||
autoconf.9 config_pending_incr.9 \
|
||||
autoconf.9 config_pending_decr.9
|
||||
MLINKS+=buffercache.9 bread.9 \
|
||||
buffercache.9 breada.9 \
|
||||
buffercache.9 breadn.9 \
|
||||
buffercache.9 bwrite.9 \
|
||||
buffercache.9 bawrite.9 \
|
||||
buffercache.9 bdwrite.9 \
|
||||
buffercache.9 getblk.9 \
|
||||
buffercache.9 geteblk.9 \
|
||||
buffercache.9 incore.9 \
|
||||
buffercache.9 allocbuf.9 \
|
||||
buffercache.9 brelse.9 \
|
||||
buffercache.9 biodone.9 \
|
||||
buffercache.9 biowait.9
|
||||
MLINKS+=bus_space.9 bus_space_alloc.9 bus_space.9 bus_space_barrier.9 \
|
||||
bus_space.9 bus_space_copy_region_1.9 \
|
||||
bus_space.9 bus_space_copy_region_2.9 \
|
||||
|
||||
322
share/man/man9/buffercache.9
Normal file
322
share/man/man9/buffercache.9
Normal file
@ -0,0 +1,322 @@
|
||||
.\" $NetBSD: buffercache.9,v 1.1 2003/09/06 18:12:39 yamt Exp $
|
||||
.\"
|
||||
.\" Copyright (c)2003 YAMAMOTO Takashi,
|
||||
.\" 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 AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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.
|
||||
.\"
|
||||
.\"
|
||||
.\" following copyright notices are from sys/kern/vfs_bio.c.
|
||||
.\" they are here because i took some comments from it. yamt@netbsd.org
|
||||
.\"
|
||||
.\"
|
||||
.\"/*-
|
||||
.\" * Copyright (c) 1982, 1986, 1989, 1993
|
||||
.\" * The Regents of the University of California. All rights reserved.
|
||||
.\" * (c) UNIX System Laboratories, Inc.
|
||||
.\" * All or some portions of this file are derived from material licensed
|
||||
.\" * to the University of California by American Telephone and Telegraph
|
||||
.\" * Co. or Unix System Laboratories, Inc. and are reproduced herein with
|
||||
.\" * the permission of UNIX System Laboratories, Inc.
|
||||
.\" *
|
||||
.\" * 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.
|
||||
.\" * 3. Neither the name of the University nor the names of its contributors
|
||||
.\" * may be used to endorse or promote products derived from this software
|
||||
.\" * without specific prior written permission.
|
||||
.\" *
|
||||
.\" * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\" *
|
||||
.\" * @(#)vfs_bio.c 8.6 (Berkeley) 1/11/94
|
||||
.\" */
|
||||
.\"
|
||||
.\"/*-
|
||||
.\" * Copyright (c) 1994 Christopher G. Demetriou
|
||||
.\" *
|
||||
.\" * 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.
|
||||
.\" * 3. All advertising materials mentioning features or use of this software
|
||||
.\" * must display the following acknowledgement:
|
||||
.\" * This product includes software developed by the University of
|
||||
.\" * California, Berkeley and its contributors.
|
||||
.\" * 4. Neither the name of the University nor the names of its contributors
|
||||
.\" * may be used to endorse or promote products derived from this software
|
||||
.\" * without specific prior written permission.
|
||||
.\" *
|
||||
.\" * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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.
|
||||
.\" *
|
||||
.\" * @(#)vfs_bio.c 8.6 (Berkeley) 1/11/94
|
||||
.\" */
|
||||
.\"
|
||||
.\"
|
||||
.\" ------------------------------------------------------------
|
||||
.Dd September 7, 2003
|
||||
.Dt BUFFERCACHE 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm buffercache ,
|
||||
.Nm bread ,
|
||||
.Nm breada ,
|
||||
.Nm breadn ,
|
||||
.Nm bwrite ,
|
||||
.Nm bawrite ,
|
||||
.Nm bdwrite ,
|
||||
.Nm getblk ,
|
||||
.Nm geteblk ,
|
||||
.Nm incore ,
|
||||
.Nm allocbuf ,
|
||||
.Nm brelse ,
|
||||
.Nm biodone ,
|
||||
.Nm biowait
|
||||
.Nd buffer cache interfaces
|
||||
.\" ------------------------------------------------------------
|
||||
.Sh SYNOPSIS
|
||||
.In sys/buf.h
|
||||
.Ft void
|
||||
.Fn bread "struct vnode *vp" "daddr_t blkno" "int size" \
|
||||
"struct ucred *cred" "struct buf **bpp"
|
||||
.Ft int
|
||||
.Fn breadn "struct vnode *vp" "daddr_t blkno" "int size" \
|
||||
"daddr_t rablks[]" "int rasizes[]" "int nrablks" \
|
||||
"struct ucred *cred" "struct buf **bpp"
|
||||
.Ft int
|
||||
.Fn breada "struct vnode *vp" "daddr_t blkno" "int size" \
|
||||
"daddr_t rablkno" "int rabsize" \
|
||||
"struct ucred *cred" "struct buf **bpp"
|
||||
.Ft int
|
||||
.Fn bwrite "struct buf *bp"
|
||||
.Ft void
|
||||
.Fn bawrite "struct buf *bp"
|
||||
.Ft void
|
||||
.Fn bdwrite "struct buf *bp"
|
||||
.Ft struct buf *
|
||||
.Fn getblk "struct vnode *vp" "daddr_t blkno" "int size" \
|
||||
"int slpflag" "int slptimeo"
|
||||
.Ft struct buf *
|
||||
.Fn geteblk "int size"
|
||||
.Ft struct buf *
|
||||
.Fn incore "struct vnode *vp" "daddr_t blkno"
|
||||
.Ft void
|
||||
.Fn allocbuf "struct buf *bp" "int size"
|
||||
.Ft void
|
||||
.Fn brelse "struct buf *bp"
|
||||
.Ft void
|
||||
.Fn biodone "struct buf *bp"
|
||||
.Ft int
|
||||
.Fn biowait "struct buf *bp"
|
||||
.\" ------------------------------------------------------------
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
interface is used by each filesystems to improve I/O performance using
|
||||
in-core caches of filesystem blocks.
|
||||
.\" XXX struct buf, B_ flags, MP locks, etc
|
||||
.\" ------------------------------------------------------------
|
||||
.Sh FUNCTIONS
|
||||
.Bl -tag -width compact
|
||||
.It Fn bread "vp" "blkno" "size" "cred" "bpp"
|
||||
Read a block corresponding to
|
||||
.Fa vp
|
||||
and
|
||||
.Fa blkno .
|
||||
the buffer is returned via
|
||||
.Fa bpp .
|
||||
.Pp
|
||||
If the buffer is not found (i.e. the block is not cached in memory),
|
||||
.Fn bread
|
||||
allocates a buffer with enough pages for
|
||||
.Fa size
|
||||
and read the specified disk block into it using
|
||||
credential
|
||||
.Fa cred .
|
||||
.Pp
|
||||
The buffer returned by
|
||||
.Fn bread
|
||||
is marked as busy.
|
||||
(B_BUSY flag is set.)
|
||||
After manipulation of the buffer returned from
|
||||
.Fn bread ,
|
||||
the caller should unbusy it so that another thread can get it.
|
||||
If the buffer contents are modified and should be written back to disk,
|
||||
it should be unbusied using one of variants of
|
||||
.Fn bwrite .
|
||||
Otherwise, it should be unbusied using
|
||||
.Fn brelse .
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn breadn "vp" "blkno" "size" "rablks" "rasizes" "nrablks" "cred" "bpp"
|
||||
Get a buffer as
|
||||
.Fn bread .
|
||||
In addition,
|
||||
.Fn breadn
|
||||
will start read-ahead of blocks specified by
|
||||
.Fn rablk ,
|
||||
.Fn rasizes ,
|
||||
.Fn nrablks .
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn breada "vp" "blkno" "size" "rablkno" "rabsize" "cred" "bpp"
|
||||
Same as
|
||||
.Fn breadn
|
||||
with single block read-ahead.
|
||||
This function is for compatibility with old filesystem code and
|
||||
shouldn't be used by new ones.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn bwrite "bp"
|
||||
Write a block.
|
||||
Start I/O for write using
|
||||
.Fn VOP_STRATEGY .
|
||||
Then, unless B_ASYNC flag is set in
|
||||
.Fa bp ,
|
||||
.Fn bwrite
|
||||
waits for the I/O to complete.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn bawrite "bp"
|
||||
Write a block asynchronously.
|
||||
Set B_ASYNC flags in
|
||||
.Fa bp
|
||||
and simply call
|
||||
.Fa VOP_BWRITE ,
|
||||
which results in
|
||||
.Fa bwrite
|
||||
for most filesystems.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn bdwrite "bp"
|
||||
Delayed write.
|
||||
Unlike
|
||||
.Fa bawrite ,
|
||||
.Fa bdwrite
|
||||
won't start any I/O.
|
||||
It only mark the buffer as dirty (B_DELWRI) and unbusy it.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn getblk "vp" "blkno" "size" "slpflag" "slptimeo"
|
||||
Get a block of requested size
|
||||
.Fa size
|
||||
that is associated with a given vnode and block
|
||||
offset, specified by
|
||||
.Fa vp
|
||||
and
|
||||
.Fa blkno
|
||||
If it is found in the block cache, make it busy and return it.
|
||||
Otherwise, return an empty block of the correct size.
|
||||
It is up to the caller to insure that the cached blocks be of the correct size.
|
||||
.Pp
|
||||
If
|
||||
.Fn getblk
|
||||
needs to sleep,
|
||||
.Fa slpflag
|
||||
and
|
||||
.Fa slptimeo
|
||||
are used as arguments for
|
||||
.Fn ltsleep .
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn geteblk "size"
|
||||
Allocate an empty, disassociated block of a given size
|
||||
.Fa size .
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn incore "vp" "blkno"
|
||||
Determine if a block associated to a given vnode and block offset
|
||||
is in the cache.
|
||||
If it's there, return a pointer to it.
|
||||
Note that
|
||||
.Fn incore
|
||||
doesn't busy the buffer unlike
|
||||
.Fn getblk .
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn allocbuf "bp" "size"
|
||||
Expand or contract the actual memory allocated to a buffer.
|
||||
If the buffer shrinks, data is lost, so it's up to the caller to have written
|
||||
it out *first*; this routine will not start a write.
|
||||
If the buffer grows, it's the callers responsibility to fill out
|
||||
the buffer's additional contents.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn brelse "bp"
|
||||
Unbusy a buffer and release it to the free lists.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn biodone "bp"
|
||||
Mark I/O complete on a buffer.
|
||||
If a callback has been requested by B_CALL, do so.
|
||||
Otherwise, wakeup waiters.
|
||||
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||||
.It Fn biowait "bp"
|
||||
Wait for operations on the buffer to complete.
|
||||
When they do, extract and return the I/O's error value.
|
||||
.El
|
||||
.\" ------------------------------------------------------------
|
||||
.Sh CODE REFERENCES
|
||||
This section describes places within the
|
||||
.Nx
|
||||
source tree where actual code implementing or using the name
|
||||
lookup subsystem can be found.
|
||||
All pathnames are relative to
|
||||
.Pa /usr/src .
|
||||
.Pp
|
||||
The buffer cache subsystem is implemented within the file
|
||||
.Pa sys/kern/vfs_bio.c .
|
||||
.Sh SEE ALSO
|
||||
.Xr intro 9 ,
|
||||
.Xr vnode 9
|
||||
.Rs
|
||||
.%A Marice J. Bach
|
||||
.%B "The Design of the UNIX Operating System"
|
||||
.%I "Prentice Hall"
|
||||
.%D 1986
|
||||
.Re
|
||||
.Rs
|
||||
.%A Marshall Kirk McKusick
|
||||
.%A Keith Bostic
|
||||
.%A Michael J. Karels
|
||||
.%A John S. Quarterman
|
||||
.%B "The Design and Implementation of the 4.4BSD UNIX Operating System"
|
||||
.%I "Addison Welley"
|
||||
.%D 1996
|
||||
.Re
|
||||
Loading…
Reference in New Issue
Block a user