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 Mar 7, 2018
  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 .Nm g_reset_bio
  36 .Nd "GEOM bio controlling functions"
  37 .Sh SYNOPSIS
  38 .In sys/bio.h
  39 .In geom/geom.h
  40 .Ft "struct bio *"
  41 .Fn g_new_bio void
  42 .Ft "struct bio *"
  43 .Fn g_alloc_bio void
  44 .Ft "struct bio *"
  45 .Fn g_clone_bio "struct bio *bp"
  46 .Ft "struct bio *"
  47 .Fn g_duplicate_bio "struct bio *bp"
  48 .Ft void
  49 .Fn g_destroy_bio "struct bio *bp"
  50 .Ft void
  51 .Fn g_print_bio "struct bio *bp"
  52 .Ft void
  53 .Fn g_reset_bio "struct bio *bp"
  54 .Sh DESCRIPTION
  55 A
  56 .Vt "struct bio"
  57 is used by GEOM to describe I/O requests, its
  58 most important fields are described below:
  59 .Bl -tag -width ".Va bio_attribute"
  60 .It Va bio_cmd
  61 I/O request command.
  62 There are five I/O requests available in GEOM:
  63 .Bl -tag -width ".Dv BIO_GETATTR"
  64 .It Dv BIO_READ
  65 A read request.
  66 .It Dv BIO_WRITE
  67 A write request.
  68 .It Dv BIO_DELETE
  69 Indicates that a certain range of data is no longer used and that
  70 it can be erased or freed as the underlying technology supports.
  71 Technologies like flash adaptation layers can arrange to erase the relevant
  72 blocks before they will become reassigned and cryptographic devices may
  73 want to fill random bits into the range to reduce the amount of data
  74 available for attack.
  75 .It Dv BIO_GETATTR
  76 Inspect and manipulate out-of-band
  77 attributes on a particular provider or path.
  78 Attributes are named by ascii strings and are stored in the
  79 .Va bio_attribute
  80 field.
  81 .It Dv BIO_FLUSH
  82 Tells underlying providers to flush their write caches.
  83 .El
  84 .It Va bio_flags
  85 Available flags:
  86 .Bl -tag -width ".Dv BIO_ERROR"
  87 .It Dv BIO_ERROR
  88 Request failed (error value is stored in
  89 .Va bio_error
  90 field).
  91 .It Dv BIO_DONE
  92 Request finished.
  93 .El
  94 .It Va bio_cflags
  95 Private use by the consumer.
  96 .It Va bio_pflags
  97 Private use by the provider.
  98 .It Va bio_offset
  99 Offset into provider.
 100 .It Va bio_data
 101 Pointer to data buffer.
 102 .It Va bio_error
 103 Error value when
 104 .Dv BIO_ERROR
 105 is set.
 106 .It Va bio_done
 107 Pointer to function which will be called when the request is finished.
 108 .It Va bio_driver1
 109 Private use by the provider.
 110 .It Va bio_driver2
 111 Private use by the provider.
 112 .It Va bio_caller1
 113 Private use by the consumer.
 114 .It Va bio_caller2
 115 Private use by the consumer.
 116 .It Va bio_attribute
 117 Attribute string for
 118 .Dv BIO_GETATTR
 119 request.
 120 .It Va bio_from
 121 Consumer to use for request (attached to provider stored in
 122 .Va bio_to
 123 field) (typically read-only for a class).
 124 .It Va bio_to
 125 Destination provider (typically read-only for a class).
 126 .It Va bio_length
 127 Request length in bytes.
 128 .It Va bio_completed
 129 Number of bytes completed, but they may not be completed from
 130 the front of the request.
 131 .It Va bio_children
 132 Number of
 133 .Vt bio
 134 clones (typically read-only for a class).
 135 .It Va bio_inbed
 136 Number of finished
 137 .Vt bio
 138 clones.
 139 .It Va bio_parent
 140 Pointer to parent
 141 .Vt bio .
 142 .El
 143 .Pp
 144 The
 145 .Fn g_new_bio
 146 function allocates a new, empty
 147 .Vt bio
 148 structure.
 149 .Pp
 150 .Fn g_alloc_bio
 151 - same as
 152 .Fn g_new_bio ,
 153 but always succeeds (allocates bio with the
 154 .Dv M_WAITOK
 155 malloc flag).
 156 .Pp
 157 The
 158 .Fn g_clone_bio
 159 function allocates a new
 160 .Vt bio
 161 structure and copies the following fields from the
 162 .Vt bio
 163 given as an argument to clone:
 164 .Va bio_cmd ,
 165 .Va bio_length ,
 166 .Va bio_offset ,
 167 .Va bio_data ,
 168 .Va bio_attribute .
 169 The field
 170 .Va bio_parent
 171 in the clone points to the passed
 172 .Vt bio
 173 and the field
 174 .Va bio_children
 175 in the passed
 176 .Vt bio
 177 is incremented.
 178 .Pp
 179 This function should be used for every request which enters through
 180 the provider of a particular geom and needs to be scheduled down.
 181 Proper order is:
 182 .Pp
 183 .Bl -enum -compact
 184 .It
 185 Clone the received
 186 .Vt "struct bio" .
 187 .It
 188 Modify the clone.
 189 .It
 190 Schedule the clone on its own consumer.
 191 .El
 192 .Pp
 193 .Fn g_duplicate_bio
 194 - same as
 195 .Fn g_clone_bio ,
 196 but always succeeds (allocates bio with the
 197 .Dv M_WAITOK
 198 malloc flag).
 199 .Pp
 200 The
 201 .Fn g_destroy_bio
 202 function deallocates and destroys the given
 203 .Vt bio
 204 structure.
 205 .Pp
 206 The
 207 .Fn g_print_bio
 208 function prints information about the given
 209 .Vt bio
 210 structure (for debugging purposes).
 211 .Pp
 212 The
 213 .Fn g_reset_bio
 214 function resets the given
 215 .Vt bio
 216 structure back to its initial state.
 217 .Fn g_reset_bio
 218 preserves internal data structures, while setting all
 219 user visible fields to their initial values.
 220 When reusing a
 221 .Vt bio
 222 obtained from
 223 .Fn g_new_bio ,
 224 .Fn g_alloc_bio ,
 225 .Fn g_clone_bio ,
 226 or
 227 .Fn g_duplicate_bio
 228 for multiple transactions,
 229 .Fn g_reset_bio
 230 must be called between the transactions in lieu of
 231 .Fn bzero .
 232 While not strictly required for a
 233 .Vt bio
 234 structure created by other means,
 235 .Fn g_reset_bio
 236 should be used to initialize it and between transactions.
 237 .Sh RETURN VALUES
 238 The
 239 .Fn g_new_bio
 240 and
 241 .Fn g_clone_bio
 242 functions return a pointer to the allocated
 243 .Vt bio ,
 244 or
 245 .Dv NULL
 246 if an error occurred.
 247 .Sh EXAMPLES
 248 Implementation of
 249 .Dq Dv NULL Ns -transformation ,
 250 meaning that an I/O request is cloned and scheduled down without any
 251 modifications.
 252 Let us assume that field
 253 .Va ex_consumer
 254 in structure
 255 .Vt example_softc
 256 contains a consumer attached to the provider we want to operate on.
 257 .Bd -literal -offset indent
 258 void
 259 example_start(struct bio *bp)
 260 {
 261         struct example_softc *sc;
 262         struct bio *cbp;
 263
 264         printf("Request received: ");
 265         g_print_bio(bp);
 266         printf("\\n");
 267
 268         sc = bp->bio_to->geom->softc;
 269         if (sc == NULL) {
 270                 g_io_deliver(bp, ENXIO);
 271                 return;
 272         }
 273
 274         /* Let's clone our bio request. */
 275         cbp = g_clone_bio(bp);
 276         if (cbp == NULL) {
 277                 g_io_deliver(bp, ENOMEM);
 278                 return;
 279         }
 280         cbp->bio_done = g_std_done;     /* Standard 'done' function. */
 281
 282         /* Ok, schedule it down. */
 283         /*
 284          * The consumer can be obtained from
 285          * LIST_FIRST(&bp->bio_to->geom->consumer) as well,
 286          * if there is only one in our geom.
 287          */
 288         g_io_request(cbp, sc->ex_consumer);
 289 }
 290 .Ed
 291 .Sh SEE ALSO
 292 .Xr geom 4 ,
 293 .Xr DECLARE_GEOM_CLASS 9 ,
 294 .Xr g_access 9 ,
 295 .Xr g_attach 9 ,
 296 .Xr g_consumer 9 ,
 297 .Xr g_data 9 ,
 298 .Xr g_event 9 ,
 299 .Xr g_geom 9 ,
 300 .Xr g_provider 9 ,
 301 .Xr g_provider_by_name 9 ,
 302 .Xr g_wither_geom 9
 303 .Sh AUTHORS
 304 .An -nosplit
 305 This manual page was written by
 306 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org .