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