g_bio(9)
NAME
- g_new_bio, g_clone_bio, g_destroy_bio, g_print_bio - GEOM
- bio controlling
functions
SYNOPSIS
#include <sys/bio.h>
#include <geom/geom.h>
struct bio *
g_new_bio(void);
struct bio *
g_clone_bio(struct bio *bp);
void
g_destroy_bio(struct bio *bp);
void
g_print_bio(struct bio *bp);
DESCRIPTION
- A struct bio is used by GEOM to describe I/O requests, its
- most important
fields are described below:
- bio_cmd I/O request command. There are four I/O
- requests
- available in GEOM:
- BIO_READ A read request.
- BIO_WRITE A write request.
- BIO_DELETE Indicates that a certain
- range of
data is no longer used
and that it
can be erased or freed
as the underlying technology sup
ports. Technologies like flash adapta
tion layers can
arrange to erase the
relevant blocks
before they will become
reassigned
and cryptographic de
vices may want to
fill random bits into
the range to
reduce the amount of da
ta available
for attack.
- BIO_GETATTR Inspect and manipulate
- out-of-band
- attributes on a particu
- lar provider
or path. Attributes are
- named by
ascii strings and are
- stored in the
bio_attribute field.
- bio_flags Available flags:
BIO_ERROR Request failed (error val- ue is stored
in bio_error field).
- BIO_DONE Request finished.
- bio_cflags Private use by the consumer.
- bio_pflags Private use by the provider.
- bio_offset Offset into provider.
- bio_data Pointer to data buffer.
- bio_error Error value when BIO_ERROR is set.
- bio_done Pointer to function which will be called
- when the
- request is finished.
- bio_driver1 Private use by the provider.
- bio_driver2 Private use by the provider.
- bio_caller1 Private use by the consumer.
- bio_caller2 Private use by the consumer.
- bio_attribute Attribute string for BIO_GETATTR request.
- bio_from Consumer to use for request (attached to
- provider
- stored in bio_to field) (typically read
- only for a
class).
- bio_to Destination provider (typically read-only
- for a
- class).
- bio_length Request length in bytes.
- bio_completed Number of bytes completed, but they may
- not be com
- pleted from the front of the request.
- bio_children Number of bio clones (typically read-only
- for a
- class).
- bio_inbed Number of finished bio clones.
- bio_parent Pointer to parent bio.
- The g_new_bio() function allocates a new, empty bio struc
- ture.
- The g_clone_bio() function allocates a new bio structure and
- copies the
following fields from the bio given as an argument to clone:
- bio_cmd,
bio_length, bio_offset, bio_data, bio_attribute. The field
- bio_parent in
the clone points to the passed bio and the field
- bio_children in the
passed bio is incremented.
- 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:
- 1. Clone the received struct bio.
2. Modify the clone.
3. Schedule the clone on its own consumer.
- The g_destroy_bio() function deallocates and destroys the
- given bio
structure.
- The g_print_bio() function prints information about the giv
- en bio structure (for debugging purposes).
RETURN VALUES
- The g_new_bio() and g_clone_bio() functions return a pointer
- to the allocated bio, or NULL if an error occurred.
EXAMPLES
- Implementation of ``NULL-transformation'', meaning that an
- I/O request is
cloned and scheduled down without any modifications. Let us
- assume that
field ex_consumer in structure example_softc contains a con
- sumer attached
to the provider we want to operate on.
void
example_start(struct bio *bp)
{
struct example_softc *sc;
struct bio *cbp;- printf("Request received: ");
g_print_bio();
printf("0);
- 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
- /* 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);
- }
SEE ALSO
- geom(4), DECLARE_GEOM_CLASS(9), g_access(9), g_attach(9),
- g_consumer(9),
g_data(9), g_event(9), g_geom(9), g_provider(9),
- g_provider_by_name(9),
g_wither_geom(9)
AUTHORS
- This manual page was written by Pawel Jakub Dawidek
- <pjd@FreeBSD.org>.
- BSD January 16, 2004