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