Commit | Line | Data |
---|---|---|
d2912cb1 | 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
e9e31049 GL |
2 | /* |
3 | * V4L2 asynchronous subdevice registration API | |
4 | * | |
5 | * Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de> | |
e9e31049 GL |
6 | */ |
7 | ||
8 | #ifndef V4L2_ASYNC_H | |
9 | #define V4L2_ASYNC_H | |
10 | ||
11 | #include <linux/list.h> | |
12 | #include <linux/mutex.h> | |
13 | ||
14 | struct device; | |
e7359f8e | 15 | struct device_node; |
e9e31049 GL |
16 | struct v4l2_device; |
17 | struct v4l2_subdev; | |
b6ee3f0d | 18 | struct v4l2_async_notifier; |
e9e31049 | 19 | |
ab4f5a4a MCC |
20 | /** |
21 | * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used | |
22 | * in order to identify a match | |
23 | * | |
24 | * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct | |
4a3fad70 | 25 | * v4l2_async_subdev.match ops |
ab4f5a4a MCC |
26 | * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name |
27 | * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address | |
ecdf0cfe | 28 | * @V4L2_ASYNC_MATCH_FWNODE: Match will use firmware node |
ab4f5a4a MCC |
29 | * |
30 | * This enum is used by the asyncrhronous sub-device logic to define the | |
31 | * algorithm that will be used to match an asynchronous device. | |
32 | */ | |
cfca7644 SN |
33 | enum v4l2_async_match_type { |
34 | V4L2_ASYNC_MATCH_CUSTOM, | |
35 | V4L2_ASYNC_MATCH_DEVNAME, | |
36 | V4L2_ASYNC_MATCH_I2C, | |
ecdf0cfe | 37 | V4L2_ASYNC_MATCH_FWNODE, |
e9e31049 GL |
38 | }; |
39 | ||
40 | /** | |
41 | * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge | |
f8b27377 MCC |
42 | * |
43 | * @match_type: type of match that will be used | |
e9e31049 | 44 | * @match: union of per-bus type matching data sets |
eb0f73ba MCC |
45 | * @match.fwnode: |
46 | * pointer to &struct fwnode_handle to be matched. | |
47 | * Used if @match_type is %V4L2_ASYNC_MATCH_FWNODE. | |
48 | * @match.device_name: | |
49 | * string containing the device name to be matched. | |
50 | * Used if @match_type is %V4L2_ASYNC_MATCH_DEVNAME. | |
51 | * @match.i2c: embedded struct with I2C parameters to be matched. | |
4a3fad70 | 52 | * Both @match.i2c.adapter_id and @match.i2c.address |
eb0f73ba MCC |
53 | * should be matched. |
54 | * Used if @match_type is %V4L2_ASYNC_MATCH_I2C. | |
55 | * @match.i2c.adapter_id: | |
56 | * I2C adapter ID to be matched. | |
57 | * Used if @match_type is %V4L2_ASYNC_MATCH_I2C. | |
58 | * @match.i2c.address: | |
59 | * I2C address to be matched. | |
60 | * Used if @match_type is %V4L2_ASYNC_MATCH_I2C. | |
61 | * @match.custom: | |
62 | * Driver-specific match criteria. | |
63 | * Used if @match_type is %V4L2_ASYNC_MATCH_CUSTOM. | |
64 | * @match.custom.match: | |
65 | * Driver-specific match function to be used if | |
66 | * %V4L2_ASYNC_MATCH_CUSTOM. | |
67 | * @match.custom.priv: | |
68 | * Driver-specific private struct with match parameters | |
69 | * to be used if %V4L2_ASYNC_MATCH_CUSTOM. | |
b47d7ff1 SL |
70 | * @asd_list: used to add struct v4l2_async_subdev objects to the |
71 | * master notifier @asd_list | |
e9e31049 GL |
72 | * @list: used to link struct v4l2_async_subdev objects, waiting to be |
73 | * probed, to a notifier->waiting list | |
9ca46531 SA |
74 | * |
75 | * When this struct is used as a member in a driver specific struct, | |
76 | * the driver specific struct shall contain the &struct | |
77 | * v4l2_async_subdev as its first member. | |
e9e31049 GL |
78 | */ |
79 | struct v4l2_async_subdev { | |
cfca7644 | 80 | enum v4l2_async_match_type match_type; |
e9e31049 | 81 | union { |
4e48afec MCC |
82 | struct fwnode_handle *fwnode; |
83 | const char *device_name; | |
e9e31049 GL |
84 | struct { |
85 | int adapter_id; | |
86 | unsigned short address; | |
87 | } i2c; | |
88 | struct { | |
6087b215 MCC |
89 | bool (*match)(struct device *dev, |
90 | struct v4l2_async_subdev *sd); | |
e9e31049 GL |
91 | void *priv; |
92 | } custom; | |
93 | } match; | |
94 | ||
95 | /* v4l2-async core private: not to be used by drivers */ | |
96 | struct list_head list; | |
b47d7ff1 | 97 | struct list_head asd_list; |
e9e31049 GL |
98 | }; |
99 | ||
b6ee3f0d LP |
100 | /** |
101 | * struct v4l2_async_notifier_operations - Asynchronous V4L2 notifier operations | |
102 | * @bound: a subdevice driver has successfully probed one of the subdevices | |
2cab00bb SA |
103 | * @complete: All subdevices have been probed successfully. The complete |
104 | * callback is only executed for the root notifier. | |
b6ee3f0d LP |
105 | * @unbind: a subdevice is leaving |
106 | */ | |
107 | struct v4l2_async_notifier_operations { | |
108 | int (*bound)(struct v4l2_async_notifier *notifier, | |
109 | struct v4l2_subdev *subdev, | |
110 | struct v4l2_async_subdev *asd); | |
111 | int (*complete)(struct v4l2_async_notifier *notifier); | |
112 | void (*unbind)(struct v4l2_async_notifier *notifier, | |
113 | struct v4l2_subdev *subdev, | |
114 | struct v4l2_async_subdev *asd); | |
115 | }; | |
116 | ||
e9e31049 | 117 | /** |
f8b27377 MCC |
118 | * struct v4l2_async_notifier - v4l2_device notifier data |
119 | * | |
b6ee3f0d | 120 | * @ops: notifier operations |
2cab00bb SA |
121 | * @v4l2_dev: v4l2_device of the root notifier, NULL otherwise |
122 | * @sd: sub-device that registered the notifier, NULL otherwise | |
123 | * @parent: parent notifier | |
66beb323 | 124 | * @asd_list: master list of struct v4l2_async_subdev |
e9e31049 | 125 | * @waiting: list of struct v4l2_async_subdev, waiting for their drivers |
b426b3a6 | 126 | * @done: list of struct v4l2_subdev, already probed |
e9e31049 | 127 | * @list: member in a global list of notifiers |
e9e31049 GL |
128 | */ |
129 | struct v4l2_async_notifier { | |
b6ee3f0d | 130 | const struct v4l2_async_notifier_operations *ops; |
e9e31049 | 131 | struct v4l2_device *v4l2_dev; |
2cab00bb SA |
132 | struct v4l2_subdev *sd; |
133 | struct v4l2_async_notifier *parent; | |
b47d7ff1 | 134 | struct list_head asd_list; |
e9e31049 GL |
135 | struct list_head waiting; |
136 | struct list_head done; | |
137 | struct list_head list; | |
e9e31049 GL |
138 | }; |
139 | ||
b47d7ff1 SL |
140 | /** |
141 | * v4l2_async_notifier_init - Initialize a notifier. | |
142 | * | |
143 | * @notifier: pointer to &struct v4l2_async_notifier | |
144 | * | |
145 | * This function initializes the notifier @asd_list. It must be called | |
146 | * before the first call to @v4l2_async_notifier_add_subdev. | |
147 | */ | |
148 | void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier); | |
149 | ||
150 | /** | |
151 | * v4l2_async_notifier_add_subdev - Add an async subdev to the | |
152 | * notifier's master asd list. | |
153 | * | |
154 | * @notifier: pointer to &struct v4l2_async_notifier | |
155 | * @asd: pointer to &struct v4l2_async_subdev | |
156 | * | |
66beb323 SL |
157 | * Call this function before registering a notifier to link the |
158 | * provided asd to the notifiers master @asd_list. | |
b47d7ff1 SL |
159 | */ |
160 | int v4l2_async_notifier_add_subdev(struct v4l2_async_notifier *notifier, | |
161 | struct v4l2_async_subdev *asd); | |
162 | ||
23989b43 SL |
163 | /** |
164 | * v4l2_async_notifier_add_fwnode_subdev - Allocate and add a fwnode async | |
165 | * subdev to the notifier's master asd_list. | |
166 | * | |
167 | * @notifier: pointer to &struct v4l2_async_notifier | |
168 | * @fwnode: fwnode handle of the sub-device to be matched | |
169 | * @asd_struct_size: size of the driver's async sub-device struct, including | |
170 | * sizeof(struct v4l2_async_subdev). The &struct | |
171 | * v4l2_async_subdev shall be the first member of | |
172 | * the driver's async sub-device struct, i.e. both | |
173 | * begin at the same memory address. | |
174 | * | |
016413d9 SA |
175 | * Allocate a fwnode-matched asd of size asd_struct_size, and add it to the |
176 | * notifiers @asd_list. The function also gets a reference of the fwnode which | |
177 | * is released later at notifier cleanup time. | |
23989b43 SL |
178 | */ |
179 | struct v4l2_async_subdev * | |
180 | v4l2_async_notifier_add_fwnode_subdev(struct v4l2_async_notifier *notifier, | |
181 | struct fwnode_handle *fwnode, | |
182 | unsigned int asd_struct_size); | |
183 | ||
820342ac SA |
184 | /** |
185 | * v4l2_async_notifier_add_fwnode_remote_subdev - Allocate and add a fwnode | |
186 | * remote async subdev to the | |
187 | * notifier's master asd_list. | |
188 | * | |
189 | * @notif: pointer to &struct v4l2_async_notifier | |
190 | * @endpoint: local endpoint pointing to the remote sub-device to be matched | |
191 | * @asd: Async sub-device struct allocated by the caller. The &struct | |
192 | * v4l2_async_subdev shall be the first member of the driver's async | |
193 | * sub-device struct, i.e. both begin at the same memory address. | |
194 | * | |
195 | * Gets the remote endpoint of a given local endpoint, set it up for fwnode | |
196 | * matching and adds the async sub-device to the notifier's @asd_list. The | |
197 | * function also gets a reference of the fwnode which is released later at | |
198 | * notifier cleanup time. | |
199 | * | |
200 | * This is just like @v4l2_async_notifier_add_fwnode_subdev, but with the | |
201 | * exception that the fwnode refers to a local endpoint, not the remote one, and | |
202 | * the function relies on the caller to allocate the async sub-device struct. | |
203 | */ | |
204 | int | |
205 | v4l2_async_notifier_add_fwnode_remote_subdev(struct v4l2_async_notifier *notif, | |
206 | struct fwnode_handle *endpoint, | |
207 | struct v4l2_async_subdev *asd); | |
208 | ||
23989b43 SL |
209 | /** |
210 | * v4l2_async_notifier_add_i2c_subdev - Allocate and add an i2c async | |
211 | * subdev to the notifier's master asd_list. | |
212 | * | |
213 | * @notifier: pointer to &struct v4l2_async_notifier | |
214 | * @adapter_id: I2C adapter ID to be matched | |
215 | * @address: I2C address of sub-device to be matched | |
216 | * @asd_struct_size: size of the driver's async sub-device struct, including | |
217 | * sizeof(struct v4l2_async_subdev). The &struct | |
218 | * v4l2_async_subdev shall be the first member of | |
219 | * the driver's async sub-device struct, i.e. both | |
220 | * begin at the same memory address. | |
221 | * | |
222 | * Same as above but for I2C matched sub-devices. | |
223 | */ | |
224 | struct v4l2_async_subdev * | |
225 | v4l2_async_notifier_add_i2c_subdev(struct v4l2_async_notifier *notifier, | |
226 | int adapter_id, unsigned short address, | |
227 | unsigned int asd_struct_size); | |
228 | ||
229 | /** | |
230 | * v4l2_async_notifier_add_devname_subdev - Allocate and add a device-name | |
231 | * async subdev to the notifier's master asd_list. | |
232 | * | |
233 | * @notifier: pointer to &struct v4l2_async_notifier | |
234 | * @device_name: device name string to be matched | |
235 | * @asd_struct_size: size of the driver's async sub-device struct, including | |
236 | * sizeof(struct v4l2_async_subdev). The &struct | |
237 | * v4l2_async_subdev shall be the first member of | |
238 | * the driver's async sub-device struct, i.e. both | |
239 | * begin at the same memory address. | |
240 | * | |
241 | * Same as above but for device-name matched sub-devices. | |
242 | */ | |
243 | struct v4l2_async_subdev * | |
244 | v4l2_async_notifier_add_devname_subdev(struct v4l2_async_notifier *notifier, | |
245 | const char *device_name, | |
246 | unsigned int asd_struct_size); | |
247 | ||
ab4f5a4a MCC |
248 | /** |
249 | * v4l2_async_notifier_register - registers a subdevice asynchronous notifier | |
250 | * | |
251 | * @v4l2_dev: pointer to &struct v4l2_device | |
252 | * @notifier: pointer to &struct v4l2_async_notifier | |
253 | */ | |
e9e31049 GL |
254 | int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev, |
255 | struct v4l2_async_notifier *notifier); | |
ab4f5a4a | 256 | |
2cab00bb SA |
257 | /** |
258 | * v4l2_async_subdev_notifier_register - registers a subdevice asynchronous | |
259 | * notifier for a sub-device | |
260 | * | |
261 | * @sd: pointer to &struct v4l2_subdev | |
262 | * @notifier: pointer to &struct v4l2_async_notifier | |
263 | */ | |
264 | int v4l2_async_subdev_notifier_register(struct v4l2_subdev *sd, | |
265 | struct v4l2_async_notifier *notifier); | |
266 | ||
ab4f5a4a | 267 | /** |
6087b215 MCC |
268 | * v4l2_async_notifier_unregister - unregisters a subdevice |
269 | * asynchronous notifier | |
ab4f5a4a MCC |
270 | * |
271 | * @notifier: pointer to &struct v4l2_async_notifier | |
272 | */ | |
e9e31049 | 273 | void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier); |
ab4f5a4a | 274 | |
9ca46531 SA |
275 | /** |
276 | * v4l2_async_notifier_cleanup - clean up notifier resources | |
277 | * @notifier: the notifier the resources of which are to be cleaned up | |
278 | * | |
279 | * Release memory resources related to a notifier, including the async | |
280 | * sub-devices allocated for the purposes of the notifier but not the notifier | |
281 | * itself. The user is responsible for calling this function to clean up the | |
b47d7ff1 SL |
282 | * notifier after calling |
283 | * @v4l2_async_notifier_add_subdev, | |
284 | * @v4l2_async_notifier_parse_fwnode_endpoints or | |
7a9ec808 | 285 | * @v4l2_fwnode_reference_parse_sensor_common. |
9ca46531 SA |
286 | * |
287 | * There is no harm from calling v4l2_async_notifier_cleanup in other | |
288 | * cases as long as its memory has been zeroed after it has been | |
289 | * allocated. | |
290 | */ | |
291 | void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier); | |
292 | ||
ab4f5a4a MCC |
293 | /** |
294 | * v4l2_async_register_subdev - registers a sub-device to the asynchronous | |
4a3fad70 | 295 | * subdevice framework |
ab4f5a4a MCC |
296 | * |
297 | * @sd: pointer to &struct v4l2_subdev | |
298 | */ | |
e9e31049 | 299 | int v4l2_async_register_subdev(struct v4l2_subdev *sd); |
ab4f5a4a | 300 | |
aef69d54 SA |
301 | /** |
302 | * v4l2_async_register_subdev_sensor_common - registers a sensor sub-device to | |
303 | * the asynchronous sub-device | |
304 | * framework and parse set up common | |
305 | * sensor related devices | |
306 | * | |
307 | * @sd: pointer to struct &v4l2_subdev | |
308 | * | |
309 | * This function is just like v4l2_async_register_subdev() with the exception | |
310 | * that calling it will also parse firmware interfaces for remote references | |
311 | * using v4l2_async_notifier_parse_fwnode_sensor_common() and registers the | |
312 | * async sub-devices. The sub-device is similarly unregistered by calling | |
313 | * v4l2_async_unregister_subdev(). | |
314 | * | |
315 | * While registered, the subdev module is marked as in-use. | |
316 | * | |
317 | * An error is returned if the module is no longer loaded on any attempts | |
318 | * to register it. | |
319 | */ | |
6087b215 MCC |
320 | int __must_check |
321 | v4l2_async_register_subdev_sensor_common(struct v4l2_subdev *sd); | |
aef69d54 | 322 | |
ab4f5a4a MCC |
323 | /** |
324 | * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous | |
4a3fad70 | 325 | * subdevice framework |
ab4f5a4a MCC |
326 | * |
327 | * @sd: pointer to &struct v4l2_subdev | |
328 | */ | |
e9e31049 GL |
329 | void v4l2_async_unregister_subdev(struct v4l2_subdev *sd); |
330 | #endif |