Commit | Line | Data |
---|---|---|
7de3697e DE |
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> | |
7de3697e | 13 | |
e1b51868 IW |
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 | */ | |
7de3697e DE |
138 | struct auxiliary_device { |
139 | struct device dev; | |
140 | const char *name; | |
141 | u32 id; | |
142 | }; | |
143 | ||
e1b51868 IW |
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 | */ | |
7de3697e DE |
180 | struct auxiliary_driver { |
181 | int (*probe)(struct auxiliary_device *auxdev, const struct auxiliary_device_id *id); | |
8142a46c | 182 | void (*remove)(struct auxiliary_device *auxdev); |
7de3697e DE |
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 | ||
365481e4 DB |
191 | static inline void *auxiliary_get_drvdata(struct auxiliary_device *auxdev) |
192 | { | |
193 | return dev_get_drvdata(&auxdev->dev); | |
194 | } | |
195 | ||
196 | static inline void auxiliary_set_drvdata(struct auxiliary_device *auxdev, void *data) | |
197 | { | |
198 | dev_set_drvdata(&auxdev->dev, data); | |
199 | } | |
200 | ||
7de3697e DE |
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(&auxdev->dev); | |
218 | } | |
219 | ||
220 | static inline void auxiliary_device_delete(struct auxiliary_device *auxdev) | |
221 | { | |
222 | device_del(&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() | |
14866a7d IW |
239 | * |
240 | * .. code-block:: c | |
241 | * | |
242 | * module_auxiliary_driver(my_drv); | |
7de3697e DE |
243 | */ |
244 | #define module_auxiliary_driver(__auxiliary_driver) \ | |
245 | module_driver(__auxiliary_driver, auxiliary_driver_register, auxiliary_driver_unregister) | |
246 | ||
0d2bf11a GKH |
247 | struct auxiliary_device *auxiliary_find_device(struct device *start, |
248 | const void *data, | |
249 | int (*match)(struct device *dev, const void *data)); | |
7de3697e DE |
250 | |
251 | #endif /* _AUXILIARY_BUS_H_ */ |