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 | #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__ | |
9 | ||
10 | #include <linux/device.h> | |
11 | #include <linux/init.h> | |
7bbb79ff | 12 | #include <linux/slab.h> |
7de3697e DE |
13 | #include <linux/module.h> |
14 | #include <linux/pm_domain.h> | |
15 | #include <linux/pm_runtime.h> | |
16 | #include <linux/string.h> | |
17 | #include <linux/auxiliary_bus.h> | |
471b12c4 | 18 | #include "base.h" |
7de3697e | 19 | |
e1b51868 IW |
20 | /** |
21 | * DOC: PURPOSE | |
22 | * | |
23 | * In some subsystems, the functionality of the core device (PCI/ACPI/other) is | |
24 | * too complex for a single device to be managed by a monolithic driver (e.g. | |
25 | * Sound Open Firmware), multiple devices might implement a common intersection | |
26 | * of functionality (e.g. NICs + RDMA), or a driver may want to export an | |
27 | * interface for another subsystem to drive (e.g. SIOV Physical Function export | |
28 | * Virtual Function management). A split of the functionality into child- | |
29 | * devices representing sub-domains of functionality makes it possible to | |
30 | * compartmentalize, layer, and distribute domain-specific concerns via a Linux | |
31 | * device-driver model. | |
32 | * | |
33 | * An example for this kind of requirement is the audio subsystem where a | |
34 | * single IP is handling multiple entities such as HDMI, Soundwire, local | |
35 | * devices such as mics/speakers etc. The split for the core's functionality | |
36 | * can be arbitrary or be defined by the DSP firmware topology and include | |
37 | * hooks for test/debug. This allows for the audio core device to be minimal | |
38 | * and focused on hardware-specific control and communication. | |
39 | * | |
40 | * Each auxiliary_device represents a part of its parent functionality. The | |
41 | * generic behavior can be extended and specialized as needed by encapsulating | |
42 | * an auxiliary_device within other domain-specific structures and the use of | |
43 | * .ops callbacks. Devices on the auxiliary bus do not share any structures and | |
44 | * the use of a communication channel with the parent is domain-specific. | |
45 | * | |
46 | * Note that ops are intended as a way to augment instance behavior within a | |
47 | * class of auxiliary devices, it is not the mechanism for exporting common | |
48 | * infrastructure from the parent. Consider EXPORT_SYMBOL_NS() to convey | |
49 | * infrastructure from the parent module to the auxiliary module(s). | |
50 | */ | |
51 | ||
52 | /** | |
53 | * DOC: USAGE | |
54 | * | |
55 | * The auxiliary bus is to be used when a driver and one or more kernel | |
56 | * modules, who share a common header file with the driver, need a mechanism to | |
57 | * connect and provide access to a shared object allocated by the | |
58 | * auxiliary_device's registering driver. The registering driver for the | |
59 | * auxiliary_device(s) and the kernel module(s) registering auxiliary_drivers | |
60 | * can be from the same subsystem, or from multiple subsystems. | |
61 | * | |
62 | * The emphasis here is on a common generic interface that keeps subsystem | |
63 | * customization out of the bus infrastructure. | |
64 | * | |
65 | * One example is a PCI network device that is RDMA-capable and exports a child | |
66 | * device to be driven by an auxiliary_driver in the RDMA subsystem. The PCI | |
67 | * driver allocates and registers an auxiliary_device for each physical | |
68 | * function on the NIC. The RDMA driver registers an auxiliary_driver that | |
69 | * claims each of these auxiliary_devices. This conveys data/ops published by | |
70 | * the parent PCI device/driver to the RDMA auxiliary_driver. | |
71 | * | |
72 | * Another use case is for the PCI device to be split out into multiple sub | |
73 | * functions. For each sub function an auxiliary_device is created. A PCI sub | |
74 | * function driver binds to such devices that creates its own one or more class | |
75 | * devices. A PCI sub function auxiliary device is likely to be contained in a | |
76 | * struct with additional attributes such as user defined sub function number | |
77 | * and optional attributes such as resources and a link to the parent device. | |
78 | * These attributes could be used by systemd/udev; and hence should be | |
79 | * initialized before a driver binds to an auxiliary_device. | |
80 | * | |
81 | * A key requirement for utilizing the auxiliary bus is that there is no | |
82 | * dependency on a physical bus, device, register accesses or regmap support. | |
83 | * These individual devices split from the core cannot live on the platform bus | |
84 | * as they are not physical devices that are controlled by DT/ACPI. The same | |
85 | * argument applies for not using MFD in this scenario as MFD relies on | |
86 | * individual function devices being physical devices. | |
87 | */ | |
88 | ||
89 | /** | |
90 | * DOC: EXAMPLE | |
91 | * | |
92 | * Auxiliary devices are created and registered by a subsystem-level core | |
93 | * device that needs to break up its functionality into smaller fragments. One | |
94 | * way to extend the scope of an auxiliary_device is to encapsulate it within a | |
95 | * domain- pecific structure defined by the parent device. This structure | |
96 | * contains the auxiliary_device and any associated shared data/callbacks | |
97 | * needed to establish the connection with the parent. | |
98 | * | |
99 | * An example is: | |
100 | * | |
101 | * .. code-block:: c | |
102 | * | |
103 | * struct foo { | |
104 | * struct auxiliary_device auxdev; | |
105 | * void (*connect)(struct auxiliary_device *auxdev); | |
106 | * void (*disconnect)(struct auxiliary_device *auxdev); | |
107 | * void *data; | |
108 | * }; | |
109 | * | |
110 | * The parent device then registers the auxiliary_device by calling | |
111 | * auxiliary_device_init(), and then auxiliary_device_add(), with the pointer | |
112 | * to the auxdev member of the above structure. The parent provides a name for | |
113 | * the auxiliary_device that, combined with the parent's KBUILD_MODNAME, | |
114 | * creates a match_name that is be used for matching and binding with a driver. | |
115 | * | |
116 | * Whenever an auxiliary_driver is registered, based on the match_name, the | |
117 | * auxiliary_driver's probe() is invoked for the matching devices. The | |
118 | * auxiliary_driver can also be encapsulated inside custom drivers that make | |
119 | * the core device's functionality extensible by adding additional | |
120 | * domain-specific ops as follows: | |
121 | * | |
122 | * .. code-block:: c | |
123 | * | |
124 | * struct my_ops { | |
125 | * void (*send)(struct auxiliary_device *auxdev); | |
126 | * void (*receive)(struct auxiliary_device *auxdev); | |
127 | * }; | |
128 | * | |
129 | * | |
130 | * struct my_driver { | |
131 | * struct auxiliary_driver auxiliary_drv; | |
132 | * const struct my_ops ops; | |
133 | * }; | |
134 | * | |
135 | * An example of this type of usage is: | |
136 | * | |
137 | * .. code-block:: c | |
138 | * | |
139 | * const struct auxiliary_device_id my_auxiliary_id_table[] = { | |
140 | * { .name = "foo_mod.foo_dev" }, | |
141 | * { }, | |
142 | * }; | |
143 | * | |
144 | * const struct my_ops my_custom_ops = { | |
145 | * .send = my_tx, | |
146 | * .receive = my_rx, | |
147 | * }; | |
148 | * | |
149 | * const struct my_driver my_drv = { | |
150 | * .auxiliary_drv = { | |
151 | * .name = "myauxiliarydrv", | |
152 | * .id_table = my_auxiliary_id_table, | |
153 | * .probe = my_probe, | |
154 | * .remove = my_remove, | |
155 | * .shutdown = my_shutdown, | |
156 | * }, | |
157 | * .ops = my_custom_ops, | |
158 | * }; | |
159 | */ | |
160 | ||
7de3697e DE |
161 | static const struct auxiliary_device_id *auxiliary_match_id(const struct auxiliary_device_id *id, |
162 | const struct auxiliary_device *auxdev) | |
163 | { | |
164 | for (; id->name[0]; id++) { | |
165 | const char *p = strrchr(dev_name(&auxdev->dev), '.'); | |
166 | int match_size; | |
167 | ||
168 | if (!p) | |
169 | continue; | |
170 | match_size = p - dev_name(&auxdev->dev); | |
171 | ||
172 | /* use dev_name(&auxdev->dev) prefix before last '.' char to match to */ | |
173 | if (strlen(id->name) == match_size && | |
174 | !strncmp(dev_name(&auxdev->dev), id->name, match_size)) | |
175 | return id; | |
176 | } | |
177 | return NULL; | |
178 | } | |
179 | ||
180 | static int auxiliary_match(struct device *dev, struct device_driver *drv) | |
181 | { | |
182 | struct auxiliary_device *auxdev = to_auxiliary_dev(dev); | |
183 | struct auxiliary_driver *auxdrv = to_auxiliary_drv(drv); | |
184 | ||
185 | return !!auxiliary_match_id(auxdrv->id_table, auxdev); | |
186 | } | |
187 | ||
188 | static int auxiliary_uevent(struct device *dev, struct kobj_uevent_env *env) | |
189 | { | |
190 | const char *name, *p; | |
191 | ||
192 | name = dev_name(dev); | |
193 | p = strrchr(name, '.'); | |
194 | ||
0d2bf11a GKH |
195 | return add_uevent_var(env, "MODALIAS=%s%.*s", AUXILIARY_MODULE_PREFIX, |
196 | (int)(p - name), name); | |
7de3697e DE |
197 | } |
198 | ||
199 | static const struct dev_pm_ops auxiliary_dev_pm_ops = { | |
200 | SET_RUNTIME_PM_OPS(pm_generic_runtime_suspend, pm_generic_runtime_resume, NULL) | |
201 | SET_SYSTEM_SLEEP_PM_OPS(pm_generic_suspend, pm_generic_resume) | |
202 | }; | |
203 | ||
204 | static int auxiliary_bus_probe(struct device *dev) | |
205 | { | |
206 | struct auxiliary_driver *auxdrv = to_auxiliary_drv(dev->driver); | |
207 | struct auxiliary_device *auxdev = to_auxiliary_dev(dev); | |
208 | int ret; | |
209 | ||
210 | ret = dev_pm_domain_attach(dev, true); | |
211 | if (ret) { | |
212 | dev_warn(dev, "Failed to attach to PM Domain : %d\n", ret); | |
213 | return ret; | |
214 | } | |
215 | ||
216 | ret = auxdrv->probe(auxdev, auxiliary_match_id(auxdrv->id_table, auxdev)); | |
217 | if (ret) | |
218 | dev_pm_domain_detach(dev, true); | |
219 | ||
220 | return ret; | |
221 | } | |
222 | ||
fc7a6209 | 223 | static void auxiliary_bus_remove(struct device *dev) |
7de3697e DE |
224 | { |
225 | struct auxiliary_driver *auxdrv = to_auxiliary_drv(dev->driver); | |
226 | struct auxiliary_device *auxdev = to_auxiliary_dev(dev); | |
7de3697e DE |
227 | |
228 | if (auxdrv->remove) | |
8142a46c | 229 | auxdrv->remove(auxdev); |
7de3697e | 230 | dev_pm_domain_detach(dev, true); |
7de3697e DE |
231 | } |
232 | ||
233 | static void auxiliary_bus_shutdown(struct device *dev) | |
234 | { | |
784b2c48 DJ |
235 | struct auxiliary_driver *auxdrv = NULL; |
236 | struct auxiliary_device *auxdev; | |
237 | ||
238 | if (dev->driver) { | |
239 | auxdrv = to_auxiliary_drv(dev->driver); | |
240 | auxdev = to_auxiliary_dev(dev); | |
241 | } | |
7de3697e | 242 | |
784b2c48 | 243 | if (auxdrv && auxdrv->shutdown) |
7de3697e DE |
244 | auxdrv->shutdown(auxdev); |
245 | } | |
246 | ||
247 | static struct bus_type auxiliary_bus_type = { | |
248 | .name = "auxiliary", | |
249 | .probe = auxiliary_bus_probe, | |
250 | .remove = auxiliary_bus_remove, | |
251 | .shutdown = auxiliary_bus_shutdown, | |
252 | .match = auxiliary_match, | |
253 | .uevent = auxiliary_uevent, | |
254 | .pm = &auxiliary_dev_pm_ops, | |
255 | }; | |
256 | ||
257 | /** | |
258 | * auxiliary_device_init - check auxiliary_device and initialize | |
259 | * @auxdev: auxiliary device struct | |
260 | * | |
b2477038 | 261 | * This is the second step in the three-step process to register an |
0d2bf11a | 262 | * auxiliary_device. |
7de3697e | 263 | * |
0d2bf11a GKH |
264 | * When this function returns an error code, then the device_initialize will |
265 | * *not* have been performed, and the caller will be responsible to free any | |
266 | * memory allocated for the auxiliary_device in the error path directly. | |
7de3697e | 267 | * |
0d2bf11a GKH |
268 | * It returns 0 on success. On success, the device_initialize has been |
269 | * performed. After this point any error unwinding will need to include a call | |
270 | * to auxiliary_device_uninit(). In this post-initialize error scenario, a call | |
271 | * to the device's .release callback will be triggered, and all memory clean-up | |
272 | * is expected to be handled there. | |
7de3697e DE |
273 | */ |
274 | int auxiliary_device_init(struct auxiliary_device *auxdev) | |
275 | { | |
276 | struct device *dev = &auxdev->dev; | |
277 | ||
278 | if (!dev->parent) { | |
279 | pr_err("auxiliary_device has a NULL dev->parent\n"); | |
280 | return -EINVAL; | |
281 | } | |
282 | ||
283 | if (!auxdev->name) { | |
284 | pr_err("auxiliary_device has a NULL name\n"); | |
285 | return -EINVAL; | |
286 | } | |
287 | ||
288 | dev->bus = &auxiliary_bus_type; | |
289 | device_initialize(&auxdev->dev); | |
290 | return 0; | |
291 | } | |
292 | EXPORT_SYMBOL_GPL(auxiliary_device_init); | |
293 | ||
294 | /** | |
295 | * __auxiliary_device_add - add an auxiliary bus device | |
296 | * @auxdev: auxiliary bus device to add to the bus | |
297 | * @modname: name of the parent device's driver module | |
298 | * | |
b2477038 | 299 | * This is the third step in the three-step process to register an |
0d2bf11a | 300 | * auxiliary_device. |
7de3697e | 301 | * |
0d2bf11a GKH |
302 | * This function must be called after a successful call to |
303 | * auxiliary_device_init(), which will perform the device_initialize. This | |
304 | * means that if this returns an error code, then a call to | |
305 | * auxiliary_device_uninit() must be performed so that the .release callback | |
306 | * will be triggered to free the memory associated with the auxiliary_device. | |
7de3697e | 307 | * |
0d2bf11a GKH |
308 | * The expectation is that users will call the "auxiliary_device_add" macro so |
309 | * that the caller's KBUILD_MODNAME is automatically inserted for the modname | |
310 | * parameter. Only if a user requires a custom name would this version be | |
311 | * called directly. | |
7de3697e DE |
312 | */ |
313 | int __auxiliary_device_add(struct auxiliary_device *auxdev, const char *modname) | |
314 | { | |
315 | struct device *dev = &auxdev->dev; | |
316 | int ret; | |
317 | ||
318 | if (!modname) { | |
0d2bf11a | 319 | dev_err(dev, "auxiliary device modname is NULL\n"); |
7de3697e DE |
320 | return -EINVAL; |
321 | } | |
322 | ||
323 | ret = dev_set_name(dev, "%s.%s.%d", modname, auxdev->name, auxdev->id); | |
324 | if (ret) { | |
0d2bf11a | 325 | dev_err(dev, "auxiliary device dev_set_name failed: %d\n", ret); |
7de3697e DE |
326 | return ret; |
327 | } | |
328 | ||
329 | ret = device_add(dev); | |
330 | if (ret) | |
331 | dev_err(dev, "adding auxiliary device failed!: %d\n", ret); | |
332 | ||
333 | return ret; | |
334 | } | |
335 | EXPORT_SYMBOL_GPL(__auxiliary_device_add); | |
336 | ||
337 | /** | |
338 | * auxiliary_find_device - auxiliary device iterator for locating a particular device. | |
339 | * @start: Device to begin with | |
340 | * @data: Data to pass to match function | |
341 | * @match: Callback function to check device | |
342 | * | |
343 | * This function returns a reference to a device that is 'found' | |
344 | * for later use, as determined by the @match callback. | |
345 | * | |
8a2d6ffe IW |
346 | * The reference returned should be released with put_device(). |
347 | * | |
7de3697e DE |
348 | * The callback should return 0 if the device doesn't match and non-zero |
349 | * if it does. If the callback returns non-zero, this function will | |
350 | * return to the caller and not iterate over any more devices. | |
351 | */ | |
0d2bf11a GKH |
352 | struct auxiliary_device *auxiliary_find_device(struct device *start, |
353 | const void *data, | |
354 | int (*match)(struct device *dev, const void *data)) | |
7de3697e DE |
355 | { |
356 | struct device *dev; | |
357 | ||
358 | dev = bus_find_device(&auxiliary_bus_type, start, data, match); | |
359 | if (!dev) | |
360 | return NULL; | |
361 | ||
362 | return to_auxiliary_dev(dev); | |
363 | } | |
364 | EXPORT_SYMBOL_GPL(auxiliary_find_device); | |
365 | ||
366 | /** | |
367 | * __auxiliary_driver_register - register a driver for auxiliary bus devices | |
368 | * @auxdrv: auxiliary_driver structure | |
369 | * @owner: owning module/driver | |
370 | * @modname: KBUILD_MODNAME for parent driver | |
05021dca IW |
371 | * |
372 | * The expectation is that users will call the "auxiliary_driver_register" | |
373 | * macro so that the caller's KBUILD_MODNAME is automatically inserted for the | |
374 | * modname parameter. Only if a user requires a custom name would this version | |
375 | * be called directly. | |
7de3697e | 376 | */ |
0d2bf11a GKH |
377 | int __auxiliary_driver_register(struct auxiliary_driver *auxdrv, |
378 | struct module *owner, const char *modname) | |
7de3697e | 379 | { |
4afa0c22 PU |
380 | int ret; |
381 | ||
7de3697e DE |
382 | if (WARN_ON(!auxdrv->probe) || WARN_ON(!auxdrv->id_table)) |
383 | return -EINVAL; | |
384 | ||
385 | if (auxdrv->name) | |
0d2bf11a GKH |
386 | auxdrv->driver.name = kasprintf(GFP_KERNEL, "%s.%s", modname, |
387 | auxdrv->name); | |
7de3697e DE |
388 | else |
389 | auxdrv->driver.name = kasprintf(GFP_KERNEL, "%s", modname); | |
390 | if (!auxdrv->driver.name) | |
391 | return -ENOMEM; | |
392 | ||
393 | auxdrv->driver.owner = owner; | |
394 | auxdrv->driver.bus = &auxiliary_bus_type; | |
395 | auxdrv->driver.mod_name = modname; | |
396 | ||
4afa0c22 PU |
397 | ret = driver_register(&auxdrv->driver); |
398 | if (ret) | |
399 | kfree(auxdrv->driver.name); | |
400 | ||
401 | return ret; | |
7de3697e DE |
402 | } |
403 | EXPORT_SYMBOL_GPL(__auxiliary_driver_register); | |
404 | ||
405 | /** | |
406 | * auxiliary_driver_unregister - unregister a driver | |
407 | * @auxdrv: auxiliary_driver structure | |
408 | */ | |
409 | void auxiliary_driver_unregister(struct auxiliary_driver *auxdrv) | |
410 | { | |
411 | driver_unregister(&auxdrv->driver); | |
412 | kfree(auxdrv->driver.name); | |
413 | } | |
414 | EXPORT_SYMBOL_GPL(auxiliary_driver_unregister); | |
415 | ||
471b12c4 | 416 | void __init auxiliary_bus_init(void) |
7de3697e | 417 | { |
471b12c4 | 418 | WARN_ON(bus_register(&auxiliary_bus_type)); |
7de3697e | 419 | } |