xref: /freebsd/share/man/man9/g_bio.9 (revision 0bf48626aaa33768078f5872b922b1487b3a9296)
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 August 7, 2019
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_format_bio ,
35.Nm g_print_bio ,
36.Nm g_reset_bio
37.Nd "GEOM bio controlling functions"
38.Sh SYNOPSIS
39.In sys/bio.h
40.In geom/geom.h
41.Ft "struct bio *"
42.Fn g_new_bio void
43.Ft "struct bio *"
44.Fn g_alloc_bio void
45.Ft "struct bio *"
46.Fn g_clone_bio "struct bio *bp"
47.Ft "struct bio *"
48.Fn g_duplicate_bio "struct bio *bp"
49.Ft void
50.Fn g_destroy_bio "struct bio *bp"
51.Ft void
52.Fn g_format_bio "struct sbuf *sb" "const struct bio *bp"
53.Ft void
54.Fo g_print_bio
55.Fa "struct sbuf *sb" "const char *prefix" "const struct bio *bp"
56.Fa "const char *fmtsuffix" ...
57.Fc
58.Ft void
59.Fn g_reset_bio "struct bio *bp"
60.Sh DESCRIPTION
61A
62.Vt "struct bio"
63is used by GEOM to describe I/O requests, its
64most important fields are described below:
65.Bl -tag -width ".Va bio_attribute"
66.It Va bio_cmd
67I/O request command.
68There are five I/O requests available in GEOM:
69.Bl -tag -width ".Dv BIO_GETATTR"
70.It Dv BIO_READ
71A read request.
72.It Dv BIO_WRITE
73A write request.
74.It Dv BIO_DELETE
75Indicates that a certain range of data is no longer used and that
76it can be erased or freed as the underlying technology supports.
77Technologies like flash adaptation layers can arrange to erase the relevant
78blocks before they will become reassigned and cryptographic devices may
79want to fill random bits into the range to reduce the amount of data
80available for attack.
81.It Dv BIO_GETATTR
82Inspect and manipulate out-of-band
83attributes on a particular provider or path.
84Attributes are named by ascii strings and are stored in the
85.Va bio_attribute
86field.
87.It Dv BIO_FLUSH
88Tells underlying providers to flush their write caches.
89.El
90.It Va bio_flags
91Available flags:
92.Bl -tag -width ".Dv BIO_ERROR"
93.It Dv BIO_ERROR
94Request failed (error value is stored in
95.Va bio_error
96field).
97.It Dv BIO_DONE
98Request finished.
99.El
100.It Va bio_cflags
101Private use by the consumer.
102.It Va bio_pflags
103Private use by the provider.
104.It Va bio_offset
105Offset into provider.
106.It Va bio_data
107Pointer to data buffer.
108.It Va bio_error
109Error value when
110.Dv BIO_ERROR
111is set.
112.It Va bio_done
113Pointer to function which will be called when the request is finished.
114.It Va bio_driver1
115Private use by the provider.
116.It Va bio_driver2
117Private use by the provider.
118.It Va bio_caller1
119Private use by the consumer.
120.It Va bio_caller2
121Private use by the consumer.
122.It Va bio_attribute
123Attribute string for
124.Dv BIO_GETATTR
125request.
126.It Va bio_from
127Consumer to use for request (attached to provider stored in
128.Va bio_to
129field) (typically read-only for a class).
130.It Va bio_to
131Destination provider (typically read-only for a class).
132.It Va bio_length
133Request length in bytes.
134.It Va bio_completed
135Number of bytes completed, but they may not be completed from
136the front of the request.
137.It Va bio_children
138Number of
139.Vt bio
140clones (typically read-only for a class).
141.It Va bio_inbed
142Number of finished
143.Vt bio
144clones.
145.It Va bio_parent
146Pointer to parent
147.Vt bio .
148.El
149.Pp
150The
151.Fn g_new_bio
152function allocates a new, empty
153.Vt bio
154structure.
155.Pp
156.Fn g_alloc_bio
157- same as
158.Fn g_new_bio ,
159but always succeeds (allocates bio with the
160.Dv M_WAITOK
161malloc flag).
162.Pp
163The
164.Fn g_clone_bio
165function allocates a new
166.Vt bio
167structure and copies the following fields from the
168.Vt bio
169given as an argument to clone:
170.Va bio_cmd ,
171.Va bio_length ,
172.Va bio_offset ,
173.Va bio_data ,
174.Va bio_attribute .
175The field
176.Va bio_parent
177in the clone points to the passed
178.Vt bio
179and the field
180.Va bio_children
181in the passed
182.Vt bio
183is incremented.
184.Pp
185This function should be used for every request which enters through
186the provider of a particular geom and needs to be scheduled down.
187Proper order is:
188.Pp
189.Bl -enum -compact
190.It
191Clone the received
192.Vt "struct bio" .
193.It
194Modify the clone.
195.It
196Schedule the clone on its own consumer.
197.El
198.Pp
199.Fn g_duplicate_bio
200- same as
201.Fn g_clone_bio ,
202but always succeeds (allocates bio with the
203.Dv M_WAITOK
204malloc flag).
205.Pp
206The
207.Fn g_destroy_bio
208function deallocates and destroys the given
209.Vt bio
210structure.
211.Pp
212The
213.Fn g_format_bio
214function prints information about the given
215.Vt bio
216structure into the provided
217.Vt sbuf .
218.Pp
219The
220.Fn g_print_bio
221function is a convenience wrapper around
222.Fn g_format_bio
223that can be used for debugging purposes.
224It prints a provided
225.Fa prefix
226string, followed by the formatted
227.Vt bio ,
228followed by a
229.Fa fmtsuffix
230in the style of
231.Xr 9 printf .
232Any of the prefix or suffix strings may be the empty string.
233.Fn g_print_bio
234always prints a newline character at the end of the line.
235.Pp
236The
237.Fn g_reset_bio
238function resets the given
239.Vt bio
240structure back to its initial state.
241.Fn g_reset_bio
242preserves internal data structures, while setting all
243user visible fields to their initial values.
244When reusing a
245.Vt bio
246obtained from
247.Fn g_new_bio ,
248.Fn g_alloc_bio ,
249.Fn g_clone_bio ,
250or
251.Fn g_duplicate_bio
252for multiple transactions,
253.Fn g_reset_bio
254must be called between the transactions in lieu of
255.Fn bzero .
256While not strictly required for a
257.Vt bio
258structure created by other means,
259.Fn g_reset_bio
260should be used to initialize it and between transactions.
261.Sh RETURN VALUES
262The
263.Fn g_new_bio
264and
265.Fn g_clone_bio
266functions return a pointer to the allocated
267.Vt bio ,
268or
269.Dv NULL
270if an error occurred.
271.Sh EXAMPLES
272Implementation of
273.Dq Dv NULL Ns -transformation ,
274meaning that an I/O request is cloned and scheduled down without any
275modifications.
276Let us assume that field
277.Va ex_consumer
278in structure
279.Vt example_softc
280contains a consumer attached to the provider we want to operate on.
281.Bd -literal -offset indent
282void
283example_start(struct bio *bp)
284{
285	struct example_softc *sc;
286	struct bio *cbp;
287
288	g_print_bio("Request received: ", bp, "");
289
290	sc = bp->bio_to->geom->softc;
291	if (sc == NULL) {
292		g_io_deliver(bp, ENXIO);
293		return;
294	}
295
296	/* Let's clone our bio request. */
297	cbp = g_clone_bio(bp);
298	if (cbp == NULL) {
299		g_io_deliver(bp, ENOMEM);
300		return;
301	}
302	cbp->bio_done = g_std_done;	/* Standard 'done' function. */
303
304	/* Ok, schedule it down. */
305	/*
306	 * The consumer can be obtained from
307	 * LIST_FIRST(&bp->bio_to->geom->consumer) as well,
308	 * if there is only one in our geom.
309	 */
310	g_io_request(cbp, sc->ex_consumer);
311}
312.Ed
313.Sh SEE ALSO
314.Xr geom 4 ,
315.Xr DECLARE_GEOM_CLASS 9 ,
316.Xr g_access 9 ,
317.Xr g_attach 9 ,
318.Xr g_consumer 9 ,
319.Xr g_data 9 ,
320.Xr g_event 9 ,
321.Xr g_geom 9 ,
322.Xr g_provider 9 ,
323.Xr g_provider_by_name 9 ,
324.Xr g_wither_geom 9
325.Sh AUTHORS
326.An -nosplit
327This manual page was written by
328.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org .
329