Loading...
1/* SPDX-License-Identifier: GPL-2.0-only */
2/*
3 * V4L2 asynchronous subdevice registration API
4 *
5 * Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
6 */
7
8#ifndef V4L2_ASYNC_H
9#define V4L2_ASYNC_H
10
11#include <linux/list.h>
12#include <linux/mutex.h>
13
14struct dentry;
15struct device;
16struct device_node;
17struct v4l2_device;
18struct v4l2_subdev;
19struct v4l2_async_notifier;
20
21/**
22 * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
23 * in order to identify a match
24 *
25 * @V4L2_ASYNC_MATCH_TYPE_I2C: Match will check for I2C adapter ID and address
26 * @V4L2_ASYNC_MATCH_TYPE_FWNODE: Match will use firmware node
27 *
28 * This enum is used by the asynchronous connection logic to define the
29 * algorithm that will be used to match an asynchronous device.
30 */
31enum v4l2_async_match_type {
32 V4L2_ASYNC_MATCH_TYPE_I2C,
33 V4L2_ASYNC_MATCH_TYPE_FWNODE,
34};
35
36/**
37 * struct v4l2_async_match_desc - async connection match information
38 *
39 * @type: type of match that will be used
40 * @fwnode: pointer to &struct fwnode_handle to be matched.
41 * Used if @match_type is %V4L2_ASYNC_MATCH_TYPE_FWNODE.
42 * @i2c: embedded struct with I2C parameters to be matched.
43 * Both @match.i2c.adapter_id and @match.i2c.address
44 * should be matched.
45 * Used if @match_type is %V4L2_ASYNC_MATCH_TYPE_I2C.
46 * @i2c.adapter_id:
47 * I2C adapter ID to be matched.
48 * Used if @match_type is %V4L2_ASYNC_MATCH_TYPE_I2C.
49 * @i2c.address:
50 * I2C address to be matched.
51 * Used if @match_type is %V4L2_ASYNC_MATCH_TYPE_I2C.
52 */
53struct v4l2_async_match_desc {
54 enum v4l2_async_match_type type;
55 union {
56 struct fwnode_handle *fwnode;
57 struct {
58 int adapter_id;
59 unsigned short address;
60 } i2c;
61 };
62};
63
64/**
65 * struct v4l2_async_connection - sub-device connection descriptor, as known to
66 * a bridge
67 *
68 * @match: struct of match type and per-bus type matching data sets
69 * @notifier: the async notifier the connection is related to
70 * @asc_entry: used to add struct v4l2_async_connection objects to the
71 * notifier @waiting_list or @done_list
72 * @asc_subdev_entry: entry in struct v4l2_async_subdev.asc_list list
73 * @sd: the related sub-device
74 *
75 * When this struct is used as a member in a driver specific struct, the driver
76 * specific struct shall contain the &struct v4l2_async_connection as its first
77 * member.
78 */
79struct v4l2_async_connection {
80 struct v4l2_async_match_desc match;
81 struct v4l2_async_notifier *notifier;
82 struct list_head asc_entry;
83 struct list_head asc_subdev_entry;
84 struct v4l2_subdev *sd;
85};
86
87/**
88 * struct v4l2_async_notifier_operations - Asynchronous V4L2 notifier operations
89 * @bound: a sub-device has been bound by the given connection
90 * @complete: All connections have been bound successfully. The complete
91 * callback is only executed for the root notifier.
92 * @unbind: a subdevice is leaving
93 * @destroy: the asc is about to be freed
94 */
95struct v4l2_async_notifier_operations {
96 int (*bound)(struct v4l2_async_notifier *notifier,
97 struct v4l2_subdev *subdev,
98 struct v4l2_async_connection *asc);
99 int (*complete)(struct v4l2_async_notifier *notifier);
100 void (*unbind)(struct v4l2_async_notifier *notifier,
101 struct v4l2_subdev *subdev,
102 struct v4l2_async_connection *asc);
103 void (*destroy)(struct v4l2_async_connection *asc);
104};
105
106/**
107 * struct v4l2_async_notifier - v4l2_device notifier data
108 *
109 * @ops: notifier operations
110 * @v4l2_dev: v4l2_device of the root notifier, NULL otherwise
111 * @sd: sub-device that registered the notifier, NULL otherwise
112 * @parent: parent notifier
113 * @waiting_list: list of struct v4l2_async_connection, waiting for their
114 * drivers
115 * @done_list: list of struct v4l2_subdev, already probed
116 * @notifier_entry: member in a global list of notifiers
117 */
118struct v4l2_async_notifier {
119 const struct v4l2_async_notifier_operations *ops;
120 struct v4l2_device *v4l2_dev;
121 struct v4l2_subdev *sd;
122 struct v4l2_async_notifier *parent;
123 struct list_head waiting_list;
124 struct list_head done_list;
125 struct list_head notifier_entry;
126};
127
128/**
129 * struct v4l2_async_subdev_endpoint - Entry in sub-device's fwnode list
130 *
131 * @async_subdev_endpoint_entry: An entry in async_subdev_endpoint_list of
132 * &struct v4l2_subdev
133 * @endpoint: Endpoint fwnode agains which to match the sub-device
134 */
135struct v4l2_async_subdev_endpoint {
136 struct list_head async_subdev_endpoint_entry;
137 struct fwnode_handle *endpoint;
138};
139
140/**
141 * v4l2_async_debug_init - Initialize debugging tools.
142 *
143 * @debugfs_dir: pointer to the parent debugfs &struct dentry
144 */
145void v4l2_async_debug_init(struct dentry *debugfs_dir);
146
147/**
148 * v4l2_async_nf_init - Initialize a notifier.
149 *
150 * @notifier: pointer to &struct v4l2_async_notifier
151 * @v4l2_dev: pointer to &struct v4l2_device
152 *
153 * This function initializes the notifier @asc_entry. It must be called
154 * before adding a subdevice to a notifier, using one of:
155 * v4l2_async_nf_add_fwnode_remote(),
156 * v4l2_async_nf_add_fwnode() or
157 * v4l2_async_nf_add_i2c().
158 */
159void v4l2_async_nf_init(struct v4l2_async_notifier *notifier,
160 struct v4l2_device *v4l2_dev);
161
162/**
163 * v4l2_async_subdev_nf_init - Initialize a sub-device notifier.
164 *
165 * @notifier: pointer to &struct v4l2_async_notifier
166 * @sd: pointer to &struct v4l2_subdev
167 *
168 * This function initializes the notifier @asc_list. It must be called
169 * before adding a subdevice to a notifier, using one of:
170 * v4l2_async_nf_add_fwnode_remote(), v4l2_async_nf_add_fwnode() or
171 * v4l2_async_nf_add_i2c().
172 */
173void v4l2_async_subdev_nf_init(struct v4l2_async_notifier *notifier,
174 struct v4l2_subdev *sd);
175
176struct v4l2_async_connection *
177__v4l2_async_nf_add_fwnode(struct v4l2_async_notifier *notifier,
178 struct fwnode_handle *fwnode,
179 unsigned int asc_struct_size);
180/**
181 * v4l2_async_nf_add_fwnode - Allocate and add a fwnode async
182 * subdev to the notifier's master asc_list.
183 *
184 * @notifier: pointer to &struct v4l2_async_notifier
185 * @fwnode: fwnode handle of the sub-device to be matched, pointer to
186 * &struct fwnode_handle
187 * @type: Type of the driver's async sub-device or connection struct. The
188 * &struct v4l2_async_connection shall be the first member of the
189 * driver's async struct, i.e. both begin at the same memory address.
190 *
191 * Allocate a fwnode-matched asc of size asc_struct_size, and add it to the
192 * notifiers @asc_list. The function also gets a reference of the fwnode which
193 * is released later at notifier cleanup time.
194 */
195#define v4l2_async_nf_add_fwnode(notifier, fwnode, type) \
196 ((type *)__v4l2_async_nf_add_fwnode(notifier, fwnode, sizeof(type)))
197
198struct v4l2_async_connection *
199__v4l2_async_nf_add_fwnode_remote(struct v4l2_async_notifier *notif,
200 struct fwnode_handle *endpoint,
201 unsigned int asc_struct_size);
202/**
203 * v4l2_async_nf_add_fwnode_remote - Allocate and add a fwnode
204 * remote async subdev to the
205 * notifier's master asc_list.
206 *
207 * @notifier: pointer to &struct v4l2_async_notifier
208 * @ep: local endpoint pointing to the remote connection to be matched,
209 * pointer to &struct fwnode_handle
210 * @type: Type of the driver's async connection struct. The &struct
211 * v4l2_async_connection shall be the first member of the driver's async
212 * connection struct, i.e. both begin at the same memory address.
213 *
214 * Gets the remote endpoint of a given local endpoint, set it up for fwnode
215 * matching and adds the async connection to the notifier's @asc_list. The
216 * function also gets a reference of the fwnode which is released later at
217 * notifier cleanup time.
218 *
219 * This is just like v4l2_async_nf_add_fwnode(), but with the
220 * exception that the fwnode refers to a local endpoint, not the remote one.
221 */
222#define v4l2_async_nf_add_fwnode_remote(notifier, ep, type) \
223 ((type *)__v4l2_async_nf_add_fwnode_remote(notifier, ep, sizeof(type)))
224
225struct v4l2_async_connection *
226__v4l2_async_nf_add_i2c(struct v4l2_async_notifier *notifier,
227 int adapter_id, unsigned short address,
228 unsigned int asc_struct_size);
229/**
230 * v4l2_async_nf_add_i2c - Allocate and add an i2c async
231 * subdev to the notifier's master asc_list.
232 *
233 * @notifier: pointer to &struct v4l2_async_notifier
234 * @adapter: I2C adapter ID to be matched
235 * @address: I2C address of connection to be matched
236 * @type: Type of the driver's async connection struct. The &struct
237 * v4l2_async_connection shall be the first member of the driver's async
238 * connection struct, i.e. both begin at the same memory address.
239 *
240 * Same as v4l2_async_nf_add_fwnode() but for I2C matched
241 * connections.
242 */
243#define v4l2_async_nf_add_i2c(notifier, adapter, address, type) \
244 ((type *)__v4l2_async_nf_add_i2c(notifier, adapter, address, \
245 sizeof(type)))
246
247/**
248 * v4l2_async_subdev_endpoint_add - Add an endpoint fwnode to async sub-device
249 * matching list
250 *
251 * @sd: the sub-device
252 * @fwnode: the endpoint fwnode to match
253 *
254 * Add a fwnode to the async sub-device's matching list. This allows registering
255 * multiple async sub-devices from a single device.
256 *
257 * Note that calling v4l2_subdev_cleanup() as part of the sub-device's cleanup
258 * if endpoints have been added to the sub-device's fwnode matching list.
259 *
260 * Returns an error on failure, 0 on success.
261 */
262int v4l2_async_subdev_endpoint_add(struct v4l2_subdev *sd,
263 struct fwnode_handle *fwnode);
264
265/**
266 * v4l2_async_connection_unique - return a unique &struct v4l2_async_connection
267 * for a sub-device
268 * @sd: the sub-device
269 *
270 * Return an async connection for a sub-device, when there is a single
271 * one only.
272 */
273struct v4l2_async_connection *
274v4l2_async_connection_unique(struct v4l2_subdev *sd);
275
276/**
277 * v4l2_async_nf_register - registers a subdevice asynchronous notifier
278 *
279 * @notifier: pointer to &struct v4l2_async_notifier
280 */
281int v4l2_async_nf_register(struct v4l2_async_notifier *notifier);
282
283/**
284 * v4l2_async_nf_unregister - unregisters a subdevice
285 * asynchronous notifier
286 *
287 * @notifier: pointer to &struct v4l2_async_notifier
288 */
289void v4l2_async_nf_unregister(struct v4l2_async_notifier *notifier);
290
291/**
292 * v4l2_async_nf_cleanup - clean up notifier resources
293 * @notifier: the notifier the resources of which are to be cleaned up
294 *
295 * Release memory resources related to a notifier, including the async
296 * connections allocated for the purposes of the notifier but not the notifier
297 * itself. The user is responsible for calling this function to clean up the
298 * notifier after calling v4l2_async_nf_add_fwnode_remote(),
299 * v4l2_async_nf_add_fwnode() or v4l2_async_nf_add_i2c().
300 *
301 * There is no harm from calling v4l2_async_nf_cleanup() in other
302 * cases as long as its memory has been zeroed after it has been
303 * allocated.
304 */
305void v4l2_async_nf_cleanup(struct v4l2_async_notifier *notifier);
306
307/**
308 * v4l2_async_register_subdev - registers a sub-device to the asynchronous
309 * subdevice framework
310 *
311 * @sd: pointer to &struct v4l2_subdev
312 */
313int v4l2_async_register_subdev(struct v4l2_subdev *sd);
314
315/**
316 * v4l2_async_register_subdev_sensor - registers a sensor sub-device to the
317 * asynchronous sub-device framework and
318 * parse set up common sensor related
319 * devices
320 *
321 * @sd: pointer to struct &v4l2_subdev
322 *
323 * This function is just like v4l2_async_register_subdev() with the exception
324 * that calling it will also parse firmware interfaces for remote references
325 * using v4l2_async_nf_parse_fwnode_sensor() and registers the
326 * async sub-devices. The sub-device is similarly unregistered by calling
327 * v4l2_async_unregister_subdev().
328 *
329 * While registered, the subdev module is marked as in-use.
330 *
331 * An error is returned if the module is no longer loaded on any attempts
332 * to register it.
333 */
334int __must_check
335v4l2_async_register_subdev_sensor(struct v4l2_subdev *sd);
336
337/**
338 * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
339 * subdevice framework
340 *
341 * @sd: pointer to &struct v4l2_subdev
342 */
343void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
344#endif
1/*
2 * V4L2 asynchronous subdevice registration API
3 *
4 * Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License version 2 as
8 * published by the Free Software Foundation.
9 */
10
11#ifndef V4L2_ASYNC_H
12#define V4L2_ASYNC_H
13
14#include <linux/list.h>
15#include <linux/mutex.h>
16
17struct device;
18struct device_node;
19struct v4l2_device;
20struct v4l2_subdev;
21struct v4l2_async_notifier;
22
23/* A random max subdevice number, used to allocate an array on stack */
24#define V4L2_MAX_SUBDEVS 128U
25
26/**
27 * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
28 * in order to identify a match
29 *
30 * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
31 * v4l2_async_subdev.match ops
32 * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
33 * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
34 * @V4L2_ASYNC_MATCH_FWNODE: Match will use firmware node
35 *
36 * This enum is used by the asyncrhronous sub-device logic to define the
37 * algorithm that will be used to match an asynchronous device.
38 */
39enum v4l2_async_match_type {
40 V4L2_ASYNC_MATCH_CUSTOM,
41 V4L2_ASYNC_MATCH_DEVNAME,
42 V4L2_ASYNC_MATCH_I2C,
43 V4L2_ASYNC_MATCH_FWNODE,
44};
45
46/**
47 * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
48 *
49 * @match_type: type of match that will be used
50 * @match: union of per-bus type matching data sets
51 * @match.fwnode:
52 * pointer to &struct fwnode_handle to be matched.
53 * Used if @match_type is %V4L2_ASYNC_MATCH_FWNODE.
54 * @match.device_name:
55 * string containing the device name to be matched.
56 * Used if @match_type is %V4L2_ASYNC_MATCH_DEVNAME.
57 * @match.i2c: embedded struct with I2C parameters to be matched.
58 * Both @match.i2c.adapter_id and @match.i2c.address
59 * should be matched.
60 * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
61 * @match.i2c.adapter_id:
62 * I2C adapter ID to be matched.
63 * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
64 * @match.i2c.address:
65 * I2C address to be matched.
66 * Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
67 * @match.custom:
68 * Driver-specific match criteria.
69 * Used if @match_type is %V4L2_ASYNC_MATCH_CUSTOM.
70 * @match.custom.match:
71 * Driver-specific match function to be used if
72 * %V4L2_ASYNC_MATCH_CUSTOM.
73 * @match.custom.priv:
74 * Driver-specific private struct with match parameters
75 * to be used if %V4L2_ASYNC_MATCH_CUSTOM.
76 * @list: used to link struct v4l2_async_subdev objects, waiting to be
77 * probed, to a notifier->waiting list
78 *
79 * When this struct is used as a member in a driver specific struct,
80 * the driver specific struct shall contain the &struct
81 * v4l2_async_subdev as its first member.
82 */
83struct v4l2_async_subdev {
84 enum v4l2_async_match_type match_type;
85 union {
86 struct fwnode_handle *fwnode;
87 const char *device_name;
88 struct {
89 int adapter_id;
90 unsigned short address;
91 } i2c;
92 struct {
93 bool (*match)(struct device *,
94 struct v4l2_async_subdev *);
95 void *priv;
96 } custom;
97 } match;
98
99 /* v4l2-async core private: not to be used by drivers */
100 struct list_head list;
101};
102
103/**
104 * struct v4l2_async_notifier_operations - Asynchronous V4L2 notifier operations
105 * @bound: a subdevice driver has successfully probed one of the subdevices
106 * @complete: All subdevices have been probed successfully. The complete
107 * callback is only executed for the root notifier.
108 * @unbind: a subdevice is leaving
109 */
110struct v4l2_async_notifier_operations {
111 int (*bound)(struct v4l2_async_notifier *notifier,
112 struct v4l2_subdev *subdev,
113 struct v4l2_async_subdev *asd);
114 int (*complete)(struct v4l2_async_notifier *notifier);
115 void (*unbind)(struct v4l2_async_notifier *notifier,
116 struct v4l2_subdev *subdev,
117 struct v4l2_async_subdev *asd);
118};
119
120/**
121 * struct v4l2_async_notifier - v4l2_device notifier data
122 *
123 * @ops: notifier operations
124 * @num_subdevs: number of subdevices used in the subdevs array
125 * @max_subdevs: number of subdevices allocated in the subdevs array
126 * @subdevs: array of pointers to subdevice descriptors
127 * @v4l2_dev: v4l2_device of the root notifier, NULL otherwise
128 * @sd: sub-device that registered the notifier, NULL otherwise
129 * @parent: parent notifier
130 * @waiting: list of struct v4l2_async_subdev, waiting for their drivers
131 * @done: list of struct v4l2_subdev, already probed
132 * @list: member in a global list of notifiers
133 */
134struct v4l2_async_notifier {
135 const struct v4l2_async_notifier_operations *ops;
136 unsigned int num_subdevs;
137 unsigned int max_subdevs;
138 struct v4l2_async_subdev **subdevs;
139 struct v4l2_device *v4l2_dev;
140 struct v4l2_subdev *sd;
141 struct v4l2_async_notifier *parent;
142 struct list_head waiting;
143 struct list_head done;
144 struct list_head list;
145};
146
147/**
148 * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
149 *
150 * @v4l2_dev: pointer to &struct v4l2_device
151 * @notifier: pointer to &struct v4l2_async_notifier
152 */
153int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
154 struct v4l2_async_notifier *notifier);
155
156/**
157 * v4l2_async_subdev_notifier_register - registers a subdevice asynchronous
158 * notifier for a sub-device
159 *
160 * @sd: pointer to &struct v4l2_subdev
161 * @notifier: pointer to &struct v4l2_async_notifier
162 */
163int v4l2_async_subdev_notifier_register(struct v4l2_subdev *sd,
164 struct v4l2_async_notifier *notifier);
165
166/**
167 * v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier
168 *
169 * @notifier: pointer to &struct v4l2_async_notifier
170 */
171void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
172
173/**
174 * v4l2_async_notifier_cleanup - clean up notifier resources
175 * @notifier: the notifier the resources of which are to be cleaned up
176 *
177 * Release memory resources related to a notifier, including the async
178 * sub-devices allocated for the purposes of the notifier but not the notifier
179 * itself. The user is responsible for calling this function to clean up the
180 * notifier after calling @v4l2_async_notifier_parse_fwnode_endpoints or
181 * @v4l2_fwnode_reference_parse_sensor_common.
182 *
183 * There is no harm from calling v4l2_async_notifier_cleanup in other
184 * cases as long as its memory has been zeroed after it has been
185 * allocated.
186 */
187void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier);
188
189/**
190 * v4l2_async_register_subdev - registers a sub-device to the asynchronous
191 * subdevice framework
192 *
193 * @sd: pointer to &struct v4l2_subdev
194 */
195int v4l2_async_register_subdev(struct v4l2_subdev *sd);
196
197/**
198 * v4l2_async_register_subdev_sensor_common - registers a sensor sub-device to
199 * the asynchronous sub-device
200 * framework and parse set up common
201 * sensor related devices
202 *
203 * @sd: pointer to struct &v4l2_subdev
204 *
205 * This function is just like v4l2_async_register_subdev() with the exception
206 * that calling it will also parse firmware interfaces for remote references
207 * using v4l2_async_notifier_parse_fwnode_sensor_common() and registers the
208 * async sub-devices. The sub-device is similarly unregistered by calling
209 * v4l2_async_unregister_subdev().
210 *
211 * While registered, the subdev module is marked as in-use.
212 *
213 * An error is returned if the module is no longer loaded on any attempts
214 * to register it.
215 */
216int __must_check v4l2_async_register_subdev_sensor_common(
217 struct v4l2_subdev *sd);
218
219/**
220 * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
221 * subdevice framework
222 *
223 * @sd: pointer to &struct v4l2_subdev
224 */
225void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
226#endif