blob: f572e127918262f3812436ab439689c008bf84e7 [file] [log] [blame]
Thomas Gleixnerd2912cb2019-06-04 10:11:33 +02001/* SPDX-License-Identifier: GPL-2.0-only */
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -03002/*
3 * V4L2 asynchronous subdevice registration API
4 *
5 * Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -03006 */
7
8#ifndef V4L2_ASYNC_H
9#define V4L2_ASYNC_H
10
11#include <linux/list.h>
12#include <linux/mutex.h>
13
Ezequiel Garcia517fd2b2021-01-08 18:17:28 +010014struct dentry;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030015struct device;
Sylwester Nawrockie7359f82013-07-19 12:21:29 -030016struct device_node;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030017struct v4l2_device;
18struct v4l2_subdev;
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -040019struct v4l2_async_notifier;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030020
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -030021/**
22 * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
23 * in order to identify a match
24 *
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -030025 * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
Sakari Ailusecdf0cf2016-08-16 06:54:59 -030026 * @V4L2_ASYNC_MATCH_FWNODE: Match will use firmware node
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -030027 *
Kieran Bingham51a47562020-09-16 12:46:45 +020028 * This enum is used by the asynchronous sub-device logic to define the
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -030029 * algorithm that will be used to match an asynchronous device.
30 */
Sylwester Nawrockicfca7642013-07-19 12:14:46 -030031enum v4l2_async_match_type {
Sylwester Nawrockicfca7642013-07-19 12:14:46 -030032 V4L2_ASYNC_MATCH_I2C,
Sakari Ailusecdf0cf2016-08-16 06:54:59 -030033 V4L2_ASYNC_MATCH_FWNODE,
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030034};
35
36/**
37 * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
Mauro Carvalho Chehabf8b27372015-08-22 05:16:24 -030038 *
39 * @match_type: type of match that will be used
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030040 * @match: union of per-bus type matching data sets
Mauro Carvalho Chehabeb0f73b2017-09-27 11:43:00 -040041 * @match.fwnode:
42 * pointer to &struct fwnode_handle to be matched.
43 * Used if @match_type is %V4L2_ASYNC_MATCH_FWNODE.
Mauro Carvalho Chehabeb0f73b2017-09-27 11:43:00 -040044 * @match.i2c: embedded struct with I2C parameters to be matched.
Mauro Carvalho Chehab4a3fad72018-01-04 06:47:28 -050045 * Both @match.i2c.adapter_id and @match.i2c.address
Mauro Carvalho Chehabeb0f73b2017-09-27 11:43:00 -040046 * should be matched.
47 * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
48 * @match.i2c.adapter_id:
49 * I2C adapter ID to be matched.
50 * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
51 * @match.i2c.address:
52 * I2C address to be matched.
53 * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -040054 * @asd_list: used to add struct v4l2_async_subdev objects to the
55 * master notifier @asd_list
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030056 * @list: used to link struct v4l2_async_subdev objects, waiting to be
57 * probed, to a notifier->waiting list
Sakari Ailus9ca46532017-08-17 11:28:21 -040058 *
59 * When this struct is used as a member in a driver specific struct,
60 * the driver specific struct shall contain the &struct
61 * v4l2_async_subdev as its first member.
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030062 */
63struct v4l2_async_subdev {
Sylwester Nawrockicfca7642013-07-19 12:14:46 -030064 enum v4l2_async_match_type match_type;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030065 union {
Mauro Carvalho Chehab4e48afe2017-09-27 10:12:00 -040066 struct fwnode_handle *fwnode;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030067 struct {
68 int adapter_id;
69 unsigned short address;
70 } i2c;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030071 } match;
72
73 /* v4l2-async core private: not to be used by drivers */
74 struct list_head list;
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -040075 struct list_head asd_list;
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030076};
77
78/**
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -040079 * struct v4l2_async_notifier_operations - Asynchronous V4L2 notifier operations
80 * @bound: a subdevice driver has successfully probed one of the subdevices
Sakari Ailus2cab00b2017-09-24 20:54:31 -040081 * @complete: All subdevices have been probed successfully. The complete
82 * callback is only executed for the root notifier.
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030083 * @unbind: a subdevice is leaving
84 */
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -040085struct v4l2_async_notifier_operations {
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -030086 int (*bound)(struct v4l2_async_notifier *notifier,
87 struct v4l2_subdev *subdev,
88 struct v4l2_async_subdev *asd);
89 int (*complete)(struct v4l2_async_notifier *notifier);
90 void (*unbind)(struct v4l2_async_notifier *notifier,
91 struct v4l2_subdev *subdev,
92 struct v4l2_async_subdev *asd);
93};
94
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -030095/**
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -040096 * struct v4l2_async_notifier - v4l2_device notifier data
97 *
98 * @ops: notifier operations
Sakari Ailus2cab00b2017-09-24 20:54:31 -040099 * @v4l2_dev: v4l2_device of the root notifier, NULL otherwise
100 * @sd: sub-device that registered the notifier, NULL otherwise
101 * @parent: parent notifier
Steve Longerbeam66beb322018-09-29 15:54:19 -0400102 * @asd_list: master list of struct v4l2_async_subdev
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -0400103 * @waiting: list of struct v4l2_async_subdev, waiting for their drivers
104 * @done: list of struct v4l2_subdev, already probed
105 * @list: member in a global list of notifiers
106 */
107struct v4l2_async_notifier {
108 const struct v4l2_async_notifier_operations *ops;
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -0400109 struct v4l2_device *v4l2_dev;
Sakari Ailus2cab00b2017-09-24 20:54:31 -0400110 struct v4l2_subdev *sd;
111 struct v4l2_async_notifier *parent;
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400112 struct list_head asd_list;
Laurent Pinchartb6ee3f02017-08-30 13:18:04 -0400113 struct list_head waiting;
114 struct list_head done;
115 struct list_head list;
116};
117
118/**
Ezequiel Garcia517fd2b2021-01-08 18:17:28 +0100119 * v4l2_async_debug_init - Initialize debugging tools.
120 *
121 * @debugfs_dir: pointer to the parent debugfs &struct dentry
122 */
123void v4l2_async_debug_init(struct dentry *debugfs_dir);
124
125/**
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400126 * v4l2_async_notifier_init - Initialize a notifier.
127 *
128 * @notifier: pointer to &struct v4l2_async_notifier
129 *
130 * This function initializes the notifier @asd_list. It must be called
Ezequiel Garcia3e90e5a2021-01-18 02:52:55 +0100131 * before adding a subdevice to a notifier, using one of:
132 * @v4l2_async_notifier_add_fwnode_remote_subdev,
133 * @v4l2_async_notifier_add_fwnode_subdev,
134 * @v4l2_async_notifier_add_i2c_subdev,
135 * @__v4l2_async_notifier_add_subdev or
136 * @v4l2_async_notifier_parse_fwnode_endpoints.
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400137 */
138void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier);
139
140/**
Ezequiel Garciac1cc2362021-01-18 02:52:57 +0100141 * __v4l2_async_notifier_add_subdev - Add an async subdev to the
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400142 * notifier's master asd list.
143 *
144 * @notifier: pointer to &struct v4l2_async_notifier
145 * @asd: pointer to &struct v4l2_async_subdev
146 *
Ezequiel Garciac1cc2362021-01-18 02:52:57 +0100147 * \warning: Drivers should avoid using this function and instead use one of:
148 * @v4l2_async_notifier_add_fwnode_subdev,
149 * @v4l2_async_notifier_add_fwnode_remote_subdev or
150 * @v4l2_async_notifier_add_i2c_subdev.
151 *
Laurent Pinchart6c116312020-08-11 22:59:35 +0200152 * Call this function before registering a notifier to link the provided @asd to
153 * the notifiers master @asd_list. The @asd must be allocated with k*alloc() as
154 * it will be freed by the framework when the notifier is destroyed.
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400155 */
Ezequiel Garciac1cc2362021-01-18 02:52:57 +0100156int __v4l2_async_notifier_add_subdev(struct v4l2_async_notifier *notifier,
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400157 struct v4l2_async_subdev *asd);
158
Sakari Ailus8f202f82021-02-15 13:37:28 +0100159struct v4l2_async_subdev *
160__v4l2_async_notifier_add_fwnode_subdev(struct v4l2_async_notifier *notifier,
161 struct fwnode_handle *fwnode,
162 unsigned int asd_struct_size);
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400163/**
Steve Longerbeam23989b42018-09-29 15:54:07 -0400164 * 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
Sakari Ailus8f202f82021-02-15 13:37:28 +0100168 * @fwnode: fwnode handle of the sub-device to be matched, pointer to
169 * &struct fwnode_handle
170 * @type: Type of the driver's async sub-device struct. The &struct
171 * v4l2_async_subdev shall be the first member of the driver's async
172 * sub-device struct, i.e. both begin at the same memory address.
Steve Longerbeam23989b42018-09-29 15:54:07 -0400173 *
Sakari Ailus016413d2019-04-04 19:43:29 -0400174 * Allocate a fwnode-matched asd of size asd_struct_size, and add it to the
175 * notifiers @asd_list. The function also gets a reference of the fwnode which
176 * is released later at notifier cleanup time.
Steve Longerbeam23989b42018-09-29 15:54:07 -0400177 */
Sakari Ailus8f202f82021-02-15 13:37:28 +0100178#define v4l2_async_notifier_add_fwnode_subdev(notifier, fwnode, type) \
179 ((type *)__v4l2_async_notifier_add_fwnode_subdev(notifier, fwnode, \
180 sizeof(type)))
Steve Longerbeam23989b42018-09-29 15:54:07 -0400181
Sakari Ailus8f202f82021-02-15 13:37:28 +0100182struct v4l2_async_subdev *
183__v4l2_async_notifier_add_fwnode_remote_subdev(struct v4l2_async_notifier *notif,
184 struct fwnode_handle *endpoint,
185 unsigned int asd_struct_size);
Steve Longerbeam23989b42018-09-29 15:54:07 -0400186/**
Sakari Ailus820342a2019-02-28 08:25:28 -0500187 * v4l2_async_notifier_add_fwnode_remote_subdev - Allocate and add a fwnode
188 * remote async subdev to the
189 * notifier's master asd_list.
190 *
Sakari Ailus8f202f82021-02-15 13:37:28 +0100191 * @notifier: pointer to &struct v4l2_async_notifier
192 * @ep: local endpoint pointing to the remote sub-device to be matched,
193 * pointer to &struct fwnode_handle
194 * @type: Type of the driver's async sub-device struct. The &struct
195 * v4l2_async_subdev shall be the first member of the driver's async
196 * sub-device struct, i.e. both begin at the same memory address.
Sakari Ailus820342a2019-02-28 08:25:28 -0500197 *
198 * Gets the remote endpoint of a given local endpoint, set it up for fwnode
199 * matching and adds the async sub-device to the notifier's @asd_list. The
200 * function also gets a reference of the fwnode which is released later at
201 * notifier cleanup time.
202 *
203 * This is just like @v4l2_async_notifier_add_fwnode_subdev, but with the
Ezequiel Garciac1cf3d82021-01-18 02:52:45 +0100204 * exception that the fwnode refers to a local endpoint, not the remote one.
Sakari Ailus820342a2019-02-28 08:25:28 -0500205 */
Sakari Ailus8f202f82021-02-15 13:37:28 +0100206#define v4l2_async_notifier_add_fwnode_remote_subdev(notifier, ep, type) \
207 ((type *) \
208 __v4l2_async_notifier_add_fwnode_remote_subdev(notifier, ep, \
209 sizeof(type)))
Sakari Ailus820342a2019-02-28 08:25:28 -0500210
Sakari Ailus8f202f82021-02-15 13:37:28 +0100211struct v4l2_async_subdev *
212__v4l2_async_notifier_add_i2c_subdev(struct v4l2_async_notifier *notifier,
213 int adapter_id, unsigned short address,
214 unsigned int asd_struct_size);
Sakari Ailus820342a2019-02-28 08:25:28 -0500215/**
Steve Longerbeam23989b42018-09-29 15:54:07 -0400216 * v4l2_async_notifier_add_i2c_subdev - Allocate and add an i2c async
217 * subdev to the notifier's master asd_list.
218 *
219 * @notifier: pointer to &struct v4l2_async_notifier
Sakari Ailus8f202f82021-02-15 13:37:28 +0100220 * @adapter: I2C adapter ID to be matched
Steve Longerbeam23989b42018-09-29 15:54:07 -0400221 * @address: I2C address of sub-device to be matched
Sakari Ailus8f202f82021-02-15 13:37:28 +0100222 * @type: Type of the driver's async sub-device struct. The &struct
223 * v4l2_async_subdev shall be the first member of the driver's async
224 * sub-device struct, i.e. both begin at the same memory address.
Steve Longerbeam23989b42018-09-29 15:54:07 -0400225 *
Sakari Ailus8f202f82021-02-15 13:37:28 +0100226 * Same as v4l2_async_notifier_add_fwnode_subdev() but for I2C matched
227 * sub-devices.
Steve Longerbeam23989b42018-09-29 15:54:07 -0400228 */
Sakari Ailus8f202f82021-02-15 13:37:28 +0100229#define v4l2_async_notifier_add_i2c_subdev(notifier, adapter, address, type) \
230 ((type *)__v4l2_async_notifier_add_i2c_subdev(notifier, adapter, \
231 address, sizeof(type)))
Steve Longerbeam23989b42018-09-29 15:54:07 -0400232
233/**
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300234 * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
235 *
236 * @v4l2_dev: pointer to &struct v4l2_device
237 * @notifier: pointer to &struct v4l2_async_notifier
238 */
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -0300239int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
240 struct v4l2_async_notifier *notifier);
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300241
242/**
Sakari Ailus2cab00b2017-09-24 20:54:31 -0400243 * v4l2_async_subdev_notifier_register - registers a subdevice asynchronous
244 * notifier for a sub-device
245 *
246 * @sd: pointer to &struct v4l2_subdev
247 * @notifier: pointer to &struct v4l2_async_notifier
248 */
249int v4l2_async_subdev_notifier_register(struct v4l2_subdev *sd,
250 struct v4l2_async_notifier *notifier);
251
252/**
Mauro Carvalho Chehab6087b212018-10-04 17:10:46 -0400253 * v4l2_async_notifier_unregister - unregisters a subdevice
254 * asynchronous notifier
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300255 *
256 * @notifier: pointer to &struct v4l2_async_notifier
257 */
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -0300258void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300259
260/**
Sakari Ailus9ca46532017-08-17 11:28:21 -0400261 * v4l2_async_notifier_cleanup - clean up notifier resources
262 * @notifier: the notifier the resources of which are to be cleaned up
263 *
264 * Release memory resources related to a notifier, including the async
265 * sub-devices allocated for the purposes of the notifier but not the notifier
266 * itself. The user is responsible for calling this function to clean up the
Steve Longerbeamb47d7ff2018-09-29 15:54:06 -0400267 * notifier after calling
Ezequiel Garcia3e90e5a2021-01-18 02:52:55 +0100268 * @v4l2_async_notifier_add_fwnode_remote_subdev,
269 * @v4l2_async_notifier_add_fwnode_subdev,
270 * @v4l2_async_notifier_add_i2c_subdev,
271 * @__v4l2_async_notifier_add_subdev or
272 * @v4l2_async_notifier_parse_fwnode_endpoints.
Sakari Ailus9ca46532017-08-17 11:28:21 -0400273 *
274 * There is no harm from calling v4l2_async_notifier_cleanup in other
275 * cases as long as its memory has been zeroed after it has been
276 * allocated.
277 */
278void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier);
279
280/**
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300281 * v4l2_async_register_subdev - registers a sub-device to the asynchronous
Mauro Carvalho Chehab4a3fad72018-01-04 06:47:28 -0500282 * subdevice framework
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300283 *
284 * @sd: pointer to &struct v4l2_subdev
285 */
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -0300286int v4l2_async_register_subdev(struct v4l2_subdev *sd);
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300287
288/**
Sakari Ailusaef69d52017-09-24 18:47:44 -0400289 * v4l2_async_register_subdev_sensor_common - registers a sensor sub-device to
290 * the asynchronous sub-device
291 * framework and parse set up common
292 * sensor related devices
293 *
294 * @sd: pointer to struct &v4l2_subdev
295 *
296 * This function is just like v4l2_async_register_subdev() with the exception
297 * that calling it will also parse firmware interfaces for remote references
298 * using v4l2_async_notifier_parse_fwnode_sensor_common() and registers the
299 * async sub-devices. The sub-device is similarly unregistered by calling
300 * v4l2_async_unregister_subdev().
301 *
302 * While registered, the subdev module is marked as in-use.
303 *
304 * An error is returned if the module is no longer loaded on any attempts
305 * to register it.
306 */
Mauro Carvalho Chehab6087b212018-10-04 17:10:46 -0400307int __must_check
308v4l2_async_register_subdev_sensor_common(struct v4l2_subdev *sd);
Sakari Ailusaef69d52017-09-24 18:47:44 -0400309
310/**
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300311 * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
Mauro Carvalho Chehab4a3fad72018-01-04 06:47:28 -0500312 * subdevice framework
Mauro Carvalho Chehabab4f5a4a2016-07-21 09:24:55 -0300313 *
314 * @sd: pointer to &struct v4l2_subdev
315 */
Guennadi Liakhovetskie9e31042013-01-08 07:06:31 -0300316void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
317#endif