share/man/man9/g_bio.9

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