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