Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

$FreeBSD: head/share/man/man9/g_bio.9 125699 2004-02-11 10:06:18Z pjd $

.Dd January 16, 2004 .Dt g_bio 9 .Os .Sh NAME .Nm g_new_bio , .Nm g_clone_bio , .Nm g_destroy_bio .Nd "bio controlling functions" .Sh SYNOPSIS n sys/bio.h n geom/geom.h .Ft "struct bio *" .Fn g_new_bio void .Ft "struct bio *" .Fn g_clone_bio "struct bio *bp" .Ft void .Fn g_destroy_bio "struct bio *bp" .Sh DESCRIPTION The .Fa bio structure is used by GEOM to describe I/O requests. Most important fields of .Fa struct bio are described below: l -tag -width ".Va bio_attribute" t Va bio_cmd I/O request number. There are four I/O requests available in GEOM: l -tag -width BIO_GETATTR t Dv BIO_READ Self explanatory. t Dv BIO_WRITE Self explanatory. t Dv BIO_DELETE Delete indicates that a certain range of data is no longer used and that it can be erased or freed as the underlying technology supports. Technologies like flash adaptation layers can arrange to erase the relevant blocks before they will become reassigned and cryptographic devices may want to fill random bits into the range to reduce the amount of data available for attack. t Dv BIO_GETATTR Get attribute supports inspection and manipulation of out-of-band attributes on a particular provider or path. Attributes are named by ascii strings and are stored in the .Va bio_attribute field. .El t Va bio_offset Offset into provider. t Va bio_data Pointer to data buffer. t Va bio_flags Available flags: l -tag -width BIO_GETATTR t Dv BIO_ERROR Request failed (error value is stored in .Va bio_error ) field. t Dv BIO_DONE Request finished. t Dv BIO_FLAG1 Avaliable for private use. t Dv BIO_FLAG2 Avaliable for private use. .El t Va bio_error Error value when BIO_ERROR is set. t Va bio_done Pointer to function which will be called on request finish. t Va bio_driver1 Private use by the callee (ie: the provider). t Va bio_driver2 Private use by the callee (ie: the provider). t Va bio_caller1 Private use by the caller (ie: the consumer). t Va bio_caller2 Private use by the caller (ie: the consumer). t Va bio_attribute Attribute string for BIO_GETATTR request. t Va bio_from Consumer to use for request (attached to provider stored in .Va bio_to field) (typically read-only for a class). t Va bio_to Destination provider (typically read-only for a class). t Va bio_length Request length in bytes. t Va bio_completed Number of bytes completed, but they may not be completed from the front of the request. t Va bio_children Number of bio clones (typically read-only for a class). t Va bio_inbed Number of finished bio clones. t Va bio_parent Pointer to parent bio. .El

p The .Fn g_new_bio function allocates a new, empty .Vt bio structure.

p The .Fn g_clone_bio function allocates a new .Vt bio structure and copies those fields from the .Vt bio structure given as an argument to clone: .Va bio_cmd , .Va bio_length , .Va bio_offset , .Va bio_data , .Va bio_attribute . The field .Va bio_parent in clone is set to source .Vt bio and the field .Va bio_children in parent is increased.

p This function should be used for every request which enters through the provider of a particular geom and needs to be scheduled down. Proper order is:

p l -enum -compact t Clone .Vt "struct bio" . t Modify the clone. t Schedule the clone on its own consumer. .El

p The .Fn g_destroy_bio function kills the given .Vt bio structure. .Sh EXAMPLES Implementation of .Dq Dv NULL Ns -transformation , meaning that an I/O request is cloned and scheduled down without any modifications. Let's assume that field .Va ex_consumer in structure .Vt example_softc contains a consumer attached to the provider we want to operate on. d -literal -offset indent void example_start(struct bio *bp) { struct example_softc *sc; struct bio *cbp; sc = bp->bio_to->geom->softc; if (sc == NULL) { g_io_deliver(bp, ENXIO); return; } /* Let's clone our bio request. */ cbp = g_clone_bio(bp); if (cbp == NULL) { g_io_deliver(bp, ENOMEM); return; } cbp->bio_done = g_std_done; /* Standard 'done' function. */ /* Ok, schedule it down. */ /* * The consumer can be obtained from * LIST_FIRST(&bp->bio_to->geom->consumers) as well, * if there is only one in our geom. */ g_io_request(cbp, sc->ex_consumer); } .Ed .Sh SEE ALSO .Xr DECLARE_GEOM_CLASS 9 , .Xr geom 4 , .Xr g_attach 9 , .Xr g_consumer 9 , .Xr g_data 9 , .Xr g_event 9 , .Xr g_geom 9 , .Xr g_provider 9 , .Xr g_provider_by_name 9 , .Xr g_wither_geom 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .