[PATCH] add function documentation for register_chrdev()
[linux-2.6.git] / fs / char_dev.c
1 /*
2  *  linux/fs/char_dev.c
3  *
4  *  Copyright (C) 1991, 1992  Linus Torvalds
5  */
6
7 #include <linux/init.h>
8 #include <linux/fs.h>
9 #include <linux/slab.h>
10 #include <linux/string.h>
11
12 #include <linux/major.h>
13 #include <linux/errno.h>
14 #include <linux/module.h>
15 #include <linux/smp_lock.h>
16 #include <linux/seq_file.h>
17
18 #include <linux/kobject.h>
19 #include <linux/kobj_map.h>
20 #include <linux/cdev.h>
21 #include <linux/mutex.h>
22
23 #ifdef CONFIG_KMOD
24 #include <linux/kmod.h>
25 #endif
26
27 static struct kobj_map *cdev_map;
28
29 static DEFINE_MUTEX(chrdevs_lock);
30
31 static struct char_device_struct {
32         struct char_device_struct *next;
33         unsigned int major;
34         unsigned int baseminor;
35         int minorct;
36         char name[64];
37         struct file_operations *fops;
38         struct cdev *cdev;              /* will die */
39 } *chrdevs[CHRDEV_MAJOR_HASH_SIZE];
40
41 /* index in the above */
42 static inline int major_to_index(int major)
43 {
44         return major % CHRDEV_MAJOR_HASH_SIZE;
45 }
46
47 #ifdef CONFIG_PROC_FS
48
49 void chrdev_show(struct seq_file *f, off_t offset)
50 {
51         struct char_device_struct *cd;
52
53         if (offset < CHRDEV_MAJOR_HASH_SIZE) {
54                 mutex_lock(&chrdevs_lock);
55                 for (cd = chrdevs[offset]; cd; cd = cd->next)
56                         seq_printf(f, "%3d %s\n", cd->major, cd->name);
57                 mutex_unlock(&chrdevs_lock);
58         }
59 }
60
61 #endif /* CONFIG_PROC_FS */
62
63 /*
64  * Register a single major with a specified minor range.
65  *
66  * If major == 0 this functions will dynamically allocate a major and return
67  * its number.
68  *
69  * If major > 0 this function will attempt to reserve the passed range of
70  * minors and will return zero on success.
71  *
72  * Returns a -ve errno on failure.
73  */
74 static struct char_device_struct *
75 __register_chrdev_region(unsigned int major, unsigned int baseminor,
76                            int minorct, const char *name)
77 {
78         struct char_device_struct *cd, **cp;
79         int ret = 0;
80         int i;
81
82         cd = kzalloc(sizeof(struct char_device_struct), GFP_KERNEL);
83         if (cd == NULL)
84                 return ERR_PTR(-ENOMEM);
85
86         mutex_lock(&chrdevs_lock);
87
88         /* temporary */
89         if (major == 0) {
90                 for (i = ARRAY_SIZE(chrdevs)-1; i > 0; i--) {
91                         if (chrdevs[i] == NULL)
92                                 break;
93                 }
94
95                 if (i == 0) {
96                         ret = -EBUSY;
97                         goto out;
98                 }
99                 major = i;
100                 ret = major;
101         }
102
103         cd->major = major;
104         cd->baseminor = baseminor;
105         cd->minorct = minorct;
106         strncpy(cd->name,name, 64);
107
108         i = major_to_index(major);
109
110         for (cp = &chrdevs[i]; *cp; cp = &(*cp)->next)
111                 if ((*cp)->major > major ||
112                     ((*cp)->major == major && (*cp)->baseminor >= baseminor))
113                         break;
114         if (*cp && (*cp)->major == major &&
115             (*cp)->baseminor < baseminor + minorct) {
116                 ret = -EBUSY;
117                 goto out;
118         }
119         cd->next = *cp;
120         *cp = cd;
121         mutex_unlock(&chrdevs_lock);
122         return cd;
123 out:
124         mutex_unlock(&chrdevs_lock);
125         kfree(cd);
126         return ERR_PTR(ret);
127 }
128
129 static struct char_device_struct *
130 __unregister_chrdev_region(unsigned major, unsigned baseminor, int minorct)
131 {
132         struct char_device_struct *cd = NULL, **cp;
133         int i = major_to_index(major);
134
135         mutex_lock(&chrdevs_lock);
136         for (cp = &chrdevs[i]; *cp; cp = &(*cp)->next)
137                 if ((*cp)->major == major &&
138                     (*cp)->baseminor == baseminor &&
139                     (*cp)->minorct == minorct)
140                         break;
141         if (*cp) {
142                 cd = *cp;
143                 *cp = cd->next;
144         }
145         mutex_unlock(&chrdevs_lock);
146         return cd;
147 }
148
149 int register_chrdev_region(dev_t from, unsigned count, const char *name)
150 {
151         struct char_device_struct *cd;
152         dev_t to = from + count;
153         dev_t n, next;
154
155         for (n = from; n < to; n = next) {
156                 next = MKDEV(MAJOR(n)+1, 0);
157                 if (next > to)
158                         next = to;
159                 cd = __register_chrdev_region(MAJOR(n), MINOR(n),
160                                next - n, name);
161                 if (IS_ERR(cd))
162                         goto fail;
163         }
164         return 0;
165 fail:
166         to = n;
167         for (n = from; n < to; n = next) {
168                 next = MKDEV(MAJOR(n)+1, 0);
169                 kfree(__unregister_chrdev_region(MAJOR(n), MINOR(n), next - n));
170         }
171         return PTR_ERR(cd);
172 }
173
174 int alloc_chrdev_region(dev_t *dev, unsigned baseminor, unsigned count,
175                         const char *name)
176 {
177         struct char_device_struct *cd;
178         cd = __register_chrdev_region(0, baseminor, count, name);
179         if (IS_ERR(cd))
180                 return PTR_ERR(cd);
181         *dev = MKDEV(cd->major, cd->baseminor);
182         return 0;
183 }
184
185 /**
186  * register_chrdev() - Register a major number for character devices.
187  * @major: major device number or 0 for dynamic allocation
188  * @name: name of this range of devices
189  * @fops: file operations associated with this devices
190  *
191  * If @major == 0 this functions will dynamically allocate a major and return
192  * its number.
193  *
194  * If @major > 0 this function will attempt to reserve a device with the given
195  * major number and will return zero on success.
196  *
197  * Returns a -ve errno on failure.
198  *
199  * The name of this device has nothing to do with the name of the device in
200  * /dev. It only helps to keep track of the different owners of devices. If
201  * your module name has only one type of devices it's ok to use e.g. the name
202  * of the module here.
203  *
204  * This function registers a range of 256 minor numbers. The first minor number
205  * is 0.
206  */
207 int register_chrdev(unsigned int major, const char *name,
208                     const struct file_operations *fops)
209 {
210         struct char_device_struct *cd;
211         struct cdev *cdev;
212         char *s;
213         int err = -ENOMEM;
214
215         cd = __register_chrdev_region(major, 0, 256, name);
216         if (IS_ERR(cd))
217                 return PTR_ERR(cd);
218         
219         cdev = cdev_alloc();
220         if (!cdev)
221                 goto out2;
222
223         cdev->owner = fops->owner;
224         cdev->ops = fops;
225         kobject_set_name(&cdev->kobj, "%s", name);
226         for (s = strchr(kobject_name(&cdev->kobj),'/'); s; s = strchr(s, '/'))
227                 *s = '!';
228                 
229         err = cdev_add(cdev, MKDEV(cd->major, 0), 256);
230         if (err)
231                 goto out;
232
233         cd->cdev = cdev;
234
235         return major ? 0 : cd->major;
236 out:
237         kobject_put(&cdev->kobj);
238 out2:
239         kfree(__unregister_chrdev_region(cd->major, 0, 256));
240         return err;
241 }
242
243 void unregister_chrdev_region(dev_t from, unsigned count)
244 {
245         dev_t to = from + count;
246         dev_t n, next;
247
248         for (n = from; n < to; n = next) {
249                 next = MKDEV(MAJOR(n)+1, 0);
250                 if (next > to)
251                         next = to;
252                 kfree(__unregister_chrdev_region(MAJOR(n), MINOR(n), next - n));
253         }
254 }
255
256 int unregister_chrdev(unsigned int major, const char *name)
257 {
258         struct char_device_struct *cd;
259         cd = __unregister_chrdev_region(major, 0, 256);
260         if (cd && cd->cdev)
261                 cdev_del(cd->cdev);
262         kfree(cd);
263         return 0;
264 }
265
266 static DEFINE_SPINLOCK(cdev_lock);
267
268 static struct kobject *cdev_get(struct cdev *p)
269 {
270         struct module *owner = p->owner;
271         struct kobject *kobj;
272
273         if (owner && !try_module_get(owner))
274                 return NULL;
275         kobj = kobject_get(&p->kobj);
276         if (!kobj)
277                 module_put(owner);
278         return kobj;
279 }
280
281 void cdev_put(struct cdev *p)
282 {
283         if (p) {
284                 struct module *owner = p->owner;
285                 kobject_put(&p->kobj);
286                 module_put(owner);
287         }
288 }
289
290 /*
291  * Called every time a character special file is opened
292  */
293 int chrdev_open(struct inode * inode, struct file * filp)
294 {
295         struct cdev *p;
296         struct cdev *new = NULL;
297         int ret = 0;
298
299         spin_lock(&cdev_lock);
300         p = inode->i_cdev;
301         if (!p) {
302                 struct kobject *kobj;
303                 int idx;
304                 spin_unlock(&cdev_lock);
305                 kobj = kobj_lookup(cdev_map, inode->i_rdev, &idx);
306                 if (!kobj)
307                         return -ENXIO;
308                 new = container_of(kobj, struct cdev, kobj);
309                 spin_lock(&cdev_lock);
310                 p = inode->i_cdev;
311                 if (!p) {
312                         inode->i_cdev = p = new;
313                         inode->i_cindex = idx;
314                         list_add(&inode->i_devices, &p->list);
315                         new = NULL;
316                 } else if (!cdev_get(p))
317                         ret = -ENXIO;
318         } else if (!cdev_get(p))
319                 ret = -ENXIO;
320         spin_unlock(&cdev_lock);
321         cdev_put(new);
322         if (ret)
323                 return ret;
324         filp->f_op = fops_get(p->ops);
325         if (!filp->f_op) {
326                 cdev_put(p);
327                 return -ENXIO;
328         }
329         if (filp->f_op->open) {
330                 lock_kernel();
331                 ret = filp->f_op->open(inode,filp);
332                 unlock_kernel();
333         }
334         if (ret)
335                 cdev_put(p);
336         return ret;
337 }
338
339 void cd_forget(struct inode *inode)
340 {
341         spin_lock(&cdev_lock);
342         list_del_init(&inode->i_devices);
343         inode->i_cdev = NULL;
344         spin_unlock(&cdev_lock);
345 }
346
347 static void cdev_purge(struct cdev *cdev)
348 {
349         spin_lock(&cdev_lock);
350         while (!list_empty(&cdev->list)) {
351                 struct inode *inode;
352                 inode = container_of(cdev->list.next, struct inode, i_devices);
353                 list_del_init(&inode->i_devices);
354                 inode->i_cdev = NULL;
355         }
356         spin_unlock(&cdev_lock);
357 }
358
359 /*
360  * Dummy default file-operations: the only thing this does
361  * is contain the open that then fills in the correct operations
362  * depending on the special file...
363  */
364 const struct file_operations def_chr_fops = {
365         .open = chrdev_open,
366 };
367
368 static struct kobject *exact_match(dev_t dev, int *part, void *data)
369 {
370         struct cdev *p = data;
371         return &p->kobj;
372 }
373
374 static int exact_lock(dev_t dev, void *data)
375 {
376         struct cdev *p = data;
377         return cdev_get(p) ? 0 : -1;
378 }
379
380 int cdev_add(struct cdev *p, dev_t dev, unsigned count)
381 {
382         p->dev = dev;
383         p->count = count;
384         return kobj_map(cdev_map, dev, count, NULL, exact_match, exact_lock, p);
385 }
386
387 static void cdev_unmap(dev_t dev, unsigned count)
388 {
389         kobj_unmap(cdev_map, dev, count);
390 }
391
392 void cdev_del(struct cdev *p)
393 {
394         cdev_unmap(p->dev, p->count);
395         kobject_put(&p->kobj);
396 }
397
398
399 static void cdev_default_release(struct kobject *kobj)
400 {
401         struct cdev *p = container_of(kobj, struct cdev, kobj);
402         cdev_purge(p);
403 }
404
405 static void cdev_dynamic_release(struct kobject *kobj)
406 {
407         struct cdev *p = container_of(kobj, struct cdev, kobj);
408         cdev_purge(p);
409         kfree(p);
410 }
411
412 static struct kobj_type ktype_cdev_default = {
413         .release        = cdev_default_release,
414 };
415
416 static struct kobj_type ktype_cdev_dynamic = {
417         .release        = cdev_dynamic_release,
418 };
419
420 struct cdev *cdev_alloc(void)
421 {
422         struct cdev *p = kzalloc(sizeof(struct cdev), GFP_KERNEL);
423         if (p) {
424                 p->kobj.ktype = &ktype_cdev_dynamic;
425                 INIT_LIST_HEAD(&p->list);
426                 kobject_init(&p->kobj);
427         }
428         return p;
429 }
430
431 void cdev_init(struct cdev *cdev, const struct file_operations *fops)
432 {
433         memset(cdev, 0, sizeof *cdev);
434         INIT_LIST_HEAD(&cdev->list);
435         cdev->kobj.ktype = &ktype_cdev_default;
436         kobject_init(&cdev->kobj);
437         cdev->ops = fops;
438 }
439
440 static struct kobject *base_probe(dev_t dev, int *part, void *data)
441 {
442         if (request_module("char-major-%d-%d", MAJOR(dev), MINOR(dev)) > 0)
443                 /* Make old-style 2.4 aliases work */
444                 request_module("char-major-%d", MAJOR(dev));
445         return NULL;
446 }
447
448 void __init chrdev_init(void)
449 {
450         cdev_map = kobj_map_init(base_probe, &chrdevs_lock);
451 }
452
453
454 /* Let modules do char dev stuff */
455 EXPORT_SYMBOL(register_chrdev_region);
456 EXPORT_SYMBOL(unregister_chrdev_region);
457 EXPORT_SYMBOL(alloc_chrdev_region);
458 EXPORT_SYMBOL(cdev_init);
459 EXPORT_SYMBOL(cdev_alloc);
460 EXPORT_SYMBOL(cdev_del);
461 EXPORT_SYMBOL(cdev_add);
462 EXPORT_SYMBOL(register_chrdev);
463 EXPORT_SYMBOL(unregister_chrdev);