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