xref: /freebsd/share/man/man9/g_geom.9 (revision 8217df6de80493481e84e1685299a7e95e03652d)
1f827ccb9SPawel Jakub Dawidek.\"
2f827ccb9SPawel Jakub Dawidek.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org>
3f827ccb9SPawel Jakub Dawidek.\" All rights reserved.
4f827ccb9SPawel Jakub Dawidek.\"
5f827ccb9SPawel Jakub Dawidek.\" Redistribution and use in source and binary forms, with or without
6f827ccb9SPawel Jakub Dawidek.\" modification, are permitted provided that the following conditions
7f827ccb9SPawel Jakub Dawidek.\" are met:
8f827ccb9SPawel Jakub Dawidek.\" 1. Redistributions of source code must retain the above copyright
9f827ccb9SPawel Jakub Dawidek.\"    notice, this list of conditions and the following disclaimer.
10f827ccb9SPawel Jakub Dawidek.\" 2. Redistributions in binary form must reproduce the above copyright
11f827ccb9SPawel Jakub Dawidek.\"    notice, this list of conditions and the following disclaimer in the
12f827ccb9SPawel Jakub Dawidek.\"    documentation and/or other materials provided with the distribution.
13f827ccb9SPawel Jakub Dawidek.\"
14f827ccb9SPawel Jakub Dawidek.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
15f827ccb9SPawel Jakub Dawidek.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
16f827ccb9SPawel Jakub Dawidek.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
17f827ccb9SPawel Jakub Dawidek.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
18f827ccb9SPawel Jakub Dawidek.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
19f827ccb9SPawel Jakub Dawidek.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
20f827ccb9SPawel Jakub Dawidek.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
21f827ccb9SPawel Jakub Dawidek.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22f827ccb9SPawel Jakub Dawidek.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
23f827ccb9SPawel Jakub Dawidek.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24f827ccb9SPawel Jakub Dawidek.\"
25f827ccb9SPawel Jakub Dawidek.\" $FreeBSD$
26f827ccb9SPawel Jakub Dawidek.\"
27f827ccb9SPawel Jakub Dawidek.Dd January 16, 2004
28f827ccb9SPawel Jakub Dawidek.Dt g_geom 9
29f827ccb9SPawel Jakub Dawidek.Os
30f827ccb9SPawel Jakub Dawidek.Sh NAME
31f827ccb9SPawel Jakub Dawidek.Nm g_new_geomf ,
32f827ccb9SPawel Jakub Dawidek.Nm g_destroy_geom
33f827ccb9SPawel Jakub Dawidek.Nd "geom management"
34f827ccb9SPawel Jakub Dawidek.Sh SYNOPSIS
35f827ccb9SPawel Jakub Dawidek.In geom/geom.h
36f827ccb9SPawel Jakub Dawidek.Ft "struct g_geom *"
37f827ccb9SPawel Jakub Dawidek.Fn g_new_geomf "struct g_class *mp" "const char *fmt" ...
38f827ccb9SPawel Jakub Dawidek.Ft void
39f827ccb9SPawel Jakub Dawidek.Fn g_destroy_geom "struct g_geom *gp"
40f827ccb9SPawel Jakub Dawidek.Sh DESCRIPTION
41f827ccb9SPawel Jakub DawidekThe geom (do not confuse
42f827ccb9SPawel Jakub Dawidek.Dq geom
43f827ccb9SPawel Jakub Dawidekwith
44f827ccb9SPawel Jakub Dawidek.Dq GEOM )
45f827ccb9SPawel Jakub Dawidekis an instance of a GEOM class.
46f827ccb9SPawel Jakub DawidekFor example: in a typical i386 FreeBSD system, there will be one geom
47f827ccb9SPawel Jakub Dawidekof class MBR for each disk.
48f827ccb9SPawel Jakub DawidekThe geom's name is not really important, it is only used in the XML
49f827ccb9SPawel Jakub Dawidekdump and for debugging purposes.
50f827ccb9SPawel Jakub DawidekThere can be many geoms with the same name.
51f827ccb9SPawel Jakub Dawidek.Pp
52f827ccb9SPawel Jakub DawidekThe
53f827ccb9SPawel Jakub Dawidek.Fn g_new_geomf
54f827ccb9SPawel Jakub Dawidekfunction creates a new geom, which will be an instance of the class
55f827ccb9SPawel Jakub Dawidek.Fa mp .
56f827ccb9SPawel Jakub DawidekThe geom name is created in a printf\-like way from the rest of the arguments.
57f827ccb9SPawel Jakub Dawidek.Pp
58f827ccb9SPawel Jakub DawidekThe
59f827ccb9SPawel Jakub Dawidek.Fn g_destroy_geom
60f827ccb9SPawel Jakub Dawidekfunction destroys the given geom imediately and cancels all related pending
61f827ccb9SPawel Jakub Dawidekevents.
62f827ccb9SPawel Jakub Dawidek.Pp
63f827ccb9SPawel Jakub DawidekStructure
64f827ccb9SPawel Jakub Dawidek.Vt g_geom
65f827ccb9SPawel Jakub Dawidekcontains fields, that should be set by the caller after geom creation, but before
66f827ccb9SPawel Jakub Dawidekcreating any providers or consumers related to this geom (not all are required):
67f827ccb9SPawel Jakub Dawidek.Bl -inset -offset indent
68f827ccb9SPawel Jakub Dawidek.It Vt "g_start_t *" Va start
69f827ccb9SPawel Jakub DawidekPointer to a function used for I/O processing.
70f827ccb9SPawel Jakub Dawidek.It Vt "g_spoiled_t *" Va spoiled
71f827ccb9SPawel Jakub DawidekPointer to a function used for consumers spoiling.
72f827ccb9SPawel Jakub Dawidek.It Vt "g_dumpconf_t *" Va dumpconf
73f827ccb9SPawel Jakub DawidekPointer to a function used for configuration in XML format dumping.
74f827ccb9SPawel Jakub Dawidek.It Vt "g_access_t *" Va access
75f827ccb9SPawel Jakub DawidekPointer to a function used for access control.
76f827ccb9SPawel Jakub Dawidek.It Vt "g_orphan_t *" Va orphan
77f827ccb9SPawel Jakub DawidekPointer to a function used to inform about orphaned consumer.
78f827ccb9SPawel Jakub Dawidek.It Vt "g_ioctl_t *" Va ioctl
79f827ccb9SPawel Jakub DawidekPointer to a function used for handling ioctl requests.
80f827ccb9SPawel Jakub Dawidek.It Vt "void *" Va softc
81f827ccb9SPawel Jakub DawidekField for private use.
82f827ccb9SPawel Jakub Dawidek.El
83f827ccb9SPawel Jakub Dawidek.Sh RESTRICTIONS/CONDITIONS
84f827ccb9SPawel Jakub DawidekIf you intend to use providers in this geom you must set field
85f827ccb9SPawel Jakub Dawidek.Va start
86f827ccb9SPawel Jakub Dawidekof your geom.
87f827ccb9SPawel Jakub Dawidek.Pp
88f827ccb9SPawel Jakub DawidekIf you are planning to use consumers in your geom you must set fields
89f827ccb9SPawel Jakub Dawidek.Va orphan
90f827ccb9SPawel Jakub Dawidekand
91f827ccb9SPawel Jakub Dawidek.Va access
92f827ccb9SPawel Jakub Dawidekfor it.
93f827ccb9SPawel Jakub Dawidek.Pp
94f827ccb9SPawel Jakub Dawidek.Fn g_new_geomf :
95f827ccb9SPawel Jakub Dawidek.Bl -item -offset indent
96f827ccb9SPawel Jakub Dawidek.It
97f827ccb9SPawel Jakub DawidekClass
98f827ccb9SPawel Jakub Dawidek.Fa mp
99f827ccb9SPawel Jakub Dawidekmust be valid (registered in GEOM).
100f827ccb9SPawel Jakub Dawidek.It
101f827ccb9SPawel Jakub DawidekThe topology lock has to be held.
102f827ccb9SPawel Jakub Dawidek.El
103f827ccb9SPawel Jakub Dawidek.Pp
104f827ccb9SPawel Jakub Dawidek.Fn g_destroy_geom :
105f827ccb9SPawel Jakub Dawidek.Bl -item -offset indent
106f827ccb9SPawel Jakub Dawidek.It
107f827ccb9SPawel Jakub DawidekThe geom can not posses any providers.
108f827ccb9SPawel Jakub Dawidek.It
109f827ccb9SPawel Jakub DawidekThe geom can not posses any consumers.
110f827ccb9SPawel Jakub Dawidek.It
111f827ccb9SPawel Jakub DawidekThe topology lock has to be held.
112f827ccb9SPawel Jakub Dawidek.El
113f827ccb9SPawel Jakub Dawidek.Sh RETURN VALUES
114f827ccb9SPawel Jakub Dawidek.Fn g_new_geomf
115f827ccb9SPawel Jakub Dawidekreturns a pointer to the newly created geom or
116f827ccb9SPawel Jakub Dawidek.Dv NULL
117f827ccb9SPawel Jakub Dawidekif an error occured.
118f827ccb9SPawel Jakub Dawidek.Sh EXAMPLES
119f827ccb9SPawel Jakub DawidekCreate an example geom.
120f827ccb9SPawel Jakub Dawidek.Bd -literal -offset indent
121f827ccb9SPawel Jakub Dawidekstatic struct geom *
122f827ccb9SPawel Jakub Dawidekg_example_start(struct bio *bp)
123f827ccb9SPawel Jakub Dawidek{
124f827ccb9SPawel Jakub Dawidek
125f827ccb9SPawel Jakub Dawidek	[...]
126f827ccb9SPawel Jakub Dawidek}
127f827ccb9SPawel Jakub Dawidek
128f827ccb9SPawel Jakub Dawidekstatic void
129f827ccb9SPawel Jakub Dawidekg_example_orphan(struct g_consumer *cp)
130f827ccb9SPawel Jakub Dawidek{
131f827ccb9SPawel Jakub Dawidek
132f827ccb9SPawel Jakub Dawidek	g_topology_assert();
133f827ccb9SPawel Jakub Dawidek
134f827ccb9SPawel Jakub Dawidek	[...]
135f827ccb9SPawel Jakub Dawidek}
136f827ccb9SPawel Jakub Dawidek
137f827ccb9SPawel Jakub Dawidekstatic void
138f827ccb9SPawel Jakub Dawidekg_example_spoiled(struct g_consumer *cp)
139f827ccb9SPawel Jakub Dawidek{
140f827ccb9SPawel Jakub Dawidek
141f827ccb9SPawel Jakub Dawidek	g_topology_assert();
142f827ccb9SPawel Jakub Dawidek
143f827ccb9SPawel Jakub Dawidek	[...]
144f827ccb9SPawel Jakub Dawidek}
145f827ccb9SPawel Jakub Dawidek
146f827ccb9SPawel Jakub Dawidekstatic void
147f827ccb9SPawel Jakub Dawidekg_example_access(struct g_provider *pp, int dr, int dw, int de)
148f827ccb9SPawel Jakub Dawidek{
149f827ccb9SPawel Jakub Dawidek
150f827ccb9SPawel Jakub Dawidek	[...]
151f827ccb9SPawel Jakub Dawidek}
152f827ccb9SPawel Jakub Dawidek
153f827ccb9SPawel Jakub Dawidekstatic struct g_geom *
154f827ccb9SPawel Jakub Dawidekcreate_example_geom(struct g_class *myclass)
155f827ccb9SPawel Jakub Dawidek{
156f827ccb9SPawel Jakub Dawidek	struct g_geom *gp;
157f827ccb9SPawel Jakub Dawidek
158f827ccb9SPawel Jakub Dawidek	g_topology_lock();
159f827ccb9SPawel Jakub Dawidek	gp = g_new_geomf(myclass, "example_geom");
160f827ccb9SPawel Jakub Dawidek	g_topology_unlock();
161f827ccb9SPawel Jakub Dawidek	if (gp != NULL) {
162f827ccb9SPawel Jakub Dawidek		gp->start = g_example_start;
163f827ccb9SPawel Jakub Dawidek		gp->orphan = g_example_orphan;
164f827ccb9SPawel Jakub Dawidek		gp->spoiled = g_example_spoiled;
165f827ccb9SPawel Jakub Dawidek		gp->access = g_example_access;
166f827ccb9SPawel Jakub Dawidek		gp->softc = NULL;
167f827ccb9SPawel Jakub Dawidek	}
168f827ccb9SPawel Jakub Dawidek
169f827ccb9SPawel Jakub Dawidek	return (gp);
170f827ccb9SPawel Jakub Dawidek}
171f827ccb9SPawel Jakub Dawidek
172f827ccb9SPawel Jakub Dawidekstatic int
173f827ccb9SPawel Jakub Dawidekdestroy_example_geom(struct g_geom *gp)
174f827ccb9SPawel Jakub Dawidek{
175f827ccb9SPawel Jakub Dawidek
176f827ccb9SPawel Jakub Dawidek	g_topology_lock();
177f827ccb9SPawel Jakub Dawidek	if (!LIST_EMPTY(&gp->provider) ||
178f827ccb9SPawel Jakub Dawidek	    !LIST_EMPTY(&gp->consumer)) {
179f827ccb9SPawel Jakub Dawidek		g_topology_unlock();
180f827ccb9SPawel Jakub Dawidek		return (EBUSY);
181f827ccb9SPawel Jakub Dawidek	}
182f827ccb9SPawel Jakub Dawidek	g_destroy_geom(gp);
183f827ccb9SPawel Jakub Dawidek	g_topology_unlock();
184f827ccb9SPawel Jakub Dawidek
185f827ccb9SPawel Jakub Dawidek	return (0);
186f827ccb9SPawel Jakub Dawidek}
187f827ccb9SPawel Jakub Dawidek.Ed
188f827ccb9SPawel Jakub Dawidek.Sh SEE ALSO
189f827ccb9SPawel Jakub Dawidek.Xr DECLARE_GEOM_CLASS 9 ,
190f827ccb9SPawel Jakub Dawidek.Xr geom 4 ,
1918217df6dSPawel Jakub Dawidek.Xr g_access 9 ,
192f827ccb9SPawel Jakub Dawidek.Xr g_attach 9 ,
193f827ccb9SPawel Jakub Dawidek.Xr g_bio 9 ,
194f827ccb9SPawel Jakub Dawidek.Xr g_consumer 9 ,
195f827ccb9SPawel Jakub Dawidek.Xr g_data 9 ,
196f827ccb9SPawel Jakub Dawidek.Xr g_event 9 ,
197f827ccb9SPawel Jakub Dawidek.Xr g_provider 9 ,
198f827ccb9SPawel Jakub Dawidek.Xr g_provider_by_name 9 ,
199f827ccb9SPawel Jakub Dawidek.Xr g_wither_geom 9
200f827ccb9SPawel Jakub Dawidek.Sh AUTHORS
201f827ccb9SPawel Jakub Dawidek.An -nosplit
202f827ccb9SPawel Jakub DawidekThis manual page was written by
203f827ccb9SPawel Jakub Dawidek.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
204