buffercache.9 man page from netbsd, ported by sven dehmlow, +mlinks;

some tidy up from myself;

ok tedu@ deraadt@

2 files changed, 398 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 3422079cfa3..65f9d0cd7c2 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,9 +1,9 @@
-#	$OpenBSD: Makefile,v 1.81 2004/09/19 23:22:29 jaredy Exp $
+#	$OpenBSD: Makefile,v 1.82 2004/09/22 21:26:02 jmc Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
 
-MAN=	altq.9 audio.9 autoconf.9 boot.9 bus_dma.9 bus_space.9 \
+MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	copy.9 crypto.9 ctxsw.9 disk.9 disklabel.9 \
 	dohooks.9 dopowerhooks.9 doshutdownhooks.9 dostartuphooks.9 \
 	extattr.9 file.9 \
@@ -28,7 +28,12 @@ MLINKS+=autoconf.9 config_init.9 autoconf.9 config_search.9 \
 	autoconf.9 config_attach.9 autoconf.9 config_detach.9 \
 	autoconf.9 config_activate.9 autoconf.9 config_deactivate.9 \
 	autoconf.9 config_defer.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_dma.9 bus_dmamap_create.9 bus_dma.9 bus_dmamap_destroy.9 \
 	bus_dma.9 bus_dmamap_load.9 bus_dma.9 bus_dmamap_load_mbuf.9 \
 	bus_dma.9 bus_dmamap_load_uio.9 bus_dma.9 bus_dmamap_load_raw.9 \
diff --git a/share/man/man9/buffercache.9 b/share/man/man9/buffercache.9
new file mode 100644
index 00000000000..e26d3d2ff83
--- /dev/null
+++ b/share/man/man9/buffercache.9
@@ -0,0 +1,390 @@
+.\"	$OpenBSD: buffercache.9,v 1.1 2004/09/22 21:26:02 jmc Exp $
+.\"     $NetBSD: buffercache.9,v 1.13 2004/06/25 15:31:37 wiz 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 August 30, 2004
+.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 int
+.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 filesystem to improve I/O performance using
+in-core caches of filesystem blocks.
+.Pp
+The kernel memory used to cache a block is called a buffer and
+described by a
+.Em buf
+structure.
+In addition to describing a cached block, a
+.Em buf
+structure is also used to describe an I/O request as a part of
+the disk driver interface.
+.\" XXX struct buf, B_ flags, MP locks, etc.
+.\" XXX free list, hash queue, 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
+calls
+.Fn getblk
+to allocate a buffer with enough pages for
+.Fa size
+and reads the specified disk block into it.
+.Pp
+The buffer returned by
+.Fn bread
+is marked as busy.
+(The
+.Dv 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 the variants of
+.Fn bwrite .
+Otherwise, it should be unbusied using
+.Fn brelse .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Xo
+.Fo breadn
+.Fa "vp"
+.Fa "blkno"
+.Fa "size"
+.Fa "rablks"
+.Fa "rasizes"
+.Fa "nrablks"
+.Fa "cred"
+.Fa "bpp"
+.Fc
+.Xc
+Get a buffer as
+.Fn bread .
+In addition,
+.Fn breadn
+will start read-ahead of blocks specified by
+.Fa rablk ,
+.Fa rasizes ,
+and
+.Fa nrablks .
+The read-ahead blocks aren't returned, but are available in cache for
+future accesses.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.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 simply calls
+.Fn breadn
+with
+.Fa nrablks
+set to 1.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn bwrite "bp"
+Write a block.
+Start I/O for write using
+.Fn VOP_STRATEGY .
+Then, unless the
+.Dv 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 the
+.Dv B_ASYNC
+flag in
+.Fa bp
+and simply call
+.Fn VOP_BWRITE ,
+which results in
+.Fn bwrite
+for most filesystems.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn bdwrite "bp"
+Delayed write.
+Unlike
+.Fn bawrite ,
+.Fn bdwrite
+won't start any I/O.
+It only marks the buffer as dirty
+.Pq Dv B_DELWRI
+and unbusies it.
+This routine should be used when the buffer is expected
+to be modified again soon, typically a small write that
+partially fills a buffer.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.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, mark it as having been found,
+make it busy and return it.
+Otherwise, return an empty block of the correct size.
+It is up to the caller to ensure that the cached blocks
+are of the correct size.
+.Pp
+If
+.Fn getblk
+needs to sleep,
+.Fa slpflag
+and
+.Fa slptimeo
+are used as arguments for
+.Fn tsleep .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.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 with a given vnode and block offset
+is in the cache.
+If it is there, return a pointer to it.
+Note that
+.Fn incore
+doesn't mark the buffer as busy unlike
+.Fn getblk .
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn allocbuf "bp" "size"
+Expand or contract the actual memory allocated to a buffer.
+If the buffer shrinks, the truncated part of the data
+is lost, so it is up to the caller to have written
+it out
+.Em first
+if needed; this routine will not start a write.
+If the buffer grows, it is the caller's responsibility to fill out
+the buffer's additional contents.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.It Fn brelse "bp"
+Unlock a buffer by clearing the
+.Dv B_AGE ,
+.Dv B_ASYNC ,
+.Dv B_BUSY ,
+.Dv B_NOCACHE ,
+and
+.Dv B_DEFERRED
+flags 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
+.Dv B_CALL ,
+do so.
+Otherwise, wake up the waiting processes.
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.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
+.Ox
+source tree where actual code implementing the buffer cache 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 ,
+.Xr VOP_STRATEGY 9
+.Rs
+.%A Maurice 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 Operating System"
+.%I "Addison Wesley"
+.%D 1996
+.Re
+.Rs
+.%A Leffler, et. al.
+.%B "The Design and Implementation of the 4.3 BSD Unix Operating System"
+.%I Addison Wesley
+.%D 1989
+.Re
+.\" ------------------------------------------------------------
+.Sh BUGS
+In the current implementation,
+.Fn bread
+and its variants
+don't use a specified credential.