diff options
Diffstat (limited to 'static/netbsd/man9/bufq.9')
| -rw-r--r-- | static/netbsd/man9/bufq.9 | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/static/netbsd/man9/bufq.9 b/static/netbsd/man9/bufq.9 new file mode 100644 index 00000000..80f62e7f --- /dev/null +++ b/static/netbsd/man9/bufq.9 @@ -0,0 +1,238 @@ +.\" $NetBSD: bufq.9,v 1.22 2016/11/18 08:29:43 wiz 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. +.\" +.\" 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 November 17, 2016 +.Dt BUFQ 9 +.Os +.Sh NAME +.Nm bufq , +.Nm bufq_init , +.Nm bufq_register , +.Nm bufq_unregister , +.Nm bufq_state , +.Nm bufq_alloc , +.Nm bufq_drain , +.Nm bufq_free , +.Nm bufq_getstrategyname , +.Nm bufq_move , +.Nm bufq_put , +.Nm bufq_get , +.Nm bufq_peek , +.Nm bufq_cancel +.Nd device buffer queues +.Sh SYNOPSIS +.In sys/bufq.h +.Ft void +.Fn bufq_init "void" +.Ft int +.Fn bufq_register "struct bufq_strat *" +.Ft int +.Fn bufq_unregister "struct bufq_strat *" +.Ft int +.Fn bufq_alloc "struct bufq_state **bufq" "const char *strategy" "int flags" +.Ft void +.Fn bufq_drain "struct bufq_state *bufq" +.Ft void +.Fn bufq_free "struct bufq_state *bufq" +.Ft "const char *" +.Fn bufq_getstrategyname "struct bufq_state *bufq" +.Ft void +.Fn bufq_move "struct bufq_state *dst" "struct bufq_state *src" +.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" +.Ft "struct buf *" +.Fn bufq_cancel "struct bufq_state *bufq" "struct buf *bp" +.Sh DESCRIPTION +The +.Nm +subsystem is a set of operations for the management of device buffer queues. +Various strategies for ordering of entries in the buffer queues can be +provided by loadable kernel modules (see +.Xr module 9 ) . +By default, the +.Dv BUFQ_FCFS +and +.Dv BUFQ_DISKSORT +strategies are included in +the kernel; see +.Xr options 4 +for more details. +.Pp +The primary data type for using the operations is the +.Em bufq_state +structure, which is opaque for users. +Each buffer queue strategy module is defined by the +.Em bufq_strat +structure, which is also opaque for users. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn bufq_init "void" +Initialize the +.Nm +subsystem. +This routine must be called before any other +.Nm +routines. +.It Fn bufq_register "bs" +Registers the specified buffer queue strategy module so it can be used +in subsequent operations. +.It Fn bufq_unregister "bs" +Unregisters the specified buffer queue strategy module. +The routine will fail if any buffer queues for the specified strategy +are in use (see +.Fn bufq_alloc +below). +.It Fn bufq_alloc "bufq" "strategy" "flags" +Allocate and initialize a +.Em bufq_state +descriptor. +.Pp +The argument +.Fa strategy +specifies a buffer queue strategy to be used for this buffer queue. +The following special values can be used: +.Pp +.Bl -tag -offset indent -width BUFQ_DISK_DEFAULT_STRAT -compact +.It Dv BUFQ_STRAT_ANY +Let +.Fn bufq_alloc +select a strategy. +.It Dv BUFQ_DISK_DEFAULT_STRAT +Let +.Fn bufq_alloc +select a strategy, assuming it will be used for a normal disk device. +.El +.Pp +Valid bits for the +.Fa flags +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_EXACT +Fail if a strategy specified by +.Fa strategy +is not available. +In that case, +.Fa bufq_alloc +returns +.Dv ENOENT . +If this flag is not specified, +.Fn bufq_alloc +will silently use one of available strategies. +.El +.Pp +If a specific strategy is specified but not currently available, the +.Nm bufq +subsystem will attempt to auto-load the corresponding kernel module using +.Xr module_autoload 9 . +.It Fn bufq_drain "bufq" +Drain a +.Em bufq_state +descriptor. +.It Fn bufq_free "bufq" +Destroy a +.Em bufq_state +descriptor. +.It Fn bufq_getstrategyname "bufq" +Get a strategy identifier of a buffer queue, the +string returned will be NUL-terminated and it always +will be a valid strategy name. +.It Fn bufq_move "dst" "src" +Move all requests from the buffer queue +.Fa src +to the buffer queue +.Fa dst . +.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. +The next buf will remain the same until +.Fn bufq_get , +.Fn bufq_put , +or +.Fn bufq_drain +is called. +Returns +.Dv NULL +if the queue is empty. +.It Fn bufq_cancel "bufq" "bp" +Cancel the buf +.Fa bp +issued earlier on the queue. +Returns +.Dv NULL +if the element can not be found on the queue or +.Fa bp +if it has been found and removed. +This operation can be computationally expensive if there are +a lot of buffers queued. +.El +.Sh CODE REFERENCES +The actual code implementing the device buffer queues can be found +in the file +.Pa sys/kern/subr_bufq.c . +The code implementing specific buffer queue strategies can be found in +the files +.Pa sys/kern/bufq_*.c . +.Sh NOTES +A list of currently available buffer queue strategies is available via +the +.Dq kern.bufq.strategies +.Xr sysctl 7 +variables. +.Sh HISTORY +The +.Nm +subsystem appeared in +.Nx 2.0 . +.Sh AUTHORS +The +.Nm +subsystem was written by +.An J\(:urgen Hannken-Illjes +.Aq hannken@NetBSD.org . |