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