1.\"
2.\" Copyright (c) 2009
3.\"	The DragonFly Project.  All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\"
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in
13.\"    the documentation and/or other materials provided with the
14.\"    distribution.
15.\" 3. Neither the name of The DragonFly Project nor the names of its
16.\"    contributors may be used to endorse or promote products derived
17.\"    from this software without specific, prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
23.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.Dd August 13, 2010
33.Dt MAKE_AUTOCLONE_DEV 9
34.Os
35.Sh NAME
36.Nm make_autoclone_dev ,
37.Nm destroy_autoclone_dev ,
38.Nm devfs_clone_bitmap_init ,
39.Nm devfs_clone_bitmap_uninit ,
40.Nm devfs_clone_bitmap_fff ,
41.Nm devfs_clone_bitmap_chk ,
42.Nm devfs_clone_bitmap_set ,
43.Nm devfs_clone_bitmap_get ,
44.Nm devfs_clone_bitmap_put ,
45.Nm DEVFS_DECLARE_CLONE_BITMAP ,
46.Nm DEVFS_CLONE_BITMAP
47.Nd device clone functions
48.Sh SYNOPSIS
49.In sys/types.h
50.In sys/conf.h
51.In sys/devfs.h
52.Ft cdev_t
53.Fn make_autoclone_dev "struct dev_ops *ops" "struct devfs_bitmap *bitmap" "d_clone_t *nhandler" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" "..."
54.Ft void
55.Fn destroy_autoclone_dev "cdev_t dev" "struct devfs_bitmap *bitmap"
56.Ft void
57.Fn devfs_clone_bitmap_init "struct devfs_bitmap *bitmap"
58.Ft void
59.Fn devfs_clone_bitmap_uninit "struct devfs_bitmap *bitmap"
60.Ft int
61.Fn devfs_clone_bitmap_fff "struct devfs_bitmap *bitmap"
62.Ft int
63.Fn devfs_clone_bitmap_chk "struct devfs_bitmap *bitmap" "int unit"
64.Ft void
65.Fn devfs_clone_bitmap_set "struct devfs_bitmap *bitmap" "int unit"
66.Ft int
67.Fn devfs_clone_bitmap_get "struct devfs_bitmap *bitmap" "int limit"
68.Ft void
69.Fn devfs_clone_bitmap_put "struct devfs_bitmap *bitmap" "int unit"
70.Fn DEVFS_DECLARE_CLONE_BITMAP "name"
71.Fn DEVFS_CLONE_BITMAP "name"
72.Sh DESCRIPTION
73.Fn make_autoclone_dev
74creates a
75.Vt cdev_t
76with the default
77.Fa ops ,
78visible in the
79.Xr devfs 5
80namespace, that (when opened) will invoke the clone handler specified by
81.Fa nhandler .
82If a
83.Vt devfs_bitmap *
84is specified, the given
85.Fa bitmap
86is initialized using
87.Fn devfs_clone_bitmap_init .
88.Pp
89The clone handler must be defined as follows:
90.Bd -literal
91d_clone_t mydev_clone;
92
93int
94mydev_clone(struct dev_clone_args *ap)
95{
96};
97.Ed
98.Pp
99When called, the handler is passed a pointer to a populated
100.Vt dev_clone_args
101structure, which is defined as follows:
102.Bd -literal
103struct dev_clone_args {
104        struct dev_generic_args a_head;
105        struct cdev     *a_dev;
106        const char      *a_name;
107        size_t           a_namelen;
108        struct ucred    *a_cred;
109        int              a_mode;
110};
111.Ed
112.Pp
113.Fa a_head.a_dev
114is the
115.Vt cdev_t
116of the accessed autoclone device.
117.Fa a_name
118and
119.Fa a_namelen
120are the registered clonable base name and its length, as specified to
121.Fn make_autoclone_dev .
122.Fa a_mode
123and
124.Fa a_cred
125contain the mode and cred passed to the autoclone device's
126.Fn open .
127.Pp
128The clone handler must set
129.Fa a_dev
130to a new
131.Vt cdev_t ,
132returned by a call to
133.Fn make_only_dev .
134.Fa a_dev
135may also be set to
136.Dv NULL ,
137in which case the
138.Fn open
139will ultimately fail with
140.Er ENXIO .
141If
142.Fa a_dev
143is
144.Pf non- Ns Dv NULL ,
145it is automatically made visible and linked into
146.Xr devfs 5
147as if it was created with
148.Fn make_dev .
149Thus,
150.Fn destroy_dev
151should be used to destroy the cloned
152.Vt cdev_t
153once it is no longer required,
154usually during
155.Fn close .
156.Pp
157.Fn destroy_autoclone_dev
158destroys a
159.Vt cdev_t
160created by
161.Fn make_autoclone_dev
162unregistering its clone handler and (if non-NULL) also uninitializes its
163.Fa bitmap
164using
165.Fn devfs_clone_bitmap_uninit .
166.Pp
167.Fn devfs_clone_bitmap_init
168initializes the given clone
169.Fa bitmap
170so it is ready to use.
171.Pp
172.Fn devfs_clone_bitmap_uninit
173frees the memory associated with the specified clone
174.Fa bitmap
175and leaves it unusable.
176.Pp
177.Fn devfs_clone_bitmap_fff
178returns the first unused unit in
179.Fa bitmap .
180To use this unit, it has to be acquired by a call to
181.Fn devfs_clone_bitmap_set .
182.Pp
183.Fn devfs_clone_bitmap_chk
184checks if
185.Fa unit
186is in use (set) and returns 1 if it is; otherwise 0 is returned.
187.Pp
188.Fn devfs_clone_bitmap_set
189marks
190.Fa unit
191in
192.Fa bitmap
193as used, so further calls to
194.Fn devfs_clone_bitmap_fff
195or
196.Fn devfs_clone_bitmap_get
197cannot retrieve it.
198If one intends to use a clone handler along with preallocated devices, it
199is recommended to block the unit numbers of the preallocated devices by
200calling
201.Fn devfs_clone_bitmap_set
202on them.
203.Pp
204.Fn devfs_clone_bitmap_put
205marks
206.Fa unit
207in the
208.Fa bitmap
209as unused so further calls to
210.Fn devfs_clone_bitmap_fff
211or
212.Fn devfs_clone_bitmap_get
213can retrieve it again.
214.Pp
215.Fn devfs_clone_bitmap_get
216is a shortcut to
217.Fn devfs_clone_bitmap_fff
218and
219.Fn devfs_clone_bitmap_set .
220It will return the first unused unit number and also mark it as used.
221.Pp
222The
223.Fn DEVFS_DECLARE_CLONE_BITMAP
224macro declares a clone bitmap with the specified
225.Fa name .
226As long as the name specified is unique, this macro can be used to declare
227global variables.
228.Pp
229The
230.Fn DEVFS_CLONE_BITMAP
231is a macro which expands the specified
232.Fa name
233to the full name of a clone bitmap.
234It is used in conjunction with
235.Fn DEVFS_DECLARE_CLONE_BITMAP ,
236as it uses the same name.
237.Sh HISTORY
238The
239.Xr devfs 5
240clone facilities and the associated functions all appeared in
241.Dx 2.3 .
242.Sh AUTHOR
243.An Alex Hornung
244