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_alloc_bio(void);

     struct bio *
     g_clone_bio(struct bio *bp);

     struct bio *
     g_duplicate_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
                                 supports.  Technologies like flash adaptation layers can arrange
                                 to erase the relevant blocks before they will become reassigned
                                 and cryptographic devices may want to fill random bits into the
                                 range to reduce the amount of data available for attack.

                    BIO_GETATTR  Inspect and manipulate out-of-band attributes on a particular
                                 provider or path.  Attributes are named by ascii strings and are
                                 stored in the bio_attribute field.

                    BIO_FLUSH    Tells underlying providers to flush their write caches.

     bio_flags      Available flags:

                    BIO_ERROR  Request failed (error value 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 completed 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 structure.

     g_alloc_bio() - same as g_new_bio(), but always succeeds (allocates bio with the M_WAITOK
     malloc flag).

     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.

     g_duplicate_bio() - same as g_clone_bio(), but always succeeds (allocates bio with the
     M_WAITOK malloc flag).

     The g_destroy_bio() function deallocates and destroys the given bio structure.

     The g_print_bio() function prints information about the given 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 consumer 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(bp);
                   printf("\n");

                   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 'done' function. */

                   /* 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>.