| 1 | ===========
|
| 2 | ISA Drivers
|
| 3 | ===========
|
| 4 |
|
| 5 | The following text is adapted from the commit message of the initial
|
| 6 | commit of the ISA bus driver authored by Rene Herman.
|
| 7 |
|
| 8 | During the recent "isa drivers using platform devices" discussion it was
|
| 9 | pointed out that (ALSA) ISA drivers ran into the problem of not having
|
| 10 | the option to fail driver load (device registration rather) upon not
|
| 11 | finding their hardware due to a probe() error not being passed up
|
| 12 | through the driver model. In the course of that, I suggested a separate
|
| 13 | ISA bus might be best; Russell King agreed and suggested this bus could
|
| 14 | use the .match() method for the actual device discovery.
|
| 15 |
|
| 16 | The attached does this. For this old non (generically) discoverable ISA
|
| 17 | hardware only the driver itself can do discovery so as a difference with
|
| 18 | the platform_bus, this isa_bus also distributes match() up to the
|
| 19 | driver.
|
| 20 |
|
| 21 | As another difference: these devices only exist in the driver model due
|
| 22 | to the driver creating them because it might want to drive them, meaning
|
| 23 | that all device creation has been made internal as well.
|
| 24 |
|
| 25 | The usage model this provides is nice, and has been acked from the ALSA
|
| 26 | side by Takashi Iwai and Jaroslav Kysela. The ALSA driver module_init's
|
| 27 | now (for oldisa-only drivers) become::
|
| 28 |
|
| 29 | static int __init alsa_card_foo_init(void)
|
| 30 | {
|
| 31 | return isa_register_driver(&snd_foo_isa_driver, SNDRV_CARDS);
|
| 32 | }
|
| 33 |
|
| 34 | static void __exit alsa_card_foo_exit(void)
|
| 35 | {
|
| 36 | isa_unregister_driver(&snd_foo_isa_driver);
|
| 37 | }
|
| 38 |
|
| 39 | Quite like the other bus models therefore. This removes a lot of
|
| 40 | duplicated init code from the ALSA ISA drivers.
|
| 41 |
|
| 42 | The passed in isa_driver struct is the regular driver struct embedding a
|
| 43 | struct device_driver, the normal probe/remove/shutdown/suspend/resume
|
| 44 | callbacks, and as indicated that .match callback.
|
| 45 |
|
| 46 | The "SNDRV_CARDS" you see being passed in is a "unsigned int ndev"
|
| 47 | parameter, indicating how many devices to create and call our methods
|
| 48 | with.
|
| 49 |
|
| 50 | The platform_driver callbacks are called with a platform_device param;
|
| 51 | the isa_driver callbacks are being called with a ``struct device *dev,
|
| 52 | unsigned int id`` pair directly -- with the device creation completely
|
| 53 | internal to the bus it's much cleaner to not leak isa_dev's by passing
|
| 54 | them in at all. The id is the only thing we ever want other then the
|
| 55 | struct device anyways, and it makes for nicer code in the callbacks as
|
| 56 | well.
|
| 57 |
|
| 58 | With this additional .match() callback ISA drivers have all options. If
|
| 59 | ALSA would want to keep the old non-load behaviour, it could stick all
|
| 60 | of the old .probe in .match, which would only keep them registered after
|
| 61 | everything was found to be present and accounted for. If it wanted the
|
| 62 | behaviour of always loading as it inadvertently did for a bit after the
|
| 63 | changeover to platform devices, it could just not provide a .match() and
|
| 64 | do everything in .probe() as before.
|
| 65 |
|
| 66 | If it, as Takashi Iwai already suggested earlier as a way of following
|
| 67 | the model from saner buses more closely, wants to load when a later bind
|
| 68 | could conceivably succeed, it could use .match() for the prerequisites
|
| 69 | (such as checking the user wants the card enabled and that port/irq/dma
|
| 70 | values have been passed in) and .probe() for everything else. This is
|
| 71 | the nicest model.
|
| 72 |
|
| 73 | To the code...
|
| 74 |
|
| 75 | This exports only two functions; isa_{,un}register_driver().
|
| 76 |
|
| 77 | isa_register_driver() register's the struct device_driver, and then
|
| 78 | loops over the passed in ndev creating devices and registering them.
|
| 79 | This causes the bus match method to be called for them, which is::
|
| 80 |
|
| 81 | int isa_bus_match(struct device *dev, struct device_driver *driver)
|
| 82 | {
|
| 83 | struct isa_driver *isa_driver = to_isa_driver(driver);
|
| 84 |
|
| 85 | if (dev->platform_data == isa_driver) {
|
| 86 | if (!isa_driver->match ||
|
| 87 | isa_driver->match(dev, to_isa_dev(dev)->id))
|
| 88 | return 1;
|
| 89 | dev->platform_data = NULL;
|
| 90 | }
|
| 91 | return 0;
|
| 92 | }
|
| 93 |
|
| 94 | The first thing this does is check if this device is in fact one of this
|
| 95 | driver's devices by seeing if the device's platform_data pointer is set
|
| 96 | to this driver. Platform devices compare strings, but we don't need to
|
| 97 | do that with everything being internal, so isa_register_driver() abuses
|
| 98 | dev->platform_data as a isa_driver pointer which we can then check here.
|
| 99 | I believe platform_data is available for this, but if rather not, moving
|
| 100 | the isa_driver pointer to the private struct isa_dev is ofcourse fine as
|
| 101 | well.
|
| 102 |
|
| 103 | Then, if the driver did not provide a .match, it matches. If it did,
|
| 104 | the driver match() method is called to determine a match.
|
| 105 |
|
| 106 | If it did **not** match, dev->platform_data is reset to indicate this to
|
| 107 | isa_register_driver which can then unregister the device again.
|
| 108 |
|
| 109 | If during all this, there's any error, or no devices matched at all
|
| 110 | everything is backed out again and the error, or -ENODEV, is returned.
|
| 111 |
|
| 112 | isa_unregister_driver() just unregisters the matched devices and the
|
| 113 | driver itself.
|
| 114 |
|
| 115 | module_isa_driver is a helper macro for ISA drivers which do not do
|
| 116 | anything special in module init/exit. This eliminates a lot of
|
| 117 | boilerplate code. Each module may only use this macro once, and calling
|
| 118 | it replaces module_init and module_exit.
|
| 119 |
|
| 120 | max_num_isa_dev is a macro to determine the maximum possible number of
|
| 121 | ISA devices which may be registered in the I/O port address space given
|
| 122 | the address extent of the ISA devices.
|