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/device-id/auxiliary.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 * @sysfs: embedded struct which hold all sysfs related fields,
62 * @sysfs.irqs: irqs xarray contains irq indices which are used by the device,
63 * @sysfs.lock: Synchronize irq sysfs creation,
64 * @sysfs.irq_dir_exists: whether "irqs" directory exists,
65 * @registration_data_rust: private data owned by the registering (parent)
66 * driver; valid for as long as the device is
67 * registered with the driver core,
68 *
69 * An auxiliary_device represents a part of its parent device's functionality.
70 * It is given a name that, combined with the registering drivers
71 * KBUILD_MODNAME, creates a match_name that is used for driver binding, and an
72 * id that combined with the match_name provide a unique name to register with
73 * the bus subsystem. For example, a driver registering an auxiliary device is
74 * named 'foo_mod.ko' and the subdevice is named 'foo_dev'. The match name is
75 * therefore 'foo_mod.foo_dev'.
76 *
77 * Registering an auxiliary_device is a three-step process.
78 *
79 * First, a 'struct auxiliary_device' needs to be defined or allocated for each
80 * sub-device desired. The name, id, dev.release, and dev.parent fields of
81 * this structure must be filled in as follows.
82 *
83 * The 'name' field is to be given a name that is recognized by the auxiliary
84 * driver. If two auxiliary_devices with the same match_name, eg
85 * "foo_mod.foo_dev", are registered onto the bus, they must have unique id
86 * values (e.g. "x" and "y") so that the registered devices names are
87 * "foo_mod.foo_dev.x" and "foo_mod.foo_dev.y". If match_name + id are not
88 * unique, then the device_add fails and generates an error message.
89 *
90 * The auxiliary_device.dev.type.release or auxiliary_device.dev.release must
91 * be populated with a non-NULL pointer to successfully register the
92 * auxiliary_device. This release call is where resources associated with the
93 * auxiliary device must be free'ed. Because once the device is placed on the
94 * bus the parent driver can not tell what other code may have a reference to
95 * this data.
96 *
97 * The auxiliary_device.dev.parent should be set. Typically to the registering
98 * drivers device.
99 *
100 * Second, call auxiliary_device_init(), which checks several aspects of the
101 * auxiliary_device struct and performs a device_initialize(). After this step
102 * completes, any error state must have a call to auxiliary_device_uninit() in
103 * its resolution path.
104 *
105 * The third and final step in registering an auxiliary_device is to perform a
106 * call to auxiliary_device_add(), which sets the name of the device and adds
107 * the device to the bus.
108 *
109 * .. code-block:: c
110 *
111 * #define MY_DEVICE_NAME "foo_dev"
112 *
113 * ...
114 *
115 * struct auxiliary_device *my_aux_dev = my_aux_dev_alloc(xxx);
116 *
117 * // Step 1:
118 * my_aux_dev->name = MY_DEVICE_NAME;
119 * my_aux_dev->id = my_unique_id_alloc(xxx);
120 * my_aux_dev->dev.release = my_aux_dev_release;
121 * my_aux_dev->dev.parent = my_dev;
122 *
123 * // Step 2:
124 * if (auxiliary_device_init(my_aux_dev))
125 * goto fail;
126 *
127 * // Step 3:
128 * if (auxiliary_device_add(my_aux_dev)) {
129 * auxiliary_device_uninit(my_aux_dev);
130 * goto fail;
131 * }
132 *
133 * ...
134 *
135 *
136 * Unregistering an auxiliary_device is a two-step process to mirror the
137 * register process. First call auxiliary_device_delete(), then call
138 * auxiliary_device_uninit().
139 *
140 * .. code-block:: c
141 *
142 * auxiliary_device_delete(my_dev->my_aux_dev);
143 * auxiliary_device_uninit(my_dev->my_aux_dev);
144 */
145 struct auxiliary_device {
146 struct device dev;
147 const char *name;
148 u32 id;
149 struct {
150 struct xarray irqs;
151 struct mutex lock; /* Synchronize irq sysfs creation */
152 bool irq_dir_exists;
153 } sysfs;
154 void *registration_data_rust;
155 };
156
157 /**
158 * struct auxiliary_driver - Definition of an auxiliary bus driver
159 * @probe: Called when a matching device is added to the bus.
160 * @remove: Called when device is removed from the bus.
161 * @shutdown: Called at shut-down time to quiesce the device.
162 * @suspend: Called to put the device to sleep mode. Usually to a power state.
163 * @resume: Called to bring a device from sleep mode.
164 * @name: Driver name.
165 * @driver: Core driver structure.
166 * @id_table: Table of devices this driver should match on the bus.
167 *
168 * Auxiliary drivers follow the standard driver model convention, where
169 * discovery/enumeration is handled by the core, and drivers provide probe()
170 * and remove() methods. They support power management and shutdown
171 * notifications using the standard conventions.
172 *
173 * Auxiliary drivers register themselves with the bus by calling
174 * auxiliary_driver_register(). The id_table contains the match_names of
175 * auxiliary devices that a driver can bind with.
176 *
177 * .. code-block:: c
178 *
179 * static const struct auxiliary_device_id my_auxiliary_id_table[] = {
180 * { .name = "foo_mod.foo_dev" },
181 * {},
182 * };
183 *
184 * MODULE_DEVICE_TABLE(auxiliary, my_auxiliary_id_table);
185 *
186 * struct auxiliary_driver my_drv = {
187 * .name = "myauxiliarydrv",
188 * .id_table = my_auxiliary_id_table,
189 * .probe = my_drv_probe,
190 * .remove = my_drv_remove
191 * };
192 */
193 struct auxiliary_driver {
194 int (*probe)(struct auxiliary_device *auxdev, const struct auxiliary_device_id *id);
195 void (*remove)(struct auxiliary_device *auxdev);
196 void (*shutdown)(struct auxiliary_device *auxdev);
197 int (*suspend)(struct auxiliary_device *auxdev, pm_message_t state);
198 int (*resume)(struct auxiliary_device *auxdev);
199 const char *name;
200 struct device_driver driver;
201 const struct auxiliary_device_id *id_table;
202 };
203
auxiliary_get_drvdata(struct auxiliary_device * auxdev)204 static inline void *auxiliary_get_drvdata(struct auxiliary_device *auxdev)
205 {
206 return dev_get_drvdata(&auxdev->dev);
207 }
208
auxiliary_set_drvdata(struct auxiliary_device * auxdev,void * data)209 static inline void auxiliary_set_drvdata(struct auxiliary_device *auxdev, void *data)
210 {
211 dev_set_drvdata(&auxdev->dev, data);
212 }
213
to_auxiliary_dev(struct device * dev)214 static inline struct auxiliary_device *to_auxiliary_dev(struct device *dev)
215 {
216 return container_of(dev, struct auxiliary_device, dev);
217 }
218
to_auxiliary_drv(const struct device_driver * drv)219 static inline const struct auxiliary_driver *to_auxiliary_drv(const struct device_driver *drv)
220 {
221 return container_of(drv, struct auxiliary_driver, driver);
222 }
223
224 int auxiliary_device_init(struct auxiliary_device *auxdev);
225 int __auxiliary_device_add(struct auxiliary_device *auxdev, const char *modname);
226 #define auxiliary_device_add(auxdev) __auxiliary_device_add(auxdev, KBUILD_MODNAME)
227
228 #ifdef CONFIG_SYSFS
229 int auxiliary_device_sysfs_irq_add(struct auxiliary_device *auxdev, int irq);
230 void auxiliary_device_sysfs_irq_remove(struct auxiliary_device *auxdev,
231 int irq);
232 #else /* CONFIG_SYSFS */
233 static inline int
auxiliary_device_sysfs_irq_add(struct auxiliary_device * auxdev,int irq)234 auxiliary_device_sysfs_irq_add(struct auxiliary_device *auxdev, int irq)
235 {
236 return 0;
237 }
238
239 static inline void
auxiliary_device_sysfs_irq_remove(struct auxiliary_device * auxdev,int irq)240 auxiliary_device_sysfs_irq_remove(struct auxiliary_device *auxdev, int irq) {}
241 #endif
242
auxiliary_device_uninit(struct auxiliary_device * auxdev)243 static inline void auxiliary_device_uninit(struct auxiliary_device *auxdev)
244 {
245 mutex_destroy(&auxdev->sysfs.lock);
246 put_device(&auxdev->dev);
247 }
248
auxiliary_device_delete(struct auxiliary_device * auxdev)249 static inline void auxiliary_device_delete(struct auxiliary_device *auxdev)
250 {
251 device_del(&auxdev->dev);
252 }
253
254 int __auxiliary_driver_register(struct auxiliary_driver *auxdrv, struct module *owner,
255 const char *modname);
256 #define auxiliary_driver_register(auxdrv) \
257 __auxiliary_driver_register(auxdrv, THIS_MODULE, KBUILD_MODNAME)
258
259 void auxiliary_driver_unregister(struct auxiliary_driver *auxdrv);
260
261 struct auxiliary_device *auxiliary_device_create(struct device *dev,
262 const char *modname,
263 const char *devname,
264 void *platform_data,
265 int id);
266 void auxiliary_device_destroy(void *auxdev);
267
268 struct auxiliary_device *__devm_auxiliary_device_create(struct device *dev,
269 const char *modname,
270 const char *devname,
271 void *platform_data,
272 int id);
273
274 #define devm_auxiliary_device_create(dev, devname, platform_data) \
275 __devm_auxiliary_device_create(dev, KBUILD_MODNAME, devname, \
276 platform_data, 0)
277
278 bool dev_is_auxiliary(struct device *dev);
279
280 /**
281 * module_auxiliary_driver() - Helper macro for registering an auxiliary driver
282 * @__auxiliary_driver: auxiliary driver struct
283 *
284 * Helper macro for auxiliary drivers which do not do anything special in
285 * module init/exit. This eliminates a lot of boilerplate. Each module may only
286 * use this macro once, and calling it replaces module_init() and module_exit()
287 *
288 * .. code-block:: c
289 *
290 * module_auxiliary_driver(my_drv);
291 */
292 #define module_auxiliary_driver(__auxiliary_driver) \
293 module_driver(__auxiliary_driver, auxiliary_driver_register, auxiliary_driver_unregister)
294
295 #endif /* _AUXILIARY_BUS_H_ */
296