1.\" $NetBSD: bufq.9,v 1.22 2016/11/18 08:29:43 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.\" 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 November 17, 2016 31.Dt BUFQ 9 32.Os 33.Sh NAME 34.Nm bufq , 35.Nm bufq_init , 36.Nm bufq_register , 37.Nm bufq_unregister , 38.Nm bufq_state , 39.Nm bufq_alloc , 40.Nm bufq_drain , 41.Nm bufq_free , 42.Nm bufq_getstrategyname , 43.Nm bufq_move , 44.Nm bufq_put , 45.Nm bufq_get , 46.Nm bufq_peek , 47.Nm bufq_cancel 48.Nd device buffer queues 49.Sh SYNOPSIS 50.In sys/bufq.h 51.Ft void 52.Fn bufq_init "void" 53.Ft int 54.Fn bufq_register "struct bufq_strat *" 55.Ft int 56.Fn bufq_unregister "struct bufq_strat *" 57.Ft int 58.Fn bufq_alloc "struct bufq_state **bufq" "const char *strategy" "int flags" 59.Ft void 60.Fn bufq_drain "struct bufq_state *bufq" 61.Ft void 62.Fn bufq_free "struct bufq_state *bufq" 63.Ft "const char *" 64.Fn bufq_getstrategyname "struct bufq_state *bufq" 65.Ft void 66.Fn bufq_move "struct bufq_state *dst" "struct bufq_state *src" 67.Ft void 68.Fn bufq_put "struct bufq_state *bufq" "struct buf *bp" 69.Ft "struct buf *" 70.Fn bufq_get "struct bufq_state *bufq" 71.Ft "struct buf *" 72.Fn bufq_peek "struct bufq_state *bufq" 73.Ft "struct buf *" 74.Fn bufq_cancel "struct bufq_state *bufq" "struct buf *bp" 75.Sh DESCRIPTION 76The 77.Nm 78subsystem is a set of operations for the management of device buffer queues. 79Various strategies for ordering of entries in the buffer queues can be 80provided by loadable kernel modules (see 81.Xr module 9 ) . 82By default, the 83.Dv BUFQ_FCFS 84and 85.Dv BUFQ_DISKSORT 86strategies are included in 87the kernel; see 88.Xr options 4 89for more details. 90.Pp 91The primary data type for using the operations is the 92.Em bufq_state 93structure, which is opaque for users. 94Each buffer queue strategy module is defined by the 95.Em bufq_strat 96structure, which is also opaque for users. 97.Sh FUNCTIONS 98.Bl -tag -width compact 99.It Fn bufq_init "void" 100Initialize the 101.Nm 102subsystem. 103This routine must be called before any other 104.Nm 105routines. 106.It Fn bufq_register "bs" 107Registers the specified buffer queue strategy module so it can be used 108in subsequent operations. 109.It Fn bufq_unregister "bs" 110Unregisters the specified buffer queue strategy module. 111The routine will fail if any buffer queues for the specified strategy 112are in use (see 113.Fn bufq_alloc 114below). 115.It Fn bufq_alloc "bufq" "strategy" "flags" 116Allocate and initialize a 117.Em bufq_state 118descriptor. 119.Pp 120The argument 121.Fa strategy 122specifies a buffer queue strategy to be used for this buffer queue. 123The following special values can be used: 124.Pp 125.Bl -tag -offset indent -width BUFQ_DISK_DEFAULT_STRAT -compact 126.It Dv BUFQ_STRAT_ANY 127Let 128.Fn bufq_alloc 129select a strategy. 130.It Dv BUFQ_DISK_DEFAULT_STRAT 131Let 132.Fn bufq_alloc 133select a strategy, assuming it will be used for a normal disk device. 134.El 135.Pp 136Valid bits for the 137.Fa flags 138are: 139.Pp 140.Bl -tag -offset indent -width BUFQ_SORT_RAWBLOCK -compact 141.It Dv BUFQ_SORT_RAWBLOCK 142sort by 143.Em b_rawblkno 144.It Dv BUFQ_SORT_CYLINDER 145sort by 146.Em b_cylinder 147and then by 148.Em b_rawblkno 149.It Dv BUFQ_EXACT 150Fail if a strategy specified by 151.Fa strategy 152is not available. 153In that case, 154.Fa bufq_alloc 155returns 156.Dv ENOENT . 157If this flag is not specified, 158.Fn bufq_alloc 159will silently use one of available strategies. 160.El 161.Pp 162If a specific strategy is specified but not currently available, the 163.Nm bufq 164subsystem will attempt to auto-load the corresponding kernel module using 165.Xr module_autoload 9 . 166.It Fn bufq_drain "bufq" 167Drain a 168.Em bufq_state 169descriptor. 170.It Fn bufq_free "bufq" 171Destroy a 172.Em bufq_state 173descriptor. 174.It Fn bufq_getstrategyname "bufq" 175Get a strategy identifier of a buffer queue, the 176string returned will be NUL-terminated and it always 177will be a valid strategy name. 178.It Fn bufq_move "dst" "src" 179Move all requests from the buffer queue 180.Fa src 181to the buffer queue 182.Fa dst . 183.It Fn bufq_put "bufq" "bp" 184Put the buf 185.Fa bp 186in the queue. 187.It Fn bufq_get "bufq" 188Get the next buf from the queue and remove it from the queue. 189Returns 190.Dv NULL 191if the queue is empty. 192.It Fn bufq_peek "bufq" 193Get the next buf from the queue without removal. 194The next buf will remain the same until 195.Fn bufq_get , 196.Fn bufq_put , 197or 198.Fn bufq_drain 199is called. 200Returns 201.Dv NULL 202if the queue is empty. 203.It Fn bufq_cancel "bufq" "bp" 204Cancel the buf 205.Fa bp 206issued earlier on the queue. 207Returns 208.Dv NULL 209if the element can not be found on the queue or 210.Fa bp 211if it has been found and removed. 212This operation can be computationally expensive if there are 213a lot of buffers queued. 214.El 215.Sh CODE REFERENCES 216The actual code implementing the device buffer queues can be found 217in the file 218.Pa sys/kern/subr_bufq.c . 219The code implementing specific buffer queue strategies can be found in 220the files 221.Pa sys/kern/bufq_*.c . 222.Sh NOTES 223A list of currently available buffer queue strategies is available via 224the 225.Dq kern.bufq.strategies 226.Xr sysctl 7 227variables. 228.Sh HISTORY 229The 230.Nm 231subsystem appeared in 232.Nx 2.0 . 233.Sh AUTHORS 234The 235.Nm 236subsystem was written by 237.An J\(:urgen Hannken-Illjes 238.Aq hannken@NetBSD.org . 239