g_alloc_bio (9)
Leading comments
Copyright (c) 2004-2006 Pawel Jakub Dawidek <pjd@FreeBSD.org> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the...
NAME
g_new_bio g_clone_bio g_destroy_bio g_print_bio g_reset_bio - GEOM bio controlling functionsSYNOPSIS
In sys/bio.h In geom/geom.h Ft struct bio * Fn g_new_bio void Ft struct bio * Fn g_alloc_bio void Ft struct bio * Fn g_clone_bio struct bio *bp Ft struct bio * Fn g_duplicate_bio struct bio *bp Ft void Fn g_destroy_bio struct bio *bp Ft void Fn g_print_bio struct bio *bp Ft void Fn g_reset_bio struct bio *bpDESCRIPTION
A Vt 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 Vt bio clones (typically read-only for a class).
- bio_inbed
- Number of finished Vt bio clones.
- bio_parent
- Pointer to parent Vt bio .
The Fn g_new_bio function allocates a new, empty Vt bio structure.
Fn g_alloc_bio - same as Fn g_new_bio , but always succeeds (allocates bio with the M_WAITOK malloc flag).
The Fn g_clone_bio function allocates a new Vt bio structure and copies the following fields from the Vt 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 Vt bio and the field bio_children in the passed Vt 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:
- Clone the received Vt struct bio .
- Modify the clone.
- Schedule the clone on its own consumer.
Fn g_duplicate_bio - same as Fn g_clone_bio , but always succeeds (allocates bio with the M_WAITOK malloc flag).
The Fn g_destroy_bio function deallocates and destroys the given Vt bio structure.
The Fn g_print_bio function prints information about the given Vt bio structure (for debugging purposes).
The Fn g_reset_bio function resets the given Vt bio structure back to its initial state. Fn g_reset_bio preserves internal data structures, while setting all user visible fields to their initial values. When reusing a Vt bio obtained from Fn g_new_bio , Fn g_alloc_bio , Fn g_clone_bio , or Fn g_duplicate_bio for multiple transactions, Fn g_reset_bio must be called between the transactions in lieu of Fn bzero . While not strictly required for a Vt bio structure created by other means, Fn g_reset_bio should be used to initialize it and between transactions.
RETURN VALUES
The Fn g_new_bio and Fn g_clone_bio functions return a pointer to the allocated Vt 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 Vt 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->consumer) as well,
* if there is only one in our geom.
*/
g_io_request(cbp, sc->ex_consumer);
}