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