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