auxiliary.c 14 KB

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