share/man/man9/g_bio.9

   1 .\"
   2 .\" Copyright (c) 2004-2006 Pawel Jakub Dawidek <pjd@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 1, 2006
  28 .Dt G_BIO 9
  29 .Os
  30 .Sh NAME
  31 .Nm g_new_bio ,
  32 .Nm g_clone_bio ,
  33 .Nm g_destroy_bio ,
  34 .Nm g_print_bio
  35 .Nd "GEOM bio controlling functions"
  36 .Sh SYNOPSIS
  37 .In sys/bio.h
  38 .In geom/geom.h
  39 .Ft "struct bio *"
  40 .Fn g_new_bio void
  41 .Ft "struct bio *"
  42 .Fn g_alloc_bio void
  43 .Ft "struct bio *"
  44 .Fn g_clone_bio "struct bio *bp"
  45 .Ft "struct bio *"
  46 .Fn g_duplicate_bio "struct bio *bp"
  47 .Ft void
  48 .Fn g_destroy_bio "struct bio *bp"
  49 .Ft void
  50 .Fn g_print_bio "struct bio *bp"
  51 .Sh DESCRIPTION
  52 A
  53 .Vt "struct bio"
  54 is used by GEOM to describe I/O requests, its
  55 most important fields are described below:
  56 .Bl -tag -width ".Va bio_attribute"
  57 .It Va bio_cmd
  58 I/O request command.
  59 There are four I/O requests available in GEOM:
  60 .Bl -tag -width ".Dv BIO_GETATTR"
  61 .It Dv BIO_READ
  62 A read request.
  63 .It Dv BIO_WRITE
  64 A write request.
  65 .It Dv BIO_DELETE
  66 Indicates that a certain range of data is no longer used and that
  67 it can be erased or freed as the underlying technology supports.
  68 Technologies like flash adaptation layers can arrange to erase the relevant
  69 blocks before they will become reassigned and cryptographic devices may
  70 want to fill random bits into the range to reduce the amount of data
  71 available for attack.
  72 .It Dv BIO_GETATTR
  73 Inspect and manipulate out-of-band
  74 attributes on a particular provider or path.
  75 Attributes are named by ascii strings and are stored in the
  76 .Va bio_attribute
  77 field.
  78 .It Dv BIO_FLUSH
  79 Tells underlying providers to flush their write caches.
  80 .El
  81 .It Va bio_flags
  82 Available flags:
  83 .Bl -tag -width ".Dv BIO_ERROR"
  84 .It Dv BIO_ERROR
  85 Request failed (error value is stored in
  86 .Va bio_error
  87 field).
  88 .It Dv BIO_DONE
  89 Request finished.
  90 .El
  91 .It Va bio_cflags
  92 Private use by the consumer.
  93 .It Va bio_pflags
  94 Private use by the provider.
  95 .It Va bio_offset
  96 Offset into provider.
  97 .It Va bio_data
  98 Pointer to data buffer.
  99 .It Va bio_error
 100 Error value when
 101 .Dv BIO_ERROR
 102 is set.
 103 .It Va bio_done
 104 Pointer to function which will be called when the request is finished.
 105 .It Va bio_driver1
 106 Private use by the provider.
 107 .It Va bio_driver2
 108 Private use by the provider.
 109 .It Va bio_caller1
 110 Private use by the consumer.
 111 .It Va bio_caller2
 112 Private use by the consumer.
 113 .It Va bio_attribute
 114 Attribute string for
 115 .Dv BIO_GETATTR
 116 request.
 117 .It Va bio_from
 118 Consumer to use for request (attached to provider stored in
 119 .Va bio_to
 120 field) (typically read-only for a class).
 121 .It Va bio_to
 122 Destination provider (typically read-only for a class).
 123 .It Va bio_length
 124 Request length in bytes.
 125 .It Va bio_completed
 126 Number of bytes completed, but they may not be completed from
 127 the front of the request.
 128 .It Va bio_children
 129 Number of
 130 .Vt bio
 131 clones (typically read-only for a class).
 132 .It Va bio_inbed
 133 Number of finished
 134 .Vt bio
 135 clones.
 136 .It Va bio_parent
 137 Pointer to parent
 138 .Vt bio .
 139 .El
 140 .Pp
 141 The
 142 .Fn g_new_bio
 143 function allocates a new, empty
 144 .Vt bio
 145 structure.
 146 .Pp
 147 .Fn g_alloc_bio
 148 - same as
 149 .Fn g_new_bio ,
 150 but always succeeds (allocates bio with the
 151 .Dv M_WAITOK
 152 malloc flag).
 153 .Pp
 154 The
 155 .Fn g_clone_bio
 156 function allocates a new
 157 .Vt bio
 158 structure and copies the following fields from the
 159 .Vt bio
 160 given as an argument to clone:
 161 .Va bio_cmd ,
 162 .Va bio_length ,
 163 .Va bio_offset ,
 164 .Va bio_data ,
 165 .Va bio_attribute .
 166 The field
 167 .Va bio_parent
 168 in the clone points to the passed
 169 .Vt bio
 170 and the field
 171 .Va bio_children
 172 in the passed
 173 .Vt bio
 174 is incremented.
 175 .Pp
 176 This function should be used for every request which enters through
 177 the provider of a particular geom and needs to be scheduled down.
 178 Proper order is:
 179 .Pp
 180 .Bl -enum -compact
 181 .It
 182 Clone the received
 183 .Vt "struct bio" .
 184 .It
 185 Modify the clone.
 186 .It
 187 Schedule the clone on its own consumer.
 188 .El
 189 .Pp
 190 .Fn g_duplicate_bio
 191 - same as
 192 .Fn g_clone_bio ,
 193 but always succeeds (allocates bio with the
 194 .Dv M_WAITOK
 195 malloc flag).
 196 .Pp
 197 The
 198 .Fn g_destroy_bio
 199 function deallocates and destroys the given
 200 .Vt bio
 201 structure.
 202 .Pp
 203 The
 204 .Fn g_print_bio
 205 function prints information about the given
 206 .Vt bio
 207 structure (for debugging purposes).
 208 .Sh RETURN VALUES
 209 The
 210 .Fn g_new_bio
 211 and
 212 .Fn g_clone_bio
 213 functions return a pointer to the allocated
 214 .Vt bio ,
 215 or
 216 .Dv NULL
 217 if an error occurred.
 218 .Sh EXAMPLES
 219 Implementation of
 220 .Dq Dv NULL Ns -transformation ,
 221 meaning that an I/O request is cloned and scheduled down without any
 222 modifications.
 223 Let us assume that field
 224 .Va ex_consumer
 225 in structure
 226 .Vt example_softc
 227 contains a consumer attached to the provider we want to operate on.
 228 .Bd -literal -offset indent
 229 void
 230 example_start(struct bio *bp)
 231 {
 232         struct example_softc *sc;
 233         struct bio *cbp;
 234
 235         printf("Request received: ");
 236         g_print_bio(bp);
 237         printf("\\n");
 238
 239         sc = bp->bio_to->geom->softc;
 240         if (sc == NULL) {
 241                 g_io_deliver(bp, ENXIO);
 242                 return;
 243         }
 244
 245         /* Let's clone our bio request. */
 246         cbp = g_clone_bio(bp);
 247         if (cbp == NULL) {
 248                 g_io_deliver(bp, ENOMEM);
 249                 return;
 250         }
 251         cbp->bio_done = g_std_done;     /* Standard 'done' function. */
 252
 253         /* Ok, schedule it down. */
 254         /*
 255          * The consumer can be obtained from
 256          * LIST_FIRST(&bp->bio_to->geom->consumers) as well,
 257          * if there is only one in our geom.
 258          */
 259         g_io_request(cbp, sc->ex_consumer);
 260 }
 261 .Ed
 262 .Sh SEE ALSO
 263 .Xr geom 4 ,
 264 .Xr DECLARE_GEOM_CLASS 9 ,
 265 .Xr g_access 9 ,
 266 .Xr g_attach 9 ,
 267 .Xr g_consumer 9 ,
 268 .Xr g_data 9 ,
 269 .Xr g_event 9 ,
 270 .Xr g_geom 9 ,
 271 .Xr g_provider 9 ,
 272 .Xr g_provider_by_name 9 ,
 273 .Xr g_wither_geom 9
 274 .Sh AUTHORS
 275 .An -nosplit
 276 This manual page was written by
 277 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .