[src/trunk]: src/share/man/man9 Add manpage for new device buffer queue inter...

[hannken <hannken%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/12559b096190
branches:  trunk
changeset: 534124:12559b096190
user:      hannken <hannken%NetBSD.org@localhost>
date:      Wed Jul 17 15:53:50 2002 +0000

description:
Add manpage for new device buffer queue interface.
With help from Thomas Klausner <wiz%netbsd.org@localhost>.

diffstat:

 share/man/man9/Makefile |    4 +-
 share/man/man9/bufq.9   |  135 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+), 2 deletions(-)

diffs (155 lines):

diff -r 1b9bd83a3f73 -r 12559b096190 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Wed Jul 17 15:53:21 2002 +0000
+++ b/share/man/man9/Makefile   Wed Jul 17 15:53:50 2002 +0000
@@ -1,10 +1,10 @@
-#       $NetBSD: Makefile,v 1.115 2002/07/16 00:36:45 lha Exp $
+#       $NetBSD: Makefile,v 1.116 2002/07/17 15:53:50 hannken Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
 MAN=   access.9 altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \
        bitmask_snprintf.9 bcmp.9 bcopy.9 bzero.9 \
-       bus_dma.9 bus_space.9 \
+       bufq.9 bus_dma.9 bus_space.9 \
        callout.9 cardbus.9 cnmagic.9 config.9 cons.9 copy.9 \
        cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 cpu_exit.9 cpu_fork.9 \
        cpu_initclocks.9 cpu_number.9 cpu_reboot.9 cpu_rootconf.9 \
diff -r 1b9bd83a3f73 -r 12559b096190 share/man/man9/bufq.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/bufq.9     Wed Jul 17 15:53:50 2002 +0000
@@ -0,0 +1,135 @@
+.\"     $NetBSD: bufq.9,v 1.1 2002/07/17 15:53:50 hannken Exp $
+.\"
+.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Juergen Hannken-Illjes.
+.\"
+.\" 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 NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd July 16, 2002
+.Dt BUFQ 9
+.Os
+.Sh NAME
+.Nm bufq ,
+.Nm bufq_state ,
+.Nm bufq_init ,
+.Nm BUFQ_PUT ,
+.Nm BUFQ_GET ,
+.Nm BUFQ_PEEK
+.Nd device buffer queues
+.Sh SYNOPSIS
+.Fd #include \*[Lt]buf.h\*[Gt]
+.Ft void
+.Fn bufq_init "struct bufq_state *bufq" "int flags"
+.Ft void
+.Fn BUFQ_PUT "struct bufq_state *bufq" "struct buf *bp"
+.Ft "struct buf *"
+.Fn BUFQ_GET "struct bufq_state *bufq"
+.Ft "struct buf *"
+.Fn BUFQ_PEEK "struct bufq_state *bufq"
+.Sh DESCRIPTION
+The
+.Nm
+subsystem is a set of operations for the management of device buffer queues.
+.Pp
+The primary data type for using the operations is the
+.Em bufq_state
+structure in
+.Pa buf.h :
+.Bd -literal
+struct bufq_state {
+       void (*bq_put)(struct bufq_state *, struct buf *);
+       struct buf *(*bq_get)(struct bufq_state *, int);
+       void *bq_private;
+       int bq_flags;           /* Flags from bufq_init() */
+};
+.Ed
+.Pp
+Valid values for the
+.Em flags
+argument are:
+.Pp
+.Bl -tag -offset indent -width BUFQ_SORT_RAWBLOCK -compact
+.It Dv BUFQ_SORT_RAWBLOCK
+sort by
+.Em b_rawblkno
+.It Dv BUFQ_SORT_CYLINDER
+sort by
+.Em b_cylinder
+and then by
+.Em b_rawblkno
+.It Dv BUFQ_FCFS
+queue strategy is first-come first-serve
+.It Dv BUFQ_DISKSORT
+queue strategy is min seek sort
+.It Dv BUFQ_READ_PRIO
+queue strategy is min seek sort for writes and first-come first-serve
+for reads with read priority
+.El
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn bufq_init "bufq" "flags"
+Initialize a
+.Em bufq_state
+descriptor.  The argument
+.Fa flags
+controls the strategy and sort order.
+.It Fn BUFQ_PUT "bufq" "bp"
+Put the buf
+.Fa bp
+in the queue.
+.It Fn BUFQ_GET "bufq"
+Get the next buf from the queue and remove it from the queue.
+Returns
+.Dv NULL
+if the queue is empty.
+.It Fn BUFQ_PEEK "bufq"
+Get the next buf from the queue without removal.
+Returns
+.Dv NULL
+if the queue is empty.
+.El
+.Sh CODE REFERENCES
+The actual code implementing the device buffer queues can be found
+in the file
+.Pa sys/kern/subr_disk.c .
+.Sh HISTORY
+The
+.Nm
+subsystem appeared in
+.Nx 1.7 .
+.Sh AUTHORS
+The
+.Nm
+subsystem was written by
+.if t .An J\(:urgen Hannken-Illjes
+.if n .An Juergen Hannken-Illjes
+.Aq hannken%NetBSD.org@localhost .