share/man/man9/bufq.9

   1 .\"     $NetBSD: bufq.9,v 1.19 2009/01/24 10:39:58 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 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
  67 The
  68 .Nm
  69 subsystem is a set of operations for the management of device buffer queues.
  70 .Pp
  71 The primary data type for using the operations is the
  72 .Em bufq_state
  73 structure, which is opaque for users.
  74 .Sh FUNCTIONS
  75 .Bl -tag -width compact
  76 .It Fn bufq_alloc "bufq" "strategy" "flags"
  77 Allocate and initialize a
  78 .Em bufq_state
  79 descriptor.
  80 .Pp
  81 The argument
  82 .Fa strategy
  83 specifies a buffer queue strategy to be used for this buffer queue.
  84 The 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
  88 Let
  89 .Fn bufq_alloc
  90 select a strategy.
  91 .It Dv BUFQ_DISK_DEFAULT_STRAT
  92 Let
  93 .Fn bufq_alloc
  94 select a strategy, assuming it will be used for a normal disk device.
  95 .El
  96 .Pp
  97 Valid bits for the
  98 .Fa flags
  99 are:
 100 .Pp
 101 .Bl -tag -offset indent -width BUFQ_SORT_RAWBLOCK -compact
 102 .It Dv BUFQ_SORT_RAWBLOCK
 103 sort by
 104 .Em b_rawblkno
 105 .It Dv BUFQ_SORT_CYLINDER
 106 sort by
 107 .Em b_cylinder
 108 and then by
 109 .Em b_rawblkno
 110 .It Dv BUFQ_EXACT
 111 Fail if a strategy specified by
 112 .Fa strategy
 113 is not available.
 114 In that case,
 115 .Fa bufq_alloc
 116 returns
 117 .Dv ENOENT .
 118 If this flag is not specified,
 119 .Fn bufq_alloc
 120 will silently use one of available strategies.
 121 .El
 122 .It Fn bufq_drain "bufq"
 123 Drain a
 124 .Em bufq_state
 125 descriptor.
 126 .It Fn bufq_free "bufq"
 127 Destroy a
 128 .Em bufq_state
 129 descriptor.
 130 .It Fn bufq_getstrategyname "bufq"
 131 Get a strategy identifier of a buffer queue, the
 132 string returned will be NUL-terminated and it always
 133 will be a valid strategy name.
 134 .It Fn bufq_move "dst" "src"
 135 Move all requests from the buffer queue
 136 .Fa src
 137 to the buffer queue
 138 .Fa dst .
 139 .It Fn bufq_put "bufq" "bp"
 140 Put the buf
 141 .Fa bp
 142 in the queue.
 143 .It Fn bufq_get "bufq"
 144 Get the next buf from the queue and remove it from the queue.
 145 Returns
 146 .Dv NULL
 147 if the queue is empty.
 148 .It Fn bufq_peek "bufq"
 149 Get the next buf from the queue without removal.
 150 The next buf will remain the same until
 151 .Fn bufq_get ,
 152 .Fn bufq_put ,
 153 or
 154 .Fn bufq_drain
 155 is called.
 156 Returns
 157 .Dv NULL
 158 if the queue is empty.
 159 .It Fn bufq_cancel "bufq" "bp"
 160 Cancel the buf
 161 .Fa bp
 162 issued earlier on the queue.
 163 Returns
 164 .Dv NULL
 165 if the element can not be found on the queue or
 166 .Fa bp
 167 if it has been found and removed.
 168 This operation can be computationally expensive if there are
 169 a lot of buffers queued.
 170 .El
 171 .Sh CODE REFERENCES
 172 The actual code implementing the device buffer queues can be found
 173 in the file
 174 .Pa sys/kern/subr_bufq.c .
 175 .Sh HISTORY
 176 The
 177 .Nm
 178 subsystem appeared in
 179 .Nx 2.0 .
 180 .Sh AUTHORS
 181 The
 182 .Nm
 183 subsystem was written by
 184 .An J\(:urgen Hannken-Illjes
 185 .Aq hannken@NetBSD.org .