Added first part of GEOM kernel API manuals pages.
Documented function and macros are: - DECLARE_GEOM_CLASS(), - g_attach(), - g_detach(), - g_new_bio(), - g_clone_bio(), - g_destroy_bio(), - g_new_consumer(), - g_destroy_consumer(), - g_read_data(), - g_write_data(), - g_post_event(), - g_waitfor_event(), - g_cancel_event(), - g_new_geomf(), - g_destroy_geom(), - g_new_providerf(), - g_destroy_provider(), - g_error_provider(), - g_provider_by_name(), - g_wither_geom(). and more to come. I want to thanks following people for help with those documents: Slawek Zak <zaks@prioris.mini.pw.edu.pl> Simon L. Nielsen <simon@FreeBSD.org> Pieter de Boer <g.p.de.boer@st.hanze.nl> and of course Poul-Henning Kamp <phk@FreeBSD.org> Reviewed by: phk, scottl Approved by: phk, scottl (mentor)
This commit is contained in:
parent
45d370ee8b
commit
f827ccb9a3
175
share/man/man9/DECLARE_GEOM_CLASS.9
Normal file
175
share/man/man9/DECLARE_GEOM_CLASS.9
Normal file
@ -0,0 +1,175 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt DECLARE_GEOM_CLASS 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm DECLARE_GEOM_CLASS
|
||||
.Nd "GEOM class declaration macro"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Fn DECLARE_GEOM_CLASS "class" "mod_name"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn DECLARE_GEOM_CLASS
|
||||
macro registers a GEOM class in GEOM.
|
||||
A GEOM class itself implements one particular kind of transformation.
|
||||
Typical examples are: MBR disk partition, BSD disklabel and RAID5 classes.
|
||||
.Fn DECLARE_GEOM_CLASS
|
||||
can be used both for compiled in and loaded as
|
||||
.Xr kld 4
|
||||
modules GEOM classes and it is the only official way for class registration.
|
||||
.Pp
|
||||
The arguments to
|
||||
.Fn DECLARE_GEOM_CLASS
|
||||
are:
|
||||
.Bl -inset -offset indent
|
||||
.It Em class
|
||||
is the
|
||||
.Vt g_class
|
||||
structure which describes a GEOM class.
|
||||
.It Em mod_name
|
||||
is a kernel module name (not a class name!).
|
||||
.El
|
||||
.Pp
|
||||
Structure
|
||||
.Vt g_class
|
||||
contains data describing the class.
|
||||
They are:
|
||||
.Bl -inset -offset indent
|
||||
.It Vt "const char *" Va name
|
||||
Class name.
|
||||
.It Vt "g_taste_t *" Va taste
|
||||
Pointer to function used for taste event handling.
|
||||
If it is
|
||||
.No non- Ns Dv NULL
|
||||
it is called in three situations:
|
||||
.Bl -dash -offset indent -compact
|
||||
.It
|
||||
On class activation, all existing providers are offered for tasting.
|
||||
.It
|
||||
When new provider is created it is offered for tasting.
|
||||
.It
|
||||
After last write access to a provider is closed it is offered for retasting
|
||||
(on first write open event
|
||||
.Dq spoil
|
||||
was sent).
|
||||
.El
|
||||
.It Vt "g_config_t *" Va config
|
||||
This field is not used anymore, its functionality was replaced by the
|
||||
.Va ctlreq
|
||||
field.
|
||||
.It Vt "g_ctl_req_t *" Va ctlreq
|
||||
Pointer to function used for handling events from userland applications.
|
||||
.It Vt "g_init_t *" Va init
|
||||
Pointer to function which is called right after class registration.
|
||||
.It Vt "g_fini_t *" Va fini
|
||||
Pointer to function which is called right before class deregistration.
|
||||
.It Vt "g_ctl_destroy_geom_t *" Va destroy_geom
|
||||
Pointer to a function which is called for every geom on class unload.
|
||||
If this field is not set, the class can not be unloaded.
|
||||
.El
|
||||
.Pp
|
||||
Only field
|
||||
.Fa name
|
||||
is required, the rest is optional.
|
||||
.Pp
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
In the
|
||||
.Vt g_class
|
||||
initialization one must use C99 initialization (just like in the example below).
|
||||
.Pp
|
||||
.Sh EXAMPLES
|
||||
Example class declaration.
|
||||
.Bd -literal -offset indent
|
||||
static struct geom *
|
||||
g_example_taste(struct g_class *mp, struct g_provider *pp,
|
||||
int flags __unused)
|
||||
{
|
||||
g_topology_assert();
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static void
|
||||
g_example_ctlreq(struct gctl_req *req, struct g_class *cp,
|
||||
char const *verb)
|
||||
{
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static int
|
||||
g_example_destroy_geom(struct gctl_req *req, struct g_class *cp,
|
||||
struct g_geom *gp)
|
||||
{
|
||||
|
||||
g_topology_assert();
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static void
|
||||
g_example_init(struct g_class *mp)
|
||||
{
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static void
|
||||
g_example_fini(struct g_class *mp)
|
||||
{
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
struct g_class example_class = {
|
||||
.name = "EXAMPLE",
|
||||
.taste = g_example_taste,
|
||||
.ctlreq = g_example_ctlreq,
|
||||
.init = g_example_init,
|
||||
.fini = g_example_fini,
|
||||
.destroy_geom = g_example_destroy_geom
|
||||
};
|
||||
|
||||
DECLARE_GEOM_CLASS(example_class, g_example);
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
138
share/man/man9/g_attach.9
Normal file
138
share/man/man9/g_attach.9
Normal file
@ -0,0 +1,138 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_attach 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_attach ,
|
||||
.Nm g_detach
|
||||
.Nd "attach/detach consumer to/from provider"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft int
|
||||
.Fn g_attach "struct g_consumer *cp" "struct g_provider *pp"
|
||||
.Ft void
|
||||
.Fn g_detach "struct g_consumer *cp"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn g_attach
|
||||
function attaches given consumer to given provider.
|
||||
For real provider access (ie. I/O operations), one still need to call the
|
||||
.Fn g_access_rel
|
||||
function on consumer to gain access to attached provider.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_detach
|
||||
function detaches the given consumer from the corresponding provider.
|
||||
This function is used when we do not want to communicate with the
|
||||
provider anymore.
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
.Fn g_attach :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The consumer can not be attached already.
|
||||
.It
|
||||
The operation should not create a topology loop.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Pp
|
||||
.Fn g_detach :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The consumer has to be attached.
|
||||
.It
|
||||
The access count has to be 0.
|
||||
.It
|
||||
There must be no active requests.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_attach
|
||||
returns the value 0 if successful; otherwise an error code is returned.
|
||||
.Sh ERRORS
|
||||
Possible errors:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er ELOOP
|
||||
The operation creates a topology loop.
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
Create consumer, attach it to given provider, gain read access and clean up.
|
||||
.Bd -literal -offset indent
|
||||
void
|
||||
some_function(struct g_geom *mygeom, struct g_provider *pp)
|
||||
{
|
||||
struct g_consumer *cp;
|
||||
|
||||
g_topology_assert();
|
||||
|
||||
/* Create new consumer on 'mygeom' geom. */
|
||||
cp = g_new_consumer(mygeom);
|
||||
if (cp == NULL)
|
||||
return;
|
||||
/* Attach newly created consumer to given provider. */
|
||||
if (g_attach(cp, pp) != 0) {
|
||||
g_destroy_consumer(cp);
|
||||
return;
|
||||
}
|
||||
/* Open provider for reading through our consumer. */
|
||||
if (g_access_rel(cp, 1, 0, 0) != 0) {
|
||||
g_detach(cp);
|
||||
g_destroy_consumer(cp);
|
||||
return;
|
||||
}
|
||||
|
||||
g_topology_unlock();
|
||||
/*
|
||||
* Read data from provider.
|
||||
*/
|
||||
g_topology_lock();
|
||||
|
||||
/* Disconnect from provider (release access count). */
|
||||
g_access_rel(cp, -1, 0, 0);
|
||||
/* Detach from provider. */
|
||||
g_detach(cp);
|
||||
/* Destroy consumer. */
|
||||
g_destroy_consumer(cp);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
224
share/man/man9/g_bio.9
Normal file
224
share/man/man9/g_bio.9
Normal file
@ -0,0 +1,224 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_bio 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_new_bio ,
|
||||
.Nm g_clone_bio ,
|
||||
.Nm g_destroy_bio
|
||||
.Nd "bio controlling functions"
|
||||
.Sh SYNOPSIS
|
||||
.In sys/bio.h
|
||||
.In geom/geom.h
|
||||
.Ft "struct bio *"
|
||||
.Fn g_new_bio void
|
||||
.Ft "struct bio *"
|
||||
.Fn g_clone_bio "struct bio *bp"
|
||||
.Ft void
|
||||
.Fn g_destroy_bio "struct bio *bp"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fa bio
|
||||
structure is used by GEOM to describe I/O requests.
|
||||
Most important fields of
|
||||
.Fa struct bio
|
||||
are described below:
|
||||
.Bl -tag -width ".Va bio_attribute"
|
||||
.It Va bio_cmd
|
||||
I/O request number.
|
||||
There are four I/O requests available in GEOM:
|
||||
.Bl -tag -width BIO_GETATTR
|
||||
.It Dv BIO_READ
|
||||
Self explanatory.
|
||||
.It Dv BIO_WRITE
|
||||
Self explanatory.
|
||||
.It Dv BIO_DELETE
|
||||
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.
|
||||
.It Dv BIO_GETATTR
|
||||
Get attribute supports inspection and manipulation of out\-of\-band
|
||||
attributes on a particular provider or path.
|
||||
Attributes are named by ascii strings and are stored in the
|
||||
.Va bio_attribute
|
||||
field.
|
||||
.El
|
||||
.It Va bio_offset
|
||||
Offset into provider.
|
||||
.It Va bio_data
|
||||
Pointer to data buffer.
|
||||
.It Va bio_flags
|
||||
Available flags:
|
||||
.Bl -tag -width BIO_GETATTR
|
||||
.It Dv BIO_ERROR
|
||||
Request failed (error value is stored in
|
||||
.Va bio_error )
|
||||
field.
|
||||
.It Dv BIO_DONE
|
||||
Request finished.
|
||||
.It Dv BIO_FLAG1
|
||||
Avaliable for private use.
|
||||
.It Dv BIO_FLAG2
|
||||
Avaliable for private use.
|
||||
.El
|
||||
.It Va bio_error
|
||||
Error value when BIO_ERROR is set.
|
||||
.It Va bio_done
|
||||
Pointer to function which will be called on request finish.
|
||||
.It Va bio_driver1
|
||||
Private use by the callee (ie: the provider).
|
||||
.It Va bio_driver2
|
||||
Private use by the callee (ie: the provider).
|
||||
.It Va bio_caller1
|
||||
Private use by the caller (ie: the consumer).
|
||||
.It Va bio_caller2
|
||||
Private use by the caller (ie: the consumer).
|
||||
.It Va bio_attribute
|
||||
Attribute string for BIO_GETATTR request.
|
||||
.It Va bio_from
|
||||
Consumer to use for request (attached to provider stored in
|
||||
.Va bio_to
|
||||
field) (typically read\-only for a class).
|
||||
.It Va bio_to
|
||||
Destination provider (typically read\-only for a class).
|
||||
.It Va bio_length
|
||||
Request length in bytes.
|
||||
.It Va bio_completed
|
||||
Number of bytes completed, but they may not be completed from
|
||||
the front of the request.
|
||||
.It Va bio_children
|
||||
Number of bio clones (typically read\-only for a class).
|
||||
.It Va bio_inbed
|
||||
Number of finished bio clones.
|
||||
.It Va bio_parent
|
||||
Pointer to parent bio.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn g_new_bio
|
||||
function allocates a new, empty
|
||||
.Vt bio
|
||||
structure.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_clone_bio
|
||||
function allocates a new
|
||||
.Vt bio
|
||||
structure and copies those fields from the
|
||||
.Vt bio
|
||||
structure given as an argument to clone:
|
||||
.Va bio_cmd ,
|
||||
.Va bio_length ,
|
||||
.Va bio_offset ,
|
||||
.Va bio_data ,
|
||||
.Va bio_attribute .
|
||||
The field
|
||||
.Va bio_parent
|
||||
in clone is set to source
|
||||
.Vt bio
|
||||
and the field
|
||||
.Va bio_children
|
||||
in parent is increased.
|
||||
.Pp
|
||||
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:
|
||||
.Pp
|
||||
.Bl -enum -compact
|
||||
.It
|
||||
Clone
|
||||
.Vt "struct bio" .
|
||||
.It
|
||||
Modify the clone.
|
||||
.It
|
||||
Schedule the clone on its own consumer.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn g_destroy_bio
|
||||
function kills the given
|
||||
.Vt bio
|
||||
structure.
|
||||
.Sh EXAMPLES
|
||||
Implementation of
|
||||
.Dq Dv NULL Ns \-transformation ,
|
||||
meaning that an I/O request is cloned and scheduled down without any
|
||||
modifications.
|
||||
Let's assume that field
|
||||
.Va ex_consumer
|
||||
in structure
|
||||
.Vt example_softc
|
||||
contains a consumer attached to the provider we want to operate on.
|
||||
.Bd -literal -offset indent
|
||||
void
|
||||
example_start(struct bio *bp)
|
||||
{
|
||||
struct example_softc *sc;
|
||||
struct bio *cbp;
|
||||
|
||||
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);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
141
share/man/man9/g_consumer.9
Normal file
141
share/man/man9/g_consumer.9
Normal file
@ -0,0 +1,141 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_consumer 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_new_consumer ,
|
||||
.Nm g_destroy_consumer
|
||||
.Nd "GEOM consumers management"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft "struct g_consumer *"
|
||||
.Fn g_new_consumer "struct g_geom *gp"
|
||||
.Ft void
|
||||
.Fn g_destroy_consumer "struct g_consumer *cp"
|
||||
.Sh DESCRIPTION
|
||||
The GEOM consumer is the backdoor through which a geom connects to
|
||||
another GEOM provider and through which I/O requests are sent.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_new_consumer
|
||||
function creates a new consumer releated to geom
|
||||
.Fa gp .
|
||||
The consumer is unusable prior attaching to a provider and gaining access
|
||||
to it.
|
||||
To serve its purpose, the consumer has to be attached to a provider
|
||||
with the
|
||||
.Xr g_attach 9
|
||||
function.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_destroy_consumer
|
||||
function destroys given consumer and cancels all related pending events.
|
||||
This function is the last stage of killing an unwanted consumer.
|
||||
.Pp
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
.Fn g_new_consumer :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The geom related to the created consumer must have the
|
||||
.Fa start
|
||||
and
|
||||
.Fa access
|
||||
fields defined.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Pp
|
||||
.Fn g_destroy_consumer :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The consumer can not be attached.
|
||||
.It
|
||||
The access count has to be 0.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_new_consumer
|
||||
returns a pointer to the newly created consumer or
|
||||
.Dv NULL
|
||||
if an error occured.
|
||||
.Sh EXAMPLES
|
||||
Create consumer, attach it to given provider, gain read access and clean up.
|
||||
.Bd -literal -offset indent
|
||||
void
|
||||
some_function(struct g_geom *mygeom, struct g_provider *pp)
|
||||
{
|
||||
struct g_consumer *cp;
|
||||
|
||||
g_topology_assert();
|
||||
|
||||
/* Create new consumer on 'mygeom' geom. */
|
||||
cp = g_new_consumer(mygeom);
|
||||
if (cp == NULL)
|
||||
return;
|
||||
/* Attach newly created consumer to given provider. */
|
||||
if (g_attach(cp, pp) != 0) {
|
||||
g_destroy_consumer(cp);
|
||||
return;
|
||||
}
|
||||
/* Open provider for reading through our consumer. */
|
||||
if (g_access_rel(cp, 1, 0, 0) != 0) {
|
||||
g_detach(cp);
|
||||
g_destroy_consumer(cp);
|
||||
return;
|
||||
}
|
||||
|
||||
g_topology_unlock();
|
||||
/*
|
||||
* Read data from provider.
|
||||
*/
|
||||
g_topology_lock();
|
||||
|
||||
/* Disconnect from provider (release access count). */
|
||||
g_access_rel(cp, -1, 0, 0);
|
||||
/* Detach from provider. */
|
||||
g_detach(cp);
|
||||
/* Destroy consumer. */
|
||||
g_destroy_consumer(cp);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
111
share/man/man9/g_data.9
Normal file
111
share/man/man9/g_data.9
Normal file
@ -0,0 +1,111 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_data 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_read_data ,
|
||||
.Nm g_write_data
|
||||
.Nd "read/write data through consumer"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft "void *"
|
||||
.Fn g_read_data "struct g_consumer *cp" "off_t offset" "off_t length" "int *error"
|
||||
.Ft int
|
||||
.Fn g_write_data "struct g_consumer *cp" "off_t offset" "void *ptr" "off_t length"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn g_read_data
|
||||
reads
|
||||
.Fa length
|
||||
bytes of data from a provider through attached consumer
|
||||
.Fa cp
|
||||
starting at offset
|
||||
.Fa offset .
|
||||
Memory for data is allocated inside
|
||||
.Fn g_read_data
|
||||
with
|
||||
.Fn g_malloc ,
|
||||
and should therefor be freed by the caller with the
|
||||
.Fn g_free
|
||||
function after use.
|
||||
If the operation fails, an error value will be stored in the
|
||||
.Fa error
|
||||
argument if it is not
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
The
|
||||
.Fn g_write_data
|
||||
writes
|
||||
.Fa length
|
||||
bytes of data from address
|
||||
.Fa ptr
|
||||
starting at offset
|
||||
.Fa offset
|
||||
to a provider through the attached consumer
|
||||
.Fa cp .
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
Length of data should be a multiple of the sectorsize for the provider
|
||||
and less than or equal to
|
||||
.Dv DFLTPHYS
|
||||
.Dv ( DFLTPHYS is defined in
|
||||
.In sys/param.h ) .
|
||||
.Pp
|
||||
The topology lock must not be held.
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_read_data
|
||||
returns a pointer to the read data or
|
||||
.Dv NULL
|
||||
if an error occured.
|
||||
In that case an error value is stored in the
|
||||
.Fa error
|
||||
argument unsless it is
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
.Fn g_write_data
|
||||
returns the value 0 if successful; otherwise an error code is returned.
|
||||
.Sh ERRORS
|
||||
Possible errors:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EIO
|
||||
Can not read data.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
179
share/man/man9/g_event.9
Normal file
179
share/man/man9/g_event.9
Normal file
@ -0,0 +1,179 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_event 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_post_event ,
|
||||
.Nm g_waitfor_event ,
|
||||
.Nm g_cancel_event
|
||||
.Nd "events management"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft int
|
||||
.Fn g_post_event "g_event_t *func" "void *arg" "int flag" ...
|
||||
.Ft int
|
||||
.Fn g_waitfor_event "g_event_t *func" "void *arg" "int flag" ...
|
||||
.Ft void
|
||||
.Fn g_cancel_event "void *ref"
|
||||
.Sh DESCRIPTION
|
||||
The GEOM has its own event queue to inform classes about important things.
|
||||
The event queue can be also used by classes, mostly for running away
|
||||
from I/O path.
|
||||
Sleeping, heavy weight tasks, etc. are not permitted on I/O path and
|
||||
events are the cure to avoid such situations.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_post_event
|
||||
function tells GEOM to call function
|
||||
.Fa func
|
||||
with argument
|
||||
.Fa arg
|
||||
from the event queue.
|
||||
The
|
||||
.Fa flag
|
||||
argument is a flag for
|
||||
.Xr malloc 9
|
||||
that should be used by GEOM.
|
||||
Only the flags
|
||||
.Dv M_WAITOK
|
||||
or
|
||||
.Dv M_NOWAIT
|
||||
can be used.
|
||||
The rest of the arguments are used as references.
|
||||
An event can be canceled by using any of given references as an
|
||||
argument to the
|
||||
.Fn g_cancel_event
|
||||
function.
|
||||
The list of references has to end with a
|
||||
.Dv NULL
|
||||
value.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_waitfor_event
|
||||
function is a blocking version of the
|
||||
.Fn g_post_event
|
||||
function.
|
||||
It waits until the event is finished or canceled and then returns.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_cancel_event
|
||||
function cancels event(s) identified by
|
||||
.Fa ref .
|
||||
Cancellation is equivalent to calling the requested function
|
||||
with requested arguments and argument
|
||||
.Fa flag
|
||||
set to
|
||||
.Dv EV_CANCEL .
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
.Fn g_post_event :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The argument
|
||||
.Fa flag
|
||||
has to be
|
||||
.Dv M_WAITOK
|
||||
or
|
||||
.Dv M_NOWAIT .
|
||||
.It
|
||||
The list of references has to end with a
|
||||
.Dv NULL
|
||||
value.
|
||||
.El
|
||||
.Pp
|
||||
.Fn g_waitfor_event :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The argument
|
||||
.Fa flag
|
||||
has to be
|
||||
.Dv M_WAITOK
|
||||
or
|
||||
.Dv M_NOWAIT .
|
||||
.It
|
||||
The list of references has to end with a
|
||||
.Dv NULL
|
||||
value.
|
||||
.It
|
||||
The
|
||||
.Fn g_waitfor_event
|
||||
function can not be called from an event, since doing so would result
|
||||
in a deadlock.
|
||||
.El
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_post_event
|
||||
and
|
||||
.Fn g_waitfor_event
|
||||
returns the value 0 if successful; otherwise an error code is returned.
|
||||
.Sh ERRORS
|
||||
Possible errors for
|
||||
.Fn g_post_event
|
||||
function:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er ENOMEM
|
||||
There was insufficient memory.
|
||||
.El
|
||||
.Pp
|
||||
Possible errors for
|
||||
.Fn g_waitfor_event
|
||||
function:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EAGAIN
|
||||
The event was canceled.
|
||||
.It Bq Er ENOMEM
|
||||
There was insufficient memory.
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
Example of a function called from the event queue.
|
||||
.Bd -literal -offset indent
|
||||
void
|
||||
example_event(void *arg, int flag)
|
||||
{
|
||||
|
||||
if (flag == EV_CANCEL) {
|
||||
printf("Event with argument %p canceled.\\n", arg);
|
||||
return;
|
||||
}
|
||||
|
||||
printf("Event with argument %p called.\\n", arg);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
202
share/man/man9/g_geom.9
Normal file
202
share/man/man9/g_geom.9
Normal file
@ -0,0 +1,202 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_geom 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_new_geomf ,
|
||||
.Nm g_destroy_geom
|
||||
.Nd "geom management"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft "struct g_geom *"
|
||||
.Fn g_new_geomf "struct g_class *mp" "const char *fmt" ...
|
||||
.Ft void
|
||||
.Fn g_destroy_geom "struct g_geom *gp"
|
||||
.Sh DESCRIPTION
|
||||
The geom (do not confuse
|
||||
.Dq geom
|
||||
with
|
||||
.Dq GEOM )
|
||||
is an instance of a GEOM class.
|
||||
For example: in a typical i386 FreeBSD system, there will be one geom
|
||||
of class MBR for each disk.
|
||||
The geom's name is not really important, it is only used in the XML
|
||||
dump and for debugging purposes.
|
||||
There can be many geoms with the same name.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_new_geomf
|
||||
function creates a new geom, which will be an instance of the class
|
||||
.Fa mp .
|
||||
The geom name is created in a printf\-like way from the rest of the arguments.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_destroy_geom
|
||||
function destroys the given geom imediately and cancels all related pending
|
||||
events.
|
||||
.Pp
|
||||
Structure
|
||||
.Vt g_geom
|
||||
contains fields, that should be set by the caller after geom creation, but before
|
||||
creating any providers or consumers related to this geom (not all are required):
|
||||
.Bl -inset -offset indent
|
||||
.It Vt "g_start_t *" Va start
|
||||
Pointer to a function used for I/O processing.
|
||||
.It Vt "g_spoiled_t *" Va spoiled
|
||||
Pointer to a function used for consumers spoiling.
|
||||
.It Vt "g_dumpconf_t *" Va dumpconf
|
||||
Pointer to a function used for configuration in XML format dumping.
|
||||
.It Vt "g_access_t *" Va access
|
||||
Pointer to a function used for access control.
|
||||
.It Vt "g_orphan_t *" Va orphan
|
||||
Pointer to a function used to inform about orphaned consumer.
|
||||
.It Vt "g_ioctl_t *" Va ioctl
|
||||
Pointer to a function used for handling ioctl requests.
|
||||
.It Vt "void *" Va softc
|
||||
Field for private use.
|
||||
.El
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
If you intend to use providers in this geom you must set field
|
||||
.Va start
|
||||
of your geom.
|
||||
.Pp
|
||||
If you are planning to use consumers in your geom you must set fields
|
||||
.Va orphan
|
||||
and
|
||||
.Va access
|
||||
for it.
|
||||
.Pp
|
||||
.Fn g_new_geomf :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
Class
|
||||
.Fa mp
|
||||
must be valid (registered in GEOM).
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Pp
|
||||
.Fn g_destroy_geom :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The geom can not posses any providers.
|
||||
.It
|
||||
The geom can not posses any consumers.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_new_geomf
|
||||
returns a pointer to the newly created geom or
|
||||
.Dv NULL
|
||||
if an error occured.
|
||||
.Sh EXAMPLES
|
||||
Create an example geom.
|
||||
.Bd -literal -offset indent
|
||||
static struct geom *
|
||||
g_example_start(struct bio *bp)
|
||||
{
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static void
|
||||
g_example_orphan(struct g_consumer *cp)
|
||||
{
|
||||
|
||||
g_topology_assert();
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static void
|
||||
g_example_spoiled(struct g_consumer *cp)
|
||||
{
|
||||
|
||||
g_topology_assert();
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static void
|
||||
g_example_access(struct g_provider *pp, int dr, int dw, int de)
|
||||
{
|
||||
|
||||
[...]
|
||||
}
|
||||
|
||||
static struct g_geom *
|
||||
create_example_geom(struct g_class *myclass)
|
||||
{
|
||||
struct g_geom *gp;
|
||||
|
||||
g_topology_lock();
|
||||
gp = g_new_geomf(myclass, "example_geom");
|
||||
g_topology_unlock();
|
||||
if (gp != NULL) {
|
||||
gp->start = g_example_start;
|
||||
gp->orphan = g_example_orphan;
|
||||
gp->spoiled = g_example_spoiled;
|
||||
gp->access = g_example_access;
|
||||
gp->softc = NULL;
|
||||
}
|
||||
|
||||
return (gp);
|
||||
}
|
||||
|
||||
static int
|
||||
destroy_example_geom(struct g_geom *gp)
|
||||
{
|
||||
|
||||
g_topology_lock();
|
||||
if (!LIST_EMPTY(&gp->provider) ||
|
||||
!LIST_EMPTY(&gp->consumer)) {
|
||||
g_topology_unlock();
|
||||
return (EBUSY);
|
||||
}
|
||||
g_destroy_geom(gp);
|
||||
g_topology_unlock();
|
||||
|
||||
return (0);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
144
share/man/man9/g_provider.9
Normal file
144
share/man/man9/g_provider.9
Normal file
@ -0,0 +1,144 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_provider 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_new_providerf ,
|
||||
.Nm g_destroy_provider ,
|
||||
.Nm g_error_provider
|
||||
.Nd "GEOM providers management"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft "struct g_provider *"
|
||||
.Fn g_new_providerf "struct g_geom *gp" "const char *fmt" ...
|
||||
.Ft void
|
||||
.Fn g_destroy_provider "struct g_provider *pp"
|
||||
.Ft void
|
||||
.Fn g_error_provider "struct g_provider *pp" "int error"
|
||||
.Sh DESCRIPTION
|
||||
The GEOM provider is the front gate at which a geom offers service.
|
||||
A provider is
|
||||
.Dq a disk\-like thing which appears in Pa /dev
|
||||
\- a logical disk in other words.
|
||||
All providers have three main properties: name, sectorsize and size.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_new_providerf
|
||||
function creates a new provider and attaches it to geom
|
||||
.Fa gp .
|
||||
The provider name is created in a printf\-like way from the rest of
|
||||
the arguments.
|
||||
After creation, the provider is unusable, because
|
||||
.Fn g_new_providerf
|
||||
sets its error to
|
||||
.Er ENXIO .
|
||||
The function
|
||||
.Fn g_error_provider
|
||||
should be used to reset this error, but before it is called, two
|
||||
fields should be set in the provider structure:
|
||||
.Va mediasize
|
||||
and
|
||||
.Va sectorsize
|
||||
as well as other initialization things should be done first.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_destroy_provider
|
||||
function destroys the given provider, cancels all related pending events and
|
||||
removes corresponding devfs entry.
|
||||
.Pp
|
||||
The
|
||||
.Fn g_error_provider
|
||||
function is used to set a provider error value.
|
||||
If it set to a nonzero value, all I/O requests will be denied,
|
||||
increasing its access count will not be possible (error
|
||||
.Fa error
|
||||
will be returned).
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
.Fn g_new_provider :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
The provider name should be unique, but this is not enforced by GEOM.
|
||||
If the name is not unique, one will end up with two (or more) files
|
||||
with the same name, which is programmer error.
|
||||
.It
|
||||
The geom related to the created provider must have
|
||||
.Fa start
|
||||
field defined.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Pp
|
||||
.Fn g_destroy_provider :
|
||||
.Bl -item -offset indent
|
||||
.It
|
||||
No consumers have to be attached.
|
||||
.It
|
||||
The access count has to be 0.
|
||||
.It
|
||||
The topology lock has to be held.
|
||||
.El
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_new_providerf
|
||||
returns a pointer to the newly created provider or
|
||||
.Dv NULL
|
||||
if an error occured.
|
||||
.Sh EXAMPLES
|
||||
Create an example provider, set its parameters and make it usable.
|
||||
.Bd -literal -offset indent
|
||||
struct g_provider *
|
||||
create_example_provider(struct g_geom *gp)
|
||||
{
|
||||
struct g_provider *pp;
|
||||
|
||||
g_topology_lock();
|
||||
pp = g_new_providerf(gp, "example_provider");
|
||||
g_topology_unlock();
|
||||
if (pp != NULL) {
|
||||
pp->mediasize = 65536;
|
||||
pp->sectorsize = 512;
|
||||
g_error_provider(pp, 0);
|
||||
}
|
||||
|
||||
return (pp);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider_by_name 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
74
share/man/man9/g_provider_by_name.9
Normal file
74
share/man/man9/g_provider_by_name.9
Normal file
@ -0,0 +1,74 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_provider_by_name 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_provider_by_name
|
||||
.Nd "find provider with given name"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft "struct g_provider *"
|
||||
.Fn g_provider_by_name "const char *name"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn g_provider_by_name
|
||||
searches for a provider called
|
||||
.Fa name
|
||||
and returns the structure
|
||||
.Fa g_provider
|
||||
bound to it.
|
||||
Argument
|
||||
.Fa name
|
||||
should be a name, not a full path (ie.
|
||||
.Dq Pa da0 ,
|
||||
instead of
|
||||
.Dq Pa /dev/da0 ) .
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
The topology lock has to be held.
|
||||
.Sh RETURN VALUES
|
||||
.Fn g_provider_by_name
|
||||
returns a pointer to the provider called
|
||||
.Fa name
|
||||
or
|
||||
.Dv NULL
|
||||
if there is no such provider.
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_wither_geom 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
85
share/man/man9/g_wither_geom.9
Normal file
85
share/man/man9/g_wither_geom.9
Normal file
@ -0,0 +1,85 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 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
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 16, 2004
|
||||
.Dt g_wither_geom 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm g_wither_geom
|
||||
.Nd "destroy geom and releated providers and consumers when you get a chance"
|
||||
.Sh SYNOPSIS
|
||||
.In geom/geom.h
|
||||
.Ft void
|
||||
.Fn g_wither_geom "struct g_geom *gp" "int error"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn g_wither_geom
|
||||
function tells GEOM that geom
|
||||
.Fa gp
|
||||
is to be destroyed.
|
||||
GEOM sets an error for every provider related to the given geom (in
|
||||
orphan process) and waits for a chance to destroy the geom.
|
||||
If access count of any possessed consumer goes to 0, consumer will be
|
||||
detached and destroyed automatically.
|
||||
If last consumer attached to any possesed provider will be detached,
|
||||
provider will be destroyed.
|
||||
If there are no more providers nor consumers, the geom will be
|
||||
destroyed.
|
||||
.Pp
|
||||
This is an automatic
|
||||
.Dq garbage collect
|
||||
to avoid duplicated code in all classes.
|
||||
Before it is called, field
|
||||
.Va softc
|
||||
should be disposed off and set to
|
||||
.Dv NULL .
|
||||
Note that the
|
||||
.Fn g_wither_geom
|
||||
function gives no guarantee that geom will be immediately destroyed, mostly
|
||||
because access counts of corresponding consumers and providers may not be 0.
|
||||
That is why calling this function for every geom from given class is not enough
|
||||
to be sure that class can be unloaded.
|
||||
.Sh RESTRICTIONS/CONDITIONS
|
||||
The argument
|
||||
.Fa error
|
||||
must be nonzero.
|
||||
.Pp
|
||||
The topology lock has to be held.
|
||||
.Sh SEE ALSO
|
||||
.Xr DECLARE_GEOM_CLASS 9 ,
|
||||
.Xr geom 4 ,
|
||||
.Xr g_attach 9 ,
|
||||
.Xr g_bio 9 ,
|
||||
.Xr g_consumer 9 ,
|
||||
.Xr g_data 9 ,
|
||||
.Xr g_event 9 ,
|
||||
.Xr g_geom 9 ,
|
||||
.Xr g_provider 9 ,
|
||||
.Xr g_provider_by_name 9
|
||||
.Sh AUTHORS
|
||||
.An -nosplit
|
||||
This manual page was written by
|
||||
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
Loading…
Reference in New Issue
Block a user