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> |
12 | #include <linux/slab.h> |
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> |
18 | #include "base.h" |
19 | |
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 | |
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(dev: &auxdev->dev), '.'); |
166 | int match_size; |
167 | |
168 | if (!p) |
169 | continue; |
170 | match_size = p - dev_name(dev: &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(dev: &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(id: auxdrv->id_table, auxdev); |
186 | } |
187 | |
188 | static int auxiliary_uevent(const 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 | |
195 | return add_uevent_var(env, format: "MODALIAS=%s%.*s" , AUXILIARY_MODULE_PREFIX, |
196 | (int)(p - name), name); |
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(drv: dev->driver); |
207 | struct auxiliary_device *auxdev = to_auxiliary_dev(dev); |
208 | int ret; |
209 | |
210 | ret = dev_pm_domain_attach(dev, power_on: 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(id: auxdrv->id_table, auxdev)); |
217 | if (ret) |
218 | dev_pm_domain_detach(dev, power_off: true); |
219 | |
220 | return ret; |
221 | } |
222 | |
223 | static void auxiliary_bus_remove(struct device *dev) |
224 | { |
225 | struct auxiliary_driver *auxdrv = to_auxiliary_drv(drv: dev->driver); |
226 | struct auxiliary_device *auxdev = to_auxiliary_dev(dev); |
227 | |
228 | if (auxdrv->remove) |
229 | auxdrv->remove(auxdev); |
230 | dev_pm_domain_detach(dev, power_off: true); |
231 | } |
232 | |
233 | static void auxiliary_bus_shutdown(struct device *dev) |
234 | { |
235 | struct auxiliary_driver *auxdrv = NULL; |
236 | struct auxiliary_device *auxdev; |
237 | |
238 | if (dev->driver) { |
239 | auxdrv = to_auxiliary_drv(drv: dev->driver); |
240 | auxdev = to_auxiliary_dev(dev); |
241 | } |
242 | |
243 | if (auxdrv && auxdrv->shutdown) |
244 | auxdrv->shutdown(auxdev); |
245 | } |
246 | |
247 | static const 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 | * |
261 | * This is the second step in the three-step process to register an |
262 | * auxiliary_device. |
263 | * |
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. |
267 | * |
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. |
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(dev: &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 | * |
299 | * This is the third step in the three-step process to register an |
300 | * auxiliary_device. |
301 | * |
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. |
307 | * |
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. |
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) { |
319 | dev_err(dev, "auxiliary device modname is NULL\n" ); |
320 | return -EINVAL; |
321 | } |
322 | |
323 | ret = dev_set_name(dev, name: "%s.%s.%d" , modname, auxdev->name, auxdev->id); |
324 | if (ret) { |
325 | dev_err(dev, "auxiliary device dev_set_name failed: %d\n" , ret); |
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 | * |
346 | * The reference returned should be released with put_device(). |
347 | * |
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 | */ |
352 | struct auxiliary_device *auxiliary_find_device(struct device *start, |
353 | const void *data, |
354 | int (*match)(struct device *dev, const void *data)) |
355 | { |
356 | struct device *dev; |
357 | |
358 | dev = bus_find_device(bus: &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 |
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. |
376 | */ |
377 | int __auxiliary_driver_register(struct auxiliary_driver *auxdrv, |
378 | struct module *owner, const char *modname) |
379 | { |
380 | int ret; |
381 | |
382 | if (WARN_ON(!auxdrv->probe) || WARN_ON(!auxdrv->id_table)) |
383 | return -EINVAL; |
384 | |
385 | if (auxdrv->name) |
386 | auxdrv->driver.name = kasprintf(GFP_KERNEL, fmt: "%s.%s" , modname, |
387 | auxdrv->name); |
388 | else |
389 | auxdrv->driver.name = kasprintf(GFP_KERNEL, fmt: "%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 | |
397 | ret = driver_register(drv: &auxdrv->driver); |
398 | if (ret) |
399 | kfree(objp: auxdrv->driver.name); |
400 | |
401 | return ret; |
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(drv: &auxdrv->driver); |
412 | kfree(objp: auxdrv->driver.name); |
413 | } |
414 | EXPORT_SYMBOL_GPL(auxiliary_driver_unregister); |
415 | |
416 | void __init auxiliary_bus_init(void) |
417 | { |
418 | WARN_ON(bus_register(&auxiliary_bus_type)); |
419 | } |
420 | |