1 /* SPDX-License-Identifier: GPL-2.0-only */ 1
2 /*
3 * Copyright (c) 2019-2020 Intel Corporation
4 *
5 * Please see Documentation/driver-api/auxilia
6 */
7
8 #ifndef _AUXILIARY_BUS_H_
9 #define _AUXILIARY_BUS_H_
10
11 #include <linux/device.h>
12 #include <linux/mod_devicetable.h>
13
14 /**
15 * DOC: DEVICE_LIFESPAN
16 *
17 * The registering driver is the entity that a
18 * auxiliary_device and registers it on the au
19 * note that, as opposed to the platform bus,
20 * responsible for the management of the memor
21 *
22 * To be clear the memory for the auxiliary_de
23 * callback defined by the registering driver.
24 * only call auxiliary_device_delete() and the
25 * it is done with the device. The release()
26 * called if and when other code releases thei
27 *
28 * A parent object, defined in the shared head
29 * auxiliary_device. It also contains a point
30 * also is defined in the shared header. Both
31 * object(s) are allocated by the registering
32 * auxiliary_driver's registering module to pe
33 * from the pointer to the auxiliary_device, t
34 * the auxiliary_driver's probe function, up t
35 * have access to the shared object(s).
36 *
37 * The memory for the shared object(s) must ha
38 * greater than, the lifespan of the memory fo
39 * auxiliary_driver should only consider that
40 * long as the auxiliary_device is still regis
41 * is up to the registering driver to manage (
42 * memory for the shared object beyond the lif
43 *
44 * The registering driver must unregister all
45 * driver.remove() is completed. An easy way
46 * devm_add_action_or_reset() call to register
47 * device which unregisters the auxiliary devi
48 *
49 * Finally, any operations which operate on th
50 * to function (if only to return an error) af
51 * unregisters the auxiliary device.
52 */
53
54 /**
55 * struct auxiliary_device - auxiliary device
56 * @dev: Device,
57 * The release and parent fields of the
58 * in
59 * @name: Match name found by the auxiliary de
60 * @id: unique identitier if multiple devices
61 * @sysfs: embedded struct which hold all sysf
62 * @sysfs.irqs: irqs xarray contains irq indic
63 * @sysfs.lock: Synchronize irq sysfs creation
64 * @sysfs.irq_dir_exists: whether "irqs" direc
65 *
66 * An auxiliary_device represents a part of it
67 * It is given a name that, combined with the
68 * KBUILD_MODNAME, creates a match_name that i
69 * id that combined with the match_name provid
70 * the bus subsystem. For example, a driver r
71 * named 'foo_mod.ko' and the subdevice is nam
72 * therefore 'foo_mod.foo_dev'.
73 *
74 * Registering an auxiliary_device is a three-
75 *
76 * First, a 'struct auxiliary_device' needs to
77 * sub-device desired. The name, id, dev.rele
78 * this structure must be filled in as follows
79 *
80 * The 'name' field is to be given a name that
81 * driver. If two auxiliary_devices with the
82 * "foo_mod.foo_dev", are registered onto the
83 * values (e.g. "x" and "y") so that the regis
84 * "foo_mod.foo_dev.x" and "foo_mod.foo_dev.y"
85 * unique, then the device_add fails and gener
86 *
87 * The auxiliary_device.dev.type.release or au
88 * be populated with a non-NULL pointer to suc
89 * auxiliary_device. This release call is whe
90 * auxiliary device must be free'ed. Because
91 * bus the parent driver can not tell what oth
92 * this data.
93 *
94 * The auxiliary_device.dev.parent should be s
95 * drivers device.
96 *
97 * Second, call auxiliary_device_init(), which
98 * auxiliary_device struct and performs a devi
99 * completes, any error state must have a call
100 * its resolution path.
101 *
102 * The third and final step in registering an
103 * call to auxiliary_device_add(), which sets
104 * the device to the bus.
105 *
106 * .. code-block:: c
107 *
108 * #define MY_DEVICE_NAME "foo_dev"
109 *
110 * ...
111 *
112 * struct auxiliary_device *my_aux_dev =
113 *
114 * // Step 1:
115 * my_aux_dev->name = MY_DEVICE_NAME;
116 * my_aux_dev->id = my_unique_id_alloc(xx
117 * my_aux_dev->dev.release = my_aux_dev_r
118 * my_aux_dev->dev.parent = my_dev;
119 *
120 * // Step 2:
121 * if (auxiliary_device_init(my_aux_dev))
122 * goto fail;
123 *
124 * // Step 3:
125 * if (auxiliary_device_add(my_aux_dev))
126 * auxiliary_device_uninit(my_aux
127 * goto fail;
128 * }
129 *
130 * ...
131 *
132 *
133 * Unregistering an auxiliary_device is a two-
134 * register process. First call auxiliary_dev
135 * auxiliary_device_uninit().
136 *
137 * .. code-block:: c
138 *
139 * auxiliary_device_delete(my_dev->my_
140 * auxiliary_device_uninit(my_dev->my_
141 */
142 struct auxiliary_device {
143 struct device dev;
144 const char *name;
145 u32 id;
146 struct {
147 struct xarray irqs;
148 struct mutex lock; /* Synchron
149 bool irq_dir_exists;
150 } sysfs;
151 };
152
153 /**
154 * struct auxiliary_driver - Definition of an
155 * @probe: Called when a matching device is ad
156 * @remove: Called when device is removed from
157 * @shutdown: Called at shut-down time to quie
158 * @suspend: Called to put the device to sleep
159 * @resume: Called to bring a device from slee
160 * @name: Driver name.
161 * @driver: Core driver structure.
162 * @id_table: Table of devices this driver sho
163 *
164 * Auxiliary drivers follow the standard drive
165 * discovery/enumeration is handled by the cor
166 * and remove() methods. They support power ma
167 * notifications using the standard convention
168 *
169 * Auxiliary drivers register themselves with
170 * auxiliary_driver_register(). The id_table c
171 * auxiliary devices that a driver can bind wi
172 *
173 * .. code-block:: c
174 *
175 * static const struct auxiliary_devic
176 * { .name = "foo_mod.foo_dev"
177 * {},
178 * };
179 *
180 * MODULE_DEVICE_TABLE(auxiliary, my_a
181 *
182 * struct auxiliary_driver my_drv = {
183 * .name = "myauxiliarydrv",
184 * .id_table = my_auxiliary_id
185 * .probe = my_drv_probe,
186 * .remove = my_drv_remove
187 * };
188 */
189 struct auxiliary_driver {
190 int (*probe)(struct auxiliary_device *
191 void (*remove)(struct auxiliary_device
192 void (*shutdown)(struct auxiliary_devi
193 int (*suspend)(struct auxiliary_device
194 int (*resume)(struct auxiliary_device
195 const char *name;
196 struct device_driver driver;
197 const struct auxiliary_device_id *id_t
198 };
199
200 static inline void *auxiliary_get_drvdata(stru
201 {
202 return dev_get_drvdata(&auxdev->dev);
203 }
204
205 static inline void auxiliary_set_drvdata(struc
206 {
207 dev_set_drvdata(&auxdev->dev, data);
208 }
209
210 static inline struct auxiliary_device *to_auxi
211 {
212 return container_of(dev, struct auxili
213 }
214
215 static inline const struct auxiliary_driver *t
216 {
217 return container_of(drv, struct auxili
218 }
219
220 int auxiliary_device_init(struct auxiliary_dev
221 int __auxiliary_device_add(struct auxiliary_de
222 #define auxiliary_device_add(auxdev) __auxilia
223
224 #ifdef CONFIG_SYSFS
225 int auxiliary_device_sysfs_irq_add(struct auxi
226 void auxiliary_device_sysfs_irq_remove(struct
227 int irq
228 #else /* CONFIG_SYSFS */
229 static inline int
230 auxiliary_device_sysfs_irq_add(struct auxiliar
231 {
232 return 0;
233 }
234
235 static inline void
236 auxiliary_device_sysfs_irq_remove(struct auxil
237 #endif
238
239 static inline void auxiliary_device_uninit(str
240 {
241 mutex_destroy(&auxdev->sysfs.lock);
242 put_device(&auxdev->dev);
243 }
244
245 static inline void auxiliary_device_delete(str
246 {
247 device_del(&auxdev->dev);
248 }
249
250 int __auxiliary_driver_register(struct auxilia
251 const char *mo
252 #define auxiliary_driver_register(auxdrv) \
253 __auxiliary_driver_register(auxdrv, TH
254
255 void auxiliary_driver_unregister(struct auxili
256
257 /**
258 * module_auxiliary_driver() - Helper macro fo
259 * @__auxiliary_driver: auxiliary driver struc
260 *
261 * Helper macro for auxiliary drivers which do
262 * module init/exit. This eliminates a lot of
263 * use this macro once, and calling it replace
264 *
265 * .. code-block:: c
266 *
267 * module_auxiliary_driver(my_drv);
268 */
269 #define module_auxiliary_driver(__auxiliary_dr
270 module_driver(__auxiliary_driver, auxi
271
272 struct auxiliary_device *auxiliary_find_device
273
274
275
276 #endif /* _AUXILIARY_BUS_H_ */
277
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.