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