[PATCH] cdev documentation
[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 #include <linux/backing-dev.h>
23
24 #ifdef CONFIG_KMOD
25 #include <linux/kmod.h>
26 #endif
27
28 /*
29  * capabilities for /dev/mem, /dev/kmem and similar directly mappable character
30  * devices
31  * - permits shared-mmap for read, write and/or exec
32  * - does not permit private mmap in NOMMU mode (can't do COW)
33  * - no readahead or I/O queue unplugging required
34  */
35 struct backing_dev_info directly_mappable_cdev_bdi = {
36         .capabilities   = (
37 #ifdef CONFIG_MMU
38                 /* permit private copies of the data to be taken */
39                 BDI_CAP_MAP_COPY |
40 #endif
41                 /* permit direct mmap, for read, write or exec */
42                 BDI_CAP_MAP_DIRECT |
43                 BDI_CAP_READ_MAP | BDI_CAP_WRITE_MAP | BDI_CAP_EXEC_MAP),
44 };
45
46 static struct kobj_map *cdev_map;
47
48 static DEFINE_MUTEX(chrdevs_lock);
49
50 static struct char_device_struct {
51         struct char_device_struct *next;
52         unsigned int major;
53         unsigned int baseminor;
54         int minorct;
55         char name[64];
56         struct file_operations *fops;
57         struct cdev *cdev;              /* will die */
58 } *chrdevs[CHRDEV_MAJOR_HASH_SIZE];
59
60 /* index in the above */
61 static inline int major_to_index(int major)
62 {
63         return major % CHRDEV_MAJOR_HASH_SIZE;
64 }
65
66 #ifdef CONFIG_PROC_FS
67
68 void chrdev_show(struct seq_file *f, off_t offset)
69 {
70         struct char_device_struct *cd;
71
72         if (offset < CHRDEV_MAJOR_HASH_SIZE) {
73                 mutex_lock(&chrdevs_lock);
74                 for (cd = chrdevs[offset]; cd; cd = cd->next)
75                         seq_printf(f, "%3d %s\n", cd->major, cd->name);
76                 mutex_unlock(&chrdevs_lock);
77         }
78 }
79
80 #endif /* CONFIG_PROC_FS */
81
82 /*
83  * Register a single major with a specified minor range.
84  *
85  * If major == 0 this functions will dynamically allocate a major and return
86  * its number.
87  *
88  * If major > 0 this function will attempt to reserve the passed range of
89  * minors and will return zero on success.
90  *
91  * Returns a -ve errno on failure.
92  */
93 static struct char_device_struct *
94 __register_chrdev_region(unsigned int major, unsigned int baseminor,
95                            int minorct, const char *name)
96 {
97         struct char_device_struct *cd, **cp;
98         int ret = 0;
99         int i;
100
101         cd = kzalloc(sizeof(struct char_device_struct), GFP_KERNEL);
102         if (cd == NULL)
103                 return ERR_PTR(-ENOMEM);
104
105         mutex_lock(&chrdevs_lock);
106
107         /* temporary */
108         if (major == 0) {
109                 for (i = ARRAY_SIZE(chrdevs)-1; i > 0; i--) {
110                         if (chrdevs[i] == NULL)
111                                 break;
112                 }
113
114                 if (i == 0) {
115                         ret = -EBUSY;
116                         goto out;
117                 }
118                 major = i;
119                 ret = major;
120         }
121
122         cd->major = major;
123         cd->baseminor = baseminor;
124         cd->minorct = minorct;
125         strncpy(cd->name,name, 64);
126
127         i = major_to_index(major);
128
129         for (cp = &chrdevs[i]; *cp; cp = &(*cp)->next)
130                 if ((*cp)->major > major ||
131                     ((*cp)->major == major &&
132                      (((*cp)->baseminor >= baseminor) ||
133                       ((*cp)->baseminor + (*cp)->minorct > baseminor))))
134                         break;
135
136         /* Check for overlapping minor ranges.  */
137         if (*cp && (*cp)->major == major) {
138                 int old_min = (*cp)->baseminor;
139                 int old_max = (*cp)->baseminor + (*cp)->minorct - 1;
140                 int new_min = baseminor;
141                 int new_max = baseminor + minorct - 1;
142
143                 /* New driver overlaps from the left.  */
144                 if (new_max >= old_min && new_max <= old_max) {
145                         ret = -EBUSY;
146                         goto out;
147                 }
148
149                 /* New driver overlaps from the right.  */
150                 if (new_min <= old_max && new_min >= old_min) {
151                         ret = -EBUSY;
152                         goto out;
153                 }
154         }
155
156         cd->next = *cp;
157         *cp = cd;
158         mutex_unlock(&chrdevs_lock);
159         return cd;
160 out:
161         mutex_unlock(&chrdevs_lock);
162         kfree(cd);
163         return ERR_PTR(ret);
164 }
165
166 static struct char_device_struct *
167 __unregister_chrdev_region(unsigned major, unsigned baseminor, int minorct)
168 {
169         struct char_device_struct *cd = NULL, **cp;
170         int i = major_to_index(major);
171
172         mutex_lock(&chrdevs_lock);
173         for (cp = &chrdevs[i]; *cp; cp = &(*cp)->next)
174                 if ((*cp)->major == major &&
175                     (*cp)->baseminor == baseminor &&
176                     (*cp)->minorct == minorct)
177                         break;
178         if (*cp) {
179                 cd = *cp;
180                 *cp = cd->next;
181         }
182         mutex_unlock(&chrdevs_lock);
183         return cd;
184 }
185
186 /**
187  * register_chrdev_region() - register a range of device numbers
188  * @from: the first in the desired range of device numbers; must include
189  *        the major number.
190  * @count: the number of consecutive device numbers required
191  * @name: the name of the device or driver.
192  *
193  * Return value is zero on success, a negative error code on failure.
194  */
195 int register_chrdev_region(dev_t from, unsigned count, const char *name)
196 {
197         struct char_device_struct *cd;
198         dev_t to = from + count;
199         dev_t n, next;
200
201         for (n = from; n < to; n = next) {
202                 next = MKDEV(MAJOR(n)+1, 0);
203                 if (next > to)
204                         next = to;
205                 cd = __register_chrdev_region(MAJOR(n), MINOR(n),
206                                next - n, name);
207                 if (IS_ERR(cd))
208                         goto fail;
209         }
210         return 0;
211 fail:
212         to = n;
213         for (n = from; n < to; n = next) {
214                 next = MKDEV(MAJOR(n)+1, 0);
215                 kfree(__unregister_chrdev_region(MAJOR(n), MINOR(n), next - n));
216         }
217         return PTR_ERR(cd);
218 }
219
220 /**
221  * alloc_chrdev_region() - register a range of char device numbers
222  * @dev: output parameter for first assigned number
223  * @baseminor: first of the requested range of minor numbers
224  * @count: the number of minor numbers required
225  * @name: the name of the associated device or driver
226  *
227  * Allocates a range of char device numbers.  The major number will be
228  * chosen dynamically, and returned (along with the first minor number)
229  * in @dev.  Returns zero or a negative error code.
230  */
231 int alloc_chrdev_region(dev_t *dev, unsigned baseminor, unsigned count,
232                         const char *name)
233 {
234         struct char_device_struct *cd;
235         cd = __register_chrdev_region(0, baseminor, count, name);
236         if (IS_ERR(cd))
237                 return PTR_ERR(cd);
238         *dev = MKDEV(cd->major, cd->baseminor);
239         return 0;
240 }
241
242 /**
243  * register_chrdev() - Register a major number for character devices.
244  * @major: major device number or 0 for dynamic allocation
245  * @name: name of this range of devices
246  * @fops: file operations associated with this devices
247  *
248  * If @major == 0 this functions will dynamically allocate a major and return
249  * its number.
250  *
251  * If @major > 0 this function will attempt to reserve a device with the given
252  * major number and will return zero on success.
253  *
254  * Returns a -ve errno on failure.
255  *
256  * The name of this device has nothing to do with the name of the device in
257  * /dev. It only helps to keep track of the different owners of devices. If
258  * your module name has only one type of devices it's ok to use e.g. the name
259  * of the module here.
260  *
261  * This function registers a range of 256 minor numbers. The first minor number
262  * is 0.
263  */
264 int register_chrdev(unsigned int major, const char *name,
265                     const struct file_operations *fops)
266 {
267         struct char_device_struct *cd;
268         struct cdev *cdev;
269         char *s;
270         int err = -ENOMEM;
271
272         cd = __register_chrdev_region(major, 0, 256, name);
273         if (IS_ERR(cd))
274                 return PTR_ERR(cd);
275         
276         cdev = cdev_alloc();
277         if (!cdev)
278                 goto out2;
279
280         cdev->owner = fops->owner;
281         cdev->ops = fops;
282         kobject_set_name(&cdev->kobj, "%s", name);
283         for (s = strchr(kobject_name(&cdev->kobj),'/'); s; s = strchr(s, '/'))
284                 *s = '!';
285                 
286         err = cdev_add(cdev, MKDEV(cd->major, 0), 256);
287         if (err)
288                 goto out;
289
290         cd->cdev = cdev;
291
292         return major ? 0 : cd->major;
293 out:
294         kobject_put(&cdev->kobj);
295 out2:
296         kfree(__unregister_chrdev_region(cd->major, 0, 256));
297         return err;
298 }
299
300 /**
301  * unregister_chrdev_region() - return a range of device numbers
302  * @from: the first in the range of numbers to unregister
303  * @count: the number of device numbers to unregister
304  *
305  * This function will unregister a range of @count device numbers,
306  * starting with @from.  The caller should normally be the one who
307  * allocated those numbers in the first place...
308  */
309 void unregister_chrdev_region(dev_t from, unsigned count)
310 {
311         dev_t to = from + count;
312         dev_t n, next;
313
314         for (n = from; n < to; n = next) {
315                 next = MKDEV(MAJOR(n)+1, 0);
316                 if (next > to)
317                         next = to;
318                 kfree(__unregister_chrdev_region(MAJOR(n), MINOR(n), next - n));
319         }
320 }
321
322 int unregister_chrdev(unsigned int major, const char *name)
323 {
324         struct char_device_struct *cd;
325         cd = __unregister_chrdev_region(major, 0, 256);
326         if (cd && cd->cdev)
327                 cdev_del(cd->cdev);
328         kfree(cd);
329         return 0;
330 }
331
332 static DEFINE_SPINLOCK(cdev_lock);
333
334 static struct kobject *cdev_get(struct cdev *p)
335 {
336         struct module *owner = p->owner;
337         struct kobject *kobj;
338
339         if (owner && !try_module_get(owner))
340                 return NULL;
341         kobj = kobject_get(&p->kobj);
342         if (!kobj)
343                 module_put(owner);
344         return kobj;
345 }
346
347 void cdev_put(struct cdev *p)
348 {
349         if (p) {
350                 struct module *owner = p->owner;
351                 kobject_put(&p->kobj);
352                 module_put(owner);
353         }
354 }
355
356 /*
357  * Called every time a character special file is opened
358  */
359 int chrdev_open(struct inode * inode, struct file * filp)
360 {
361         struct cdev *p;
362         struct cdev *new = NULL;
363         int ret = 0;
364
365         spin_lock(&cdev_lock);
366         p = inode->i_cdev;
367         if (!p) {
368                 struct kobject *kobj;
369                 int idx;
370                 spin_unlock(&cdev_lock);
371                 kobj = kobj_lookup(cdev_map, inode->i_rdev, &idx);
372                 if (!kobj)
373                         return -ENXIO;
374                 new = container_of(kobj, struct cdev, kobj);
375                 spin_lock(&cdev_lock);
376                 p = inode->i_cdev;
377                 if (!p) {
378                         inode->i_cdev = p = new;
379                         inode->i_cindex = idx;
380                         list_add(&inode->i_devices, &p->list);
381                         new = NULL;
382                 } else if (!cdev_get(p))
383                         ret = -ENXIO;
384         } else if (!cdev_get(p))
385                 ret = -ENXIO;
386         spin_unlock(&cdev_lock);
387         cdev_put(new);
388         if (ret)
389                 return ret;
390         filp->f_op = fops_get(p->ops);
391         if (!filp->f_op) {
392                 cdev_put(p);
393                 return -ENXIO;
394         }
395         if (filp->f_op->open) {
396                 lock_kernel();
397                 ret = filp->f_op->open(inode,filp);
398                 unlock_kernel();
399         }
400         if (ret)
401                 cdev_put(p);
402         return ret;
403 }
404
405 void cd_forget(struct inode *inode)
406 {
407         spin_lock(&cdev_lock);
408         list_del_init(&inode->i_devices);
409         inode->i_cdev = NULL;
410         spin_unlock(&cdev_lock);
411 }
412
413 static void cdev_purge(struct cdev *cdev)
414 {
415         spin_lock(&cdev_lock);
416         while (!list_empty(&cdev->list)) {
417                 struct inode *inode;
418                 inode = container_of(cdev->list.next, struct inode, i_devices);
419                 list_del_init(&inode->i_devices);
420                 inode->i_cdev = NULL;
421         }
422         spin_unlock(&cdev_lock);
423 }
424
425 /*
426  * Dummy default file-operations: the only thing this does
427  * is contain the open that then fills in the correct operations
428  * depending on the special file...
429  */
430 const struct file_operations def_chr_fops = {
431         .open = chrdev_open,
432 };
433
434 static struct kobject *exact_match(dev_t dev, int *part, void *data)
435 {
436         struct cdev *p = data;
437         return &p->kobj;
438 }
439
440 static int exact_lock(dev_t dev, void *data)
441 {
442         struct cdev *p = data;
443         return cdev_get(p) ? 0 : -1;
444 }
445
446 /**
447  * cdev_add() - add a char device to the system
448  * @p: the cdev structure for the device
449  * @dev: the first device number for which this device is responsible
450  * @count: the number of consecutive minor numbers corresponding to this
451  *         device
452  *
453  * cdev_add() adds the device represented by @p to the system, making it
454  * live immediately.  A negative error code is returned on failure.
455  */
456 int cdev_add(struct cdev *p, dev_t dev, unsigned count)
457 {
458         p->dev = dev;
459         p->count = count;
460         return kobj_map(cdev_map, dev, count, NULL, exact_match, exact_lock, p);
461 }
462
463 static void cdev_unmap(dev_t dev, unsigned count)
464 {
465         kobj_unmap(cdev_map, dev, count);
466 }
467
468 /**
469  * cdev_del() - remove a cdev from the system
470  * @p: the cdev structure to be removed
471  *
472  * cdev_del() removes @p from the system, possibly freeing the structure
473  * itself.
474  */
475 void cdev_del(struct cdev *p)
476 {
477         cdev_unmap(p->dev, p->count);
478         kobject_put(&p->kobj);
479 }
480
481
482 static void cdev_default_release(struct kobject *kobj)
483 {
484         struct cdev *p = container_of(kobj, struct cdev, kobj);
485         cdev_purge(p);
486 }
487
488 static void cdev_dynamic_release(struct kobject *kobj)
489 {
490         struct cdev *p = container_of(kobj, struct cdev, kobj);
491         cdev_purge(p);
492         kfree(p);
493 }
494
495 static struct kobj_type ktype_cdev_default = {
496         .release        = cdev_default_release,
497 };
498
499 static struct kobj_type ktype_cdev_dynamic = {
500         .release        = cdev_dynamic_release,
501 };
502
503 /**
504  * cdev_alloc() - allocate a cdev structure
505  *
506  * Allocates and returns a cdev structure, or NULL on failure.
507  */
508 struct cdev *cdev_alloc(void)
509 {
510         struct cdev *p = kzalloc(sizeof(struct cdev), GFP_KERNEL);
511         if (p) {
512                 p->kobj.ktype = &ktype_cdev_dynamic;
513                 INIT_LIST_HEAD(&p->list);
514                 kobject_init(&p->kobj);
515         }
516         return p;
517 }
518
519 /**
520  * cdev_init() - initialize a cdev structure
521  * @cdev: the structure to initialize
522  * @fops: the file_operations for this device
523  *
524  * Initializes @cdev, remembering @fops, making it ready to add to the
525  * system with cdev_add().
526  */
527 void cdev_init(struct cdev *cdev, const struct file_operations *fops)
528 {
529         memset(cdev, 0, sizeof *cdev);
530         INIT_LIST_HEAD(&cdev->list);
531         cdev->kobj.ktype = &ktype_cdev_default;
532         kobject_init(&cdev->kobj);
533         cdev->ops = fops;
534 }
535
536 static struct kobject *base_probe(dev_t dev, int *part, void *data)
537 {
538         if (request_module("char-major-%d-%d", MAJOR(dev), MINOR(dev)) > 0)
539                 /* Make old-style 2.4 aliases work */
540                 request_module("char-major-%d", MAJOR(dev));
541         return NULL;
542 }
543
544 void __init chrdev_init(void)
545 {
546         cdev_map = kobj_map_init(base_probe, &chrdevs_lock);
547 }
548
549
550 /* Let modules do char dev stuff */
551 EXPORT_SYMBOL(register_chrdev_region);
552 EXPORT_SYMBOL(unregister_chrdev_region);
553 EXPORT_SYMBOL(alloc_chrdev_region);
554 EXPORT_SYMBOL(cdev_init);
555 EXPORT_SYMBOL(cdev_alloc);
556 EXPORT_SYMBOL(cdev_del);
557 EXPORT_SYMBOL(cdev_add);
558 EXPORT_SYMBOL(register_chrdev);
559 EXPORT_SYMBOL(unregister_chrdev);
560 EXPORT_SYMBOL(directly_mappable_cdev_bdi);