1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * Copyright (c) 2019-2020 Intel Corporation |
4 | * |
5 | * Please see Documentation/driver-api/auxiliary_bus.rst for more information. |
6 | */ |
7 | |
8 | #ifndef _AUXILIARY_BUS_H_ |
9 | #define _AUXILIARY_BUS_H_ |
10 | |
11 | #include <linux/device.h> |
12 | #include <linux/mod_devicetable.h> |
13 | |
14 | /** |
15 | * DOC: DEVICE_LIFESPAN |
16 | * |
17 | * The registering driver is the entity that allocates memory for the |
18 | * auxiliary_device and registers it on the auxiliary bus. It is important to |
19 | * note that, as opposed to the platform bus, the registering driver is wholly |
20 | * responsible for the management of the memory used for the device object. |
21 | * |
22 | * To be clear the memory for the auxiliary_device is freed in the release() |
23 | * callback defined by the registering driver. The registering driver should |
24 | * only call auxiliary_device_delete() and then auxiliary_device_uninit() when |
25 | * it is done with the device. The release() function is then automatically |
26 | * called if and when other code releases their reference to the devices. |
27 | * |
28 | * A parent object, defined in the shared header file, contains the |
29 | * auxiliary_device. It also contains a pointer to the shared object(s), which |
30 | * also is defined in the shared header. Both the parent object and the shared |
31 | * object(s) are allocated by the registering driver. This layout allows the |
32 | * auxiliary_driver's registering module to perform a container_of() call to go |
33 | * from the pointer to the auxiliary_device, that is passed during the call to |
34 | * the auxiliary_driver's probe function, up to the parent object, and then |
35 | * have access to the shared object(s). |
36 | * |
37 | * The memory for the shared object(s) must have a lifespan equal to, or |
38 | * greater than, the lifespan of the memory for the auxiliary_device. The |
39 | * auxiliary_driver should only consider that the shared object is valid as |
40 | * long as the auxiliary_device is still registered on the auxiliary bus. It |
41 | * is up to the registering driver to manage (e.g. free or keep available) the |
42 | * memory for the shared object beyond the life of the auxiliary_device. |
43 | * |
44 | * The registering driver must unregister all auxiliary devices before its own |
45 | * driver.remove() is completed. An easy way to ensure this is to use the |
46 | * devm_add_action_or_reset() call to register a function against the parent |
47 | * device which unregisters the auxiliary device object(s). |
48 | * |
49 | * Finally, any operations which operate on the auxiliary devices must continue |
50 | * to function (if only to return an error) after the registering driver |
51 | * unregisters the auxiliary device. |
52 | */ |
53 | |
54 | /** |
55 | * struct auxiliary_device - auxiliary device object. |
56 | * @dev: Device, |
57 | * The release and parent fields of the device structure must be filled |
58 | * in |
59 | * @name: Match name found by the auxiliary device driver, |
60 | * @id: unique identitier if multiple devices of the same name are exported, |
61 | * |
62 | * An auxiliary_device represents a part of its parent device's functionality. |
63 | * It is given a name that, combined with the registering drivers |
64 | * KBUILD_MODNAME, creates a match_name that is used for driver binding, and an |
65 | * id that combined with the match_name provide a unique name to register with |
66 | * the bus subsystem. For example, a driver registering an auxiliary device is |
67 | * named 'foo_mod.ko' and the subdevice is named 'foo_dev'. The match name is |
68 | * therefore 'foo_mod.foo_dev'. |
69 | * |
70 | * Registering an auxiliary_device is a three-step process. |
71 | * |
72 | * First, a 'struct auxiliary_device' needs to be defined or allocated for each |
73 | * sub-device desired. The name, id, dev.release, and dev.parent fields of |
74 | * this structure must be filled in as follows. |
75 | * |
76 | * The 'name' field is to be given a name that is recognized by the auxiliary |
77 | * driver. If two auxiliary_devices with the same match_name, eg |
78 | * "foo_mod.foo_dev", are registered onto the bus, they must have unique id |
79 | * values (e.g. "x" and "y") so that the registered devices names are |
80 | * "foo_mod.foo_dev.x" and "foo_mod.foo_dev.y". If match_name + id are not |
81 | * unique, then the device_add fails and generates an error message. |
82 | * |
83 | * The auxiliary_device.dev.type.release or auxiliary_device.dev.release must |
84 | * be populated with a non-NULL pointer to successfully register the |
85 | * auxiliary_device. This release call is where resources associated with the |
86 | * auxiliary device must be free'ed. Because once the device is placed on the |
87 | * bus the parent driver can not tell what other code may have a reference to |
88 | * this data. |
89 | * |
90 | * The auxiliary_device.dev.parent should be set. Typically to the registering |
91 | * drivers device. |
92 | * |
93 | * Second, call auxiliary_device_init(), which checks several aspects of the |
94 | * auxiliary_device struct and performs a device_initialize(). After this step |
95 | * completes, any error state must have a call to auxiliary_device_uninit() in |
96 | * its resolution path. |
97 | * |
98 | * The third and final step in registering an auxiliary_device is to perform a |
99 | * call to auxiliary_device_add(), which sets the name of the device and adds |
100 | * the device to the bus. |
101 | * |
102 | * .. code-block:: c |
103 | * |
104 | * #define MY_DEVICE_NAME "foo_dev" |
105 | * |
106 | * ... |
107 | * |
108 | * struct auxiliary_device *my_aux_dev = my_aux_dev_alloc(xxx); |
109 | * |
110 | * // Step 1: |
111 | * my_aux_dev->name = MY_DEVICE_NAME; |
112 | * my_aux_dev->id = my_unique_id_alloc(xxx); |
113 | * my_aux_dev->dev.release = my_aux_dev_release; |
114 | * my_aux_dev->dev.parent = my_dev; |
115 | * |
116 | * // Step 2: |
117 | * if (auxiliary_device_init(my_aux_dev)) |
118 | * goto fail; |
119 | * |
120 | * // Step 3: |
121 | * if (auxiliary_device_add(my_aux_dev)) { |
122 | * auxiliary_device_uninit(my_aux_dev); |
123 | * goto fail; |
124 | * } |
125 | * |
126 | * ... |
127 | * |
128 | * |
129 | * Unregistering an auxiliary_device is a two-step process to mirror the |
130 | * register process. First call auxiliary_device_delete(), then call |
131 | * auxiliary_device_uninit(). |
132 | * |
133 | * .. code-block:: c |
134 | * |
135 | * auxiliary_device_delete(my_dev->my_aux_dev); |
136 | * auxiliary_device_uninit(my_dev->my_aux_dev); |
137 | */ |
138 | struct auxiliary_device { |
139 | struct device dev; |
140 | const char *name; |
141 | u32 id; |
142 | }; |
143 | |
144 | /** |
145 | * struct auxiliary_driver - Definition of an auxiliary bus driver |
146 | * @probe: Called when a matching device is added to the bus. |
147 | * @remove: Called when device is removed from the bus. |
148 | * @shutdown: Called at shut-down time to quiesce the device. |
149 | * @suspend: Called to put the device to sleep mode. Usually to a power state. |
150 | * @resume: Called to bring a device from sleep mode. |
151 | * @name: Driver name. |
152 | * @driver: Core driver structure. |
153 | * @id_table: Table of devices this driver should match on the bus. |
154 | * |
155 | * Auxiliary drivers follow the standard driver model convention, where |
156 | * discovery/enumeration is handled by the core, and drivers provide probe() |
157 | * and remove() methods. They support power management and shutdown |
158 | * notifications using the standard conventions. |
159 | * |
160 | * Auxiliary drivers register themselves with the bus by calling |
161 | * auxiliary_driver_register(). The id_table contains the match_names of |
162 | * auxiliary devices that a driver can bind with. |
163 | * |
164 | * .. code-block:: c |
165 | * |
166 | * static const struct auxiliary_device_id my_auxiliary_id_table[] = { |
167 | * { .name = "foo_mod.foo_dev" }, |
168 | * {}, |
169 | * }; |
170 | * |
171 | * MODULE_DEVICE_TABLE(auxiliary, my_auxiliary_id_table); |
172 | * |
173 | * struct auxiliary_driver my_drv = { |
174 | * .name = "myauxiliarydrv", |
175 | * .id_table = my_auxiliary_id_table, |
176 | * .probe = my_drv_probe, |
177 | * .remove = my_drv_remove |
178 | * }; |
179 | */ |
180 | struct auxiliary_driver { |
181 | int (*probe)(struct auxiliary_device *auxdev, const struct auxiliary_device_id *id); |
182 | void (*remove)(struct auxiliary_device *auxdev); |
183 | void (*shutdown)(struct auxiliary_device *auxdev); |
184 | int (*suspend)(struct auxiliary_device *auxdev, pm_message_t state); |
185 | int (*resume)(struct auxiliary_device *auxdev); |
186 | const char *name; |
187 | struct device_driver driver; |
188 | const struct auxiliary_device_id *id_table; |
189 | }; |
190 | |
191 | static inline void *auxiliary_get_drvdata(struct auxiliary_device *auxdev) |
192 | { |
193 | return dev_get_drvdata(dev: &auxdev->dev); |
194 | } |
195 | |
196 | static inline void auxiliary_set_drvdata(struct auxiliary_device *auxdev, void *data) |
197 | { |
198 | dev_set_drvdata(dev: &auxdev->dev, data); |
199 | } |
200 | |
201 | static inline struct auxiliary_device *to_auxiliary_dev(struct device *dev) |
202 | { |
203 | return container_of(dev, struct auxiliary_device, dev); |
204 | } |
205 | |
206 | static inline struct auxiliary_driver *to_auxiliary_drv(struct device_driver *drv) |
207 | { |
208 | return container_of(drv, struct auxiliary_driver, driver); |
209 | } |
210 | |
211 | int auxiliary_device_init(struct auxiliary_device *auxdev); |
212 | int __auxiliary_device_add(struct auxiliary_device *auxdev, const char *modname); |
213 | #define auxiliary_device_add(auxdev) __auxiliary_device_add(auxdev, KBUILD_MODNAME) |
214 | |
215 | static inline void auxiliary_device_uninit(struct auxiliary_device *auxdev) |
216 | { |
217 | put_device(dev: &auxdev->dev); |
218 | } |
219 | |
220 | static inline void auxiliary_device_delete(struct auxiliary_device *auxdev) |
221 | { |
222 | device_del(dev: &auxdev->dev); |
223 | } |
224 | |
225 | int __auxiliary_driver_register(struct auxiliary_driver *auxdrv, struct module *owner, |
226 | const char *modname); |
227 | #define auxiliary_driver_register(auxdrv) \ |
228 | __auxiliary_driver_register(auxdrv, THIS_MODULE, KBUILD_MODNAME) |
229 | |
230 | void auxiliary_driver_unregister(struct auxiliary_driver *auxdrv); |
231 | |
232 | /** |
233 | * module_auxiliary_driver() - Helper macro for registering an auxiliary driver |
234 | * @__auxiliary_driver: auxiliary driver struct |
235 | * |
236 | * Helper macro for auxiliary drivers which do not do anything special in |
237 | * module init/exit. This eliminates a lot of boilerplate. Each module may only |
238 | * use this macro once, and calling it replaces module_init() and module_exit() |
239 | * |
240 | * .. code-block:: c |
241 | * |
242 | * module_auxiliary_driver(my_drv); |
243 | */ |
244 | #define module_auxiliary_driver(__auxiliary_driver) \ |
245 | module_driver(__auxiliary_driver, auxiliary_driver_register, auxiliary_driver_unregister) |
246 | |
247 | struct auxiliary_device *auxiliary_find_device(struct device *start, |
248 | const void *data, |
249 | int (*match)(struct device *dev, const void *data)); |
250 | |
251 | #endif /* _AUXILIARY_BUS_H_ */ |
252 | |