2 .\" Copyright (c) 2004 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.
35 .Nd "GEOM bio controlling functions"
42 .Fn g_clone_bio "struct bio *bp"
44 .Fn g_destroy_bio "struct bio *bp"
46 .Fn g_print_bio "struct bio *bp"
50 is used by GEOM to describe I/O requests, its
51 most important fields are described below:
52 .Bl -tag -width ".Va bio_attribute"
55 There are four I/O requests available in GEOM:
56 .Bl -tag -width ".Dv BIO_GETATTR"
62 Indicates that a certain range of data is no longer used and that
63 it can be erased or freed as the underlying technology supports.
64 Technologies like flash adaptation layers can arrange to erase the relevant
65 blocks before they will become reassigned and cryptographic devices may
66 want to fill random bits into the range to reduce the amount of data
69 Inspect and manipulate out-of-band
70 attributes on a particular provider or path.
71 Attributes are named by ascii strings and are stored in the
77 .Bl -tag -width ".Dv BIO_ERROR"
79 Request failed (error value is stored in
86 Private use by the consumer.
88 Private use by the provider.
92 Pointer to data buffer.
98 Pointer to function which will be called when the request is finished.
100 Private use by the provider.
102 Private use by the provider.
104 Private use by the consumer.
106 Private use by the consumer.
112 Consumer to use for request (attached to provider stored in
114 field) (typically read-only for a class).
116 Destination provider (typically read-only for a class).
118 Request length in bytes.
120 Number of bytes completed, but they may not be completed from
121 the front of the request.
125 clones (typically read-only for a class).
137 function allocates a new, empty
143 function allocates a new
145 structure and copies the following fields from the
147 given as an argument to clone:
155 in the clone points to the passed
163 This function should be used for every request which enters through
164 the provider of a particular geom and needs to be scheduled down.
174 Schedule the clone on its own consumer.
179 function deallocates and destroys the given
185 function prints information about the given
187 structure (for debugging purposes).
193 functions return a pointer to the allocated
197 if an error occurred.
200 .Dq Dv NULL Ns -transformation ,
201 meaning that an I/O request is cloned and scheduled down without any
203 Let us assume that field
207 contains a consumer attached to the provider we want to operate on.
208 .Bd -literal -offset indent
210 example_start(struct bio *bp)
212 struct example_softc *sc;
215 printf("Request received: ");
219 sc = bp->bio_to->geom->softc;
221 g_io_deliver(bp, ENXIO);
225 /* Let's clone our bio request. */
226 cbp = g_clone_bio(bp);
228 g_io_deliver(bp, ENOMEM);
231 cbp->bio_done = g_std_done; /* Standard 'done' function. */
233 /* Ok, schedule it down. */
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.
239 g_io_request(cbp, sc->ex_consumer);
244 .Xr DECLARE_GEOM_CLASS 9 ,
252 .Xr g_provider_by_name 9 ,
256 This manual page was written by
257 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .