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