2 .\" Copyright (c) 2004-2006 Pawel Jakub Dawidek <pjd@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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.
36 .Nd "GEOM bio controlling functions"
45 .Fn g_clone_bio "struct bio *bp"
47 .Fn g_duplicate_bio "struct bio *bp"
49 .Fn g_destroy_bio "struct bio *bp"
51 .Fn g_print_bio "struct bio *bp"
53 .Fn g_reset_bio "struct bio *bp"
57 is used by GEOM to describe I/O requests, its
58 most important fields are described below:
59 .Bl -tag -width ".Va bio_attribute"
62 There are four I/O requests available in GEOM:
63 .Bl -tag -width ".Dv BIO_GETATTR"
69 Indicates that a certain range of data is no longer used and that
70 it can be erased or freed as the underlying technology supports.
71 Technologies like flash adaptation layers can arrange to erase the relevant
72 blocks before they will become reassigned and cryptographic devices may
73 want to fill random bits into the range to reduce the amount of data
76 Inspect and manipulate out-of-band
77 attributes on a particular provider or path.
78 Attributes are named by ascii strings and are stored in the
82 Tells underlying providers to flush their write caches.
86 .Bl -tag -width ".Dv BIO_ERROR"
88 Request failed (error value is stored in
95 Private use by the consumer.
97 Private use by the provider.
101 Pointer to data buffer.
107 Pointer to function which will be called when the request is finished.
109 Private use by the provider.
111 Private use by the provider.
113 Private use by the consumer.
115 Private use by the consumer.
121 Consumer to use for request (attached to provider stored in
123 field) (typically read-only for a class).
125 Destination provider (typically read-only for a class).
127 Request length in bytes.
129 Number of bytes completed, but they may not be completed from
130 the front of the request.
134 clones (typically read-only for a class).
146 function allocates a new, empty
153 but always succeeds (allocates bio with the
159 function allocates a new
161 structure and copies the following fields from the
163 given as an argument to clone:
171 in the clone points to the passed
179 This function should be used for every request which enters through
180 the provider of a particular geom and needs to be scheduled down.
190 Schedule the clone on its own consumer.
196 but always succeeds (allocates bio with the
202 function deallocates and destroys the given
208 function prints information about the given
210 structure (for debugging purposes).
214 function resets the given
216 structure back to its initial state.
218 preserves internal data structures, while setting all
219 user visible fields to their initial values.
228 for multiple transactions,
230 must be called between the transactions in lieu of
232 While not strictly required for a
234 structure created by other means,
236 should be used to initialize it and between transactions.
242 functions return a pointer to the allocated
246 if an error occurred.
249 .Dq Dv NULL Ns -transformation ,
250 meaning that an I/O request is cloned and scheduled down without any
252 Let us assume that field
256 contains a consumer attached to the provider we want to operate on.
257 .Bd -literal -offset indent
259 example_start(struct bio *bp)
261 struct example_softc *sc;
264 printf("Request received: ");
268 sc = bp->bio_to->geom->softc;
270 g_io_deliver(bp, ENXIO);
274 /* Let's clone our bio request. */
275 cbp = g_clone_bio(bp);
277 g_io_deliver(bp, ENOMEM);
280 cbp->bio_done = g_std_done; /* Standard 'done' function. */
282 /* Ok, schedule it down. */
284 * The consumer can be obtained from
285 * LIST_FIRST(&bp->bio_to->geom->consumer) as well,
286 * if there is only one in our geom.
288 g_io_request(cbp, sc->ex_consumer);
293 .Xr DECLARE_GEOM_CLASS 9 ,
301 .Xr g_provider_by_name 9 ,
305 This manual page was written by
306 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org .