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