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