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.Vt "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 ".Dv 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 ".Dv 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 95.Dv BIO_ERROR 96is set. 97.It Va bio_done 98Pointer to function which will be called when the request is finished. 99.It Va bio_driver1 100Private use by the callee (i.e., the provider). 101.It Va bio_driver2 102Private use by the callee (i.e., the provider). 103.It Va bio_caller1 104Private use by the caller (i.e., the consumer). 105.It Va bio_caller2 106Private use by the caller (i.e., the consumer). 107.It Va bio_attribute 108Attribute string for 109.Dv BIO_GETATTR 110request. 111.It Va bio_from 112Consumer to use for request (attached to provider stored in 113.Va bio_to 114field) (typically read-only for a class). 115.It Va bio_to 116Destination provider (typically read-only for a class). 117.It Va bio_length 118Request length in bytes. 119.It Va bio_completed 120Number of bytes completed, but they may not be completed from 121the front of the request. 122.It Va bio_children 123Number of 124.Vt bio 125clones (typically read-only for a class). 126.It Va bio_inbed 127Number of finished 128.Vt bio 129clones. 130.It Va bio_parent 131Pointer to parent 132.Vt bio . 133.El 134.Pp 135The 136.Fn g_new_bio 137function allocates a new, empty 138.Vt bio 139structure. 140.Pp 141The 142.Fn g_clone_bio 143function allocates a new 144.Vt bio 145structure and copies the following fields from the 146.Vt bio 147given as an argument to clone: 148.Va bio_cmd , 149.Va bio_length , 150.Va bio_offset , 151.Va bio_data , 152.Va bio_attribute . 153The field 154.Va bio_parent 155in the clone points to the passed 156.Vt bio 157and the field 158.Va bio_children 159in the passed 160.Vt bio 161is incremented. 162.Pp 163This function should be used for every request which enters through 164the provider of a particular geom and needs to be scheduled down. 165Proper order is: 166.Pp 167.Bl -enum -compact 168.It 169Clone the received 170.Vt "struct bio" . 171.It 172Modify the clone. 173.It 174Schedule the clone on its own consumer. 175.El 176.Pp 177The 178.Fn g_destroy_bio 179function deallocates and destroys the given 180.Vt bio 181structure. 182.Pp 183The 184.Fn g_print_bio 185function prints information about the given 186.Vt bio 187structure (for debugging purposes). 188.Sh RETURN VALUES 189The 190.Fn g_new_bio 191and 192.Fn g_clone_bio 193functions return a pointer to the allocated 194.Vt bio , 195or 196.Dv NULL 197if an error occurred. 198.Sh EXAMPLES 199Implementation of 200.Dq Dv NULL Ns -transformation , 201meaning that an I/O request is cloned and scheduled down without any 202modifications. 203Let us assume that field 204.Va ex_consumer 205in structure 206.Vt example_softc 207contains a consumer attached to the provider we want to operate on. 208.Bd -literal -offset indent 209void 210example_start(struct bio *bp) 211{ 212 struct example_softc *sc; 213 struct bio *cbp; 214 215 printf("Request received: "); 216 g_print_bio(); 217 printf("\\n"); 218 219 sc = bp->bio_to->geom->softc; 220 if (sc == NULL) { 221 g_io_deliver(bp, ENXIO); 222 return; 223 } 224 225 /* Let's clone our bio request. */ 226 cbp = g_clone_bio(bp); 227 if (cbp == NULL) { 228 g_io_deliver(bp, ENOMEM); 229 return; 230 } 231 cbp->bio_done = g_std_done; /* Standard 'done' function. */ 232 233 /* Ok, schedule it down. */ 234 /* 235 * The consumer can be obtained from 236 * LIST_FIRST(&bp->bio_to->geom->consumers) as well, 237 * if there is only one in our geom. 238 */ 239 g_io_request(cbp, sc->ex_consumer); 240} 241.Ed 242.Sh SEE ALSO 243.Xr geom 4 , 244.Xr DECLARE_GEOM_CLASS 9 , 245.Xr g_access 9 , 246.Xr g_attach 9 , 247.Xr g_consumer 9 , 248.Xr g_data 9 , 249.Xr g_event 9 , 250.Xr g_geom 9 , 251.Xr g_provider 9 , 252.Xr g_provider_by_name 9 , 253.Xr g_wither_geom 9 254.Sh AUTHORS 255.An -nosplit 256This manual page was written by 257.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . 258