1.\" $NetBSD: bufq.9,v 1.20 2009/04/12 19:00:56 joerg Exp $ 2.\" 3.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Juergen Hannken-Illjes. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 24, 2009 31.Dt BUFQ 9 32.Os 33.Sh NAME 34.Nm bufq , 35.Nm bufq_state , 36.Nm bufq_alloc , 37.Nm bufq_drain , 38.Nm bufq_free , 39.Nm bufq_getstrategyname , 40.Nm bufq_move , 41.Nm bufq_put , 42.Nm bufq_get , 43.Nm bufq_peek , 44.Nm bufq_cancel 45.Nd device buffer queues 46.Sh SYNOPSIS 47.In sys/bufq.h 48.Ft int 49.Fn bufq_alloc "struct bufq_state **bufq" "const char *strategy" "int flags" 50.Ft void 51.Fn bufq_drain "struct bufq_state *bufq" 52.Ft void 53.Fn bufq_free "struct bufq_state *bufq" 54.Ft "const char *" 55.Fn bufq_getstrategyname "struct bufq_state *bufq" 56.Ft void 57.Fn bufq_move "struct bufq_state *dst" "struct bufq_state *src" 58.Ft void 59.Fn bufq_put "struct bufq_state *bufq" "struct buf *bp" 60.Ft "struct buf *" 61.Fn bufq_get "struct bufq_state *bufq" 62.Ft "struct buf *" 63.Fn bufq_peek "struct bufq_state *bufq" 64.Ft "struct buf *" 65.Fn bufq_cancel "struct bufq_state *bufq" "struct buf *bp" 66.Sh DESCRIPTION 67The 68.Nm 69subsystem is a set of operations for the management of device buffer queues. 70.Pp 71The primary data type for using the operations is the 72.Em bufq_state 73structure, which is opaque for users. 74.Sh FUNCTIONS 75.Bl -tag -width compact 76.It Fn bufq_alloc "bufq" "strategy" "flags" 77Allocate and initialize a 78.Em bufq_state 79descriptor. 80.Pp 81The argument 82.Fa strategy 83specifies a buffer queue strategy to be used for this buffer queue. 84The following special values can be used: 85.Pp 86.Bl -tag -offset indent -width BUFQ_DISK_DEFAULT_STRAT -compact 87.It Dv BUFQ_STRAT_ANY 88Let 89.Fn bufq_alloc 90select a strategy. 91.It Dv BUFQ_DISK_DEFAULT_STRAT 92Let 93.Fn bufq_alloc 94select a strategy, assuming it will be used for a normal disk device. 95.El 96.Pp 97Valid bits for the 98.Fa flags 99are: 100.Pp 101.Bl -tag -offset indent -width BUFQ_SORT_RAWBLOCK -compact 102.It Dv BUFQ_SORT_RAWBLOCK 103sort by 104.Em b_rawblkno 105.It Dv BUFQ_SORT_CYLINDER 106sort by 107.Em b_cylinder 108and then by 109.Em b_rawblkno 110.It Dv BUFQ_EXACT 111Fail if a strategy specified by 112.Fa strategy 113is not available. 114In that case, 115.Fa bufq_alloc 116returns 117.Dv ENOENT . 118If this flag is not specified, 119.Fn bufq_alloc 120will silently use one of available strategies. 121.El 122.It Fn bufq_drain "bufq" 123Drain a 124.Em bufq_state 125descriptor. 126.It Fn bufq_free "bufq" 127Destroy a 128.Em bufq_state 129descriptor. 130.It Fn bufq_getstrategyname "bufq" 131Get a strategy identifier of a buffer queue, the 132string returned will be NUL-terminated and it always 133will be a valid strategy name. 134.It Fn bufq_move "dst" "src" 135Move all requests from the buffer queue 136.Fa src 137to the buffer queue 138.Fa dst . 139.It Fn bufq_put "bufq" "bp" 140Put the buf 141.Fa bp 142in the queue. 143.It Fn bufq_get "bufq" 144Get the next buf from the queue and remove it from the queue. 145Returns 146.Dv NULL 147if the queue is empty. 148.It Fn bufq_peek "bufq" 149Get the next buf from the queue without removal. 150The next buf will remain the same until 151.Fn bufq_get , 152.Fn bufq_put , 153or 154.Fn bufq_drain 155is called. 156Returns 157.Dv NULL 158if the queue is empty. 159.It Fn bufq_cancel "bufq" "bp" 160Cancel the buf 161.Fa bp 162issued earlier on the queue. 163Returns 164.Dv NULL 165if the element can not be found on the queue or 166.Fa bp 167if it has been found and removed. 168This operation can be computationally expensive if there are 169a lot of buffers queued. 170.El 171.Sh CODE REFERENCES 172The actual code implementing the device buffer queues can be found 173in the file 174.Pa sys/kern/subr_bufq.c . 175.Sh HISTORY 176The 177.Nm 178subsystem appeared in 179.Nx 2.0 . 180.Sh AUTHORS 181The 182.Nm 183subsystem was written by 184.An J\(:urgen Hannken-Illjes 185.Aq hannken@NetBSD.org . 186