diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/devices.txt | 86 | ||||
| -rw-r--r-- | Documentation/isa.txt | 121 |
2 files changed, 149 insertions, 58 deletions
diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 87b4c5e82d39..4035eca87144 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -1,20 +1,17 @@ - LINUX ALLOCATED DEVICES (2.6+ version) - - Maintained by Alan Cox <device@lanana.org> - - Last revised: 6th April 2009 + LINUX ALLOCATED DEVICES (4.x+ version) This list is the Linux Device List, the official registry of allocated device numbers and /dev directory nodes for the Linux operating system. -The latest version of this list is available from -http://www.lanana.org/docs/device-list/ or -ftp://ftp.kernel.org/pub/linux/docs/device-list/. This version may be -newer than the one distributed with the Linux kernel. - -The LaTeX version of this document is no longer maintained. +The LaTeX version of this document is no longer maintained, nor is +the document that used to reside at lanana.org. This version in the +mainline Linux kernel is the master document. Updates shall be sent +as patches to the kernel maintainers (see the SubmittingPatches document). +Specifically explore the sections titled "CHAR and MISC DRIVERS", and +"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers +to involve for character and block devices. This document is included by reference into the Filesystem Hierarchy Standard (FHS). The FHS is available from http://www.pathname.com/fhs/. @@ -23,60 +20,33 @@ Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga platform only. Allocations marked (68k/Atari) apply to Linux/68k on the Atari platform only. -The symbol {2.6} means the allocation is obsolete and scheduled for -removal once kernel version 2.6 (or equivalent) is released. Some of these -allocations have already been removed. - -This document is in the public domain. The author requests, however, +This document is in the public domain. The authors requests, however, that semantically altered versions are not distributed without -permission of the author, assuming the author can be contacted without +permission of the authors, assuming the authors can be contacted without an unreasonable effort. -In particular, please don't sent patches for this list to Linus, at -least not without contacting me first. - -I do not have any information about these devices beyond what appears -on this list. Any such information requests will be deleted without -reply. - **** DEVICE DRIVERS AUTHORS PLEASE READ THIS **** -To have a major number allocated, or a minor number in situations -where that applies (e.g. busmice), please contact me with the -appropriate device information. Also, if you have additional -information regarding any of the devices listed below, or if I have -made a mistake, I would greatly appreciate a note. - -I do, however, make a few requests about the nature of your report. -This is necessary for me to be able to keep this list up to date and -correct in a timely manner. First of all, *please* send it to the -correct address... <device@lanana.org>. I receive hundreds of email -messages a day, so mail sent to other addresses may very well get lost -in the avalanche. Please put in a descriptive subject, so I can find -your mail again should I need to. Too many people send me email -saying just "device number request" in the subject. - -Second, please include a description of the device *in the same format -as this list*. The reason for this is that it is the only way I have -found to ensure I have all the requisite information to publish your -device and avoid conflicts. +Linux now has extensive support for dynamic allocation of device numbering +and can use sysfs and udev (systemd) to handle the naming needs. There are +still some exceptions in the serial and boot device area. Before asking +for a device number make sure you actually need one. -Third, please don't assume that the distributed version of the list is -up to date. Due to the number of registrations I have to maintain it -in "batch mode", so there is likely additional registrations that -haven't been listed yet. +To have a major number allocated, or a minor number in situations +where that applies (e.g. busmice), please submit a patch and send to +the authors as indicated above. -Fourth, remember that Linux now has extensive support for dynamic allocation -of device numbering and can use sysfs and udev to handle the naming needs. -There are still some exceptions in the serial and boot device area. Before -asking for a device number make sure you actually need one. +Keep the description of the device *in the same format +as this list*. The reason for this is that it is the only way we have +found to ensure we have all the requisite information to publish your +device and avoid conflicts. -Finally, sometimes I have to play "namespace police." Please don't be -offended. I often get submissions for /dev names that would be bound -to cause conflicts down the road. I am trying to avoid getting in a +Finally, sometimes we have to play "namespace police." Please don't be +offended. We often get submissions for /dev names that would be bound +to cause conflicts down the road. We are trying to avoid getting in a situation where we would have to suffer an incompatible forward -change. Therefore, please consult with me *before* you make your +change. Therefore, please consult with us *before* you make your device names and numbers in any way public, at least to the point where it would be at all difficult to get them changed. @@ -3099,9 +3069,9 @@ Your cooperation is appreciated. 129 = /dev/ipath_sma Device used by Subnet Management Agent 130 = /dev/ipath_diag Device used by diagnostics programs -234-239 UNASSIGNED - -240-254 char LOCAL/EXPERIMENTAL USE +234-254 char RESERVED FOR DYNAMIC ASSIGNMENT + Character devices that request a dynamic allocation of major number will + take numbers starting from 254 and downward. 240-254 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not diff --git a/Documentation/isa.txt b/Documentation/isa.txt new file mode 100644 index 000000000000..f232c26a40be --- /dev/null +++ b/Documentation/isa.txt @@ -0,0 +1,121 @@ +ISA Drivers +----------- + +The following text is adapted from the commit message of the initial +commit of the ISA bus driver authored by Rene Herman. + +During the recent "isa drivers using platform devices" discussion it was +pointed out that (ALSA) ISA drivers ran into the problem of not having +the option to fail driver load (device registration rather) upon not +finding their hardware due to a probe() error not being passed up +through the driver model. In the course of that, I suggested a separate +ISA bus might be best; Russell King agreed and suggested this bus could +use the .match() method for the actual device discovery. + +The attached does this. For this old non (generically) discoverable ISA +hardware only the driver itself can do discovery so as a difference with +the platform_bus, this isa_bus also distributes match() up to the +driver. + +As another difference: these devices only exist in the driver model due +to the driver creating them because it might want to drive them, meaning +that all device creation has been made internal as well. + +The usage model this provides is nice, and has been acked from the ALSA +side by Takashi Iwai and Jaroslav Kysela. The ALSA driver module_init's +now (for oldisa-only drivers) become: + +static int __init alsa_card_foo_init(void) +{ + return isa_register_driver(&snd_foo_isa_driver, SNDRV_CARDS); +} + +static void __exit alsa_card_foo_exit(void) +{ + isa_unregister_driver(&snd_foo_isa_driver); +} + +Quite like the other bus models therefore. This removes a lot of +duplicated init code from the ALSA ISA drivers. + +The passed in isa_driver struct is the regular driver struct embedding a +struct device_driver, the normal probe/remove/shutdown/suspend/resume +callbacks, and as indicated that .match callback. + +The "SNDRV_CARDS" you see being passed in is a "unsigned int ndev" +parameter, indicating how many devices to create and call our methods +with. + +The platform_driver callbacks are called with a platform_device param; +the isa_driver callbacks are being called with a "struct device *dev, +unsigned int id" pair directly -- with the device creation completely +internal to the bus it's much cleaner to not leak isa_dev's by passing +them in at all. The id is the only thing we ever want other then the +struct device * anyways, and it makes for nicer code in the callbacks as +well. + +With this additional .match() callback ISA drivers have all options. If +ALSA would want to keep the old non-load behaviour, it could stick all +of the old .probe in .match, which would only keep them registered after +everything was found to be present and accounted for. If it wanted the +behaviour of always loading as it inadvertently did for a bit after the +changeover to platform devices, it could just not provide a .match() and +do everything in .probe() as before. + +If it, as Takashi Iwai already suggested earlier as a way of following +the model from saner buses more closely, wants to load when a later bind +could conceivably succeed, it could use .match() for the prerequisites +(such as checking the user wants the card enabled and that port/irq/dma +values have been passed in) and .probe() for everything else. This is +the nicest model. + +To the code... + +This exports only two functions; isa_{,un}register_driver(). + +isa_register_driver() register's the struct device_driver, and then +loops over the passed in ndev creating devices and registering them. +This causes the bus match method to be called for them, which is: + +int isa_bus_match(struct device *dev, struct device_driver *driver) +{ + struct isa_driver *isa_driver = to_isa_driver(driver); + + if (dev->platform_data == isa_driver) { + if (!isa_driver->match || + isa_driver->match(dev, to_isa_dev(dev)->id)) + return 1; + dev->platform_data = NULL; + } + return 0; +} + +The first thing this does is check if this device is in fact one of this +driver's devices by seeing if the device's platform_data pointer is set +to this driver. Platform devices compare strings, but we don't need to +do that with everything being internal, so isa_register_driver() abuses +dev->platform_data as a isa_driver pointer which we can then check here. +I believe platform_data is available for this, but if rather not, moving +the isa_driver pointer to the private struct isa_dev is ofcourse fine as +well. + +Then, if the the driver did not provide a .match, it matches. If it did, +the driver match() method is called to determine a match. + +If it did _not_ match, dev->platform_data is reset to indicate this to +isa_register_driver which can then unregister the device again. + +If during all this, there's any error, or no devices matched at all +everything is backed out again and the error, or -ENODEV, is returned. + +isa_unregister_driver() just unregisters the matched devices and the +driver itself. + +module_isa_driver is a helper macro for ISA drivers which do not do +anything special in module init/exit. This eliminates a lot of +boilerplate code. Each module may only use this macro once, and calling +it replaces module_init and module_exit. + +max_num_isa_dev is a macro to determine the maximum possible number of +ISA devices which may be registered in the I/O port address space given +the address extent of the ISA devices. |