]>
Commit | Line | Data |
---|---|---|
ca50c197 SA |
1 | /* |
2 | * V4L2 fwnode binding parsing library | |
3 | * | |
4 | * Copyright (c) 2016 Intel Corporation. | |
5 | * Author: Sakari Ailus <sakari.ailus@linux.intel.com> | |
6 | * | |
7 | * Copyright (C) 2012 - 2013 Samsung Electronics Co., Ltd. | |
8 | * Author: Sylwester Nawrocki <s.nawrocki@samsung.com> | |
9 | * | |
10 | * Copyright (C) 2012 Renesas Electronics Corp. | |
11 | * Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> | |
12 | * | |
13 | * This program is free software; you can redistribute it and/or modify | |
14 | * it under the terms of version 2 of the GNU General Public License as | |
15 | * published by the Free Software Foundation. | |
16 | */ | |
17 | #ifndef _V4L2_FWNODE_H | |
18 | #define _V4L2_FWNODE_H | |
19 | ||
20 | #include <linux/errno.h> | |
21 | #include <linux/fwnode.h> | |
22 | #include <linux/list.h> | |
23 | #include <linux/types.h> | |
24 | ||
25 | #include <media/v4l2-mediabus.h> | |
1634f0ed | 26 | #include <media/v4l2-subdev.h> |
ca50c197 SA |
27 | |
28 | struct fwnode_handle; | |
9ca46531 SA |
29 | struct v4l2_async_notifier; |
30 | struct v4l2_async_subdev; | |
ca50c197 | 31 | |
ad3cdf3e | 32 | #define V4L2_FWNODE_CSI2_MAX_DATA_LANES 4 |
4ee23621 | 33 | |
ca50c197 SA |
34 | /** |
35 | * struct v4l2_fwnode_bus_mipi_csi2 - MIPI CSI-2 bus data structure | |
36 | * @flags: media bus (V4L2_MBUS_*) flags | |
37 | * @data_lanes: an array of physical data lane indexes | |
38 | * @clock_lane: physical lane index of the clock lane | |
39 | * @num_data_lanes: number of data lanes | |
40 | * @lane_polarities: polarity of the lanes. The order is the same of | |
41 | * the physical lanes. | |
42 | */ | |
43 | struct v4l2_fwnode_bus_mipi_csi2 { | |
44 | unsigned int flags; | |
ad3cdf3e | 45 | unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES]; |
ca50c197 SA |
46 | unsigned char clock_lane; |
47 | unsigned short num_data_lanes; | |
ad3cdf3e | 48 | bool lane_polarities[1 + V4L2_FWNODE_CSI2_MAX_DATA_LANES]; |
ca50c197 SA |
49 | }; |
50 | ||
51 | /** | |
52 | * struct v4l2_fwnode_bus_parallel - parallel data bus data structure | |
53 | * @flags: media bus (V4L2_MBUS_*) flags | |
54 | * @bus_width: bus width in bits | |
55 | * @data_shift: data shift in bits | |
56 | */ | |
57 | struct v4l2_fwnode_bus_parallel { | |
58 | unsigned int flags; | |
59 | unsigned char bus_width; | |
60 | unsigned char data_shift; | |
61 | }; | |
62 | ||
97bbdf02 SA |
63 | /** |
64 | * struct v4l2_fwnode_bus_mipi_csi1 - CSI-1/CCP2 data bus structure | |
65 | * @clock_inv: polarity of clock/strobe signal | |
66 | * false - not inverted, true - inverted | |
67 | * @strobe: false - data/clock, true - data/strobe | |
68 | * @lane_polarity: the polarities of the clock (index 0) and data lanes | |
8382a11b | 69 | * index (1) |
97bbdf02 SA |
70 | * @data_lane: the number of the data lane |
71 | * @clock_lane: the number of the clock lane | |
72 | */ | |
73 | struct v4l2_fwnode_bus_mipi_csi1 { | |
6087b215 MCC |
74 | unsigned char clock_inv:1; |
75 | unsigned char strobe:1; | |
97bbdf02 SA |
76 | bool lane_polarity[2]; |
77 | unsigned char data_lane; | |
78 | unsigned char clock_lane; | |
79 | }; | |
80 | ||
ca50c197 SA |
81 | /** |
82 | * struct v4l2_fwnode_endpoint - the endpoint data structure | |
83 | * @base: fwnode endpoint of the v4l2_fwnode | |
84 | * @bus_type: bus type | |
d63a9ef2 MCC |
85 | * @bus: union with bus configuration data structure |
86 | * @bus.parallel: embedded &struct v4l2_fwnode_bus_parallel. | |
87 | * Used if the bus is parallel. | |
88 | * @bus.mipi_csi1: embedded &struct v4l2_fwnode_bus_mipi_csi1. | |
89 | * Used if the bus is MIPI Alliance's Camera Serial | |
90 | * Interface version 1 (MIPI CSI1) or Standard | |
91 | * Mobile Imaging Architecture's Compact Camera Port 2 | |
92 | * (SMIA CCP2). | |
93 | * @bus.mipi_csi2: embedded &struct v4l2_fwnode_bus_mipi_csi2. | |
94 | * Used if the bus is MIPI Alliance's Camera Serial | |
95 | * Interface version 2 (MIPI CSI2). | |
ca50c197 SA |
96 | * @link_frequencies: array of supported link frequencies |
97 | * @nr_of_link_frequencies: number of elements in link_frequenccies array | |
98 | */ | |
99 | struct v4l2_fwnode_endpoint { | |
100 | struct fwnode_endpoint base; | |
101 | /* | |
102 | * Fields below this line will be zeroed by | |
a2b2eff6 | 103 | * v4l2_fwnode_endpoint_parse() |
ca50c197 SA |
104 | */ |
105 | enum v4l2_mbus_type bus_type; | |
106 | union { | |
107 | struct v4l2_fwnode_bus_parallel parallel; | |
97bbdf02 | 108 | struct v4l2_fwnode_bus_mipi_csi1 mipi_csi1; |
ca50c197 SA |
109 | struct v4l2_fwnode_bus_mipi_csi2 mipi_csi2; |
110 | } bus; | |
111 | u64 *link_frequencies; | |
112 | unsigned int nr_of_link_frequencies; | |
113 | }; | |
114 | ||
115 | /** | |
116 | * struct v4l2_fwnode_link - a link between two endpoints | |
117 | * @local_node: pointer to device_node of this endpoint | |
118 | * @local_port: identifier of the port this endpoint belongs to | |
119 | * @remote_node: pointer to device_node of the remote endpoint | |
120 | * @remote_port: identifier of the port the remote endpoint belongs to | |
121 | */ | |
122 | struct v4l2_fwnode_link { | |
123 | struct fwnode_handle *local_node; | |
124 | unsigned int local_port; | |
125 | struct fwnode_handle *remote_node; | |
126 | unsigned int remote_port; | |
127 | }; | |
128 | ||
baf249e4 SA |
129 | /** |
130 | * v4l2_fwnode_endpoint_parse() - parse all fwnode node properties | |
131 | * @fwnode: pointer to the endpoint's fwnode handle | |
132 | * @vep: pointer to the V4L2 fwnode data structure | |
133 | * | |
2e6e3932 SA |
134 | * This function parses the V4L2 fwnode endpoint specific parameters from the |
135 | * firmware. The caller is responsible for assigning @vep.bus_type to a valid | |
136 | * media bus type. The caller may also set the default configuration for the | |
137 | * endpoint --- a configuration that shall be in line with the DT binding | |
138 | * documentation. Should a device support multiple bus types, the caller may | |
139 | * call this function once the correct type is found --- with a default | |
140 | * configuration valid for that type. | |
141 | * | |
142 | * As a compatibility means guessing the bus type is also supported by setting | |
143 | * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default | |
144 | * configuration in this case as the defaults are specific to a given bus type. | |
145 | * This functionality is deprecated and should not be used in new drivers and it | |
146 | * is only supported for CSI-2 D-PHY, parallel and Bt.656 busses. | |
147 | * | |
148 | * The function does not change the V4L2 fwnode endpoint state if it fails. | |
60359a28 | 149 | * |
baf249e4 SA |
150 | * NOTE: This function does not parse properties the size of which is variable |
151 | * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in | |
152 | * new drivers instead. | |
153 | * | |
2e6e3932 SA |
154 | * Return: %0 on success or a negative error code on failure: |
155 | * %-ENOMEM on memory allocation failure | |
156 | * %-EINVAL on parsing failure | |
157 | * %-ENXIO on mismatching bus types | |
baf249e4 | 158 | */ |
ca50c197 SA |
159 | int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode, |
160 | struct v4l2_fwnode_endpoint *vep); | |
baf249e4 SA |
161 | |
162 | /** | |
163 | * v4l2_fwnode_endpoint_free() - free the V4L2 fwnode acquired by | |
164 | * v4l2_fwnode_endpoint_alloc_parse() | |
165 | * @vep: the V4L2 fwnode the resources of which are to be released | |
166 | * | |
167 | * It is safe to call this function with NULL argument or on a V4L2 fwnode the | |
168 | * parsing of which failed. | |
169 | */ | |
170 | void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); | |
171 | ||
172 | /** | |
173 | * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties | |
174 | * @fwnode: pointer to the endpoint's fwnode handle | |
6970d37c | 175 | * @vep: pointer to the V4L2 fwnode data structure |
baf249e4 | 176 | * |
2e6e3932 SA |
177 | * This function parses the V4L2 fwnode endpoint specific parameters from the |
178 | * firmware. The caller is responsible for assigning @vep.bus_type to a valid | |
179 | * media bus type. The caller may also set the default configuration for the | |
180 | * endpoint --- a configuration that shall be in line with the DT binding | |
181 | * documentation. Should a device support multiple bus types, the caller may | |
182 | * call this function once the correct type is found --- with a default | |
183 | * configuration valid for that type. | |
184 | * | |
185 | * As a compatibility means guessing the bus type is also supported by setting | |
186 | * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default | |
187 | * configuration in this case as the defaults are specific to a given bus type. | |
188 | * This functionality is deprecated and should not be used in new drivers and it | |
189 | * is only supported for CSI-2 D-PHY, parallel and Bt.656 busses. | |
baf249e4 | 190 | * |
2e6e3932 | 191 | * The function does not change the V4L2 fwnode endpoint state if it fails. |
6970d37c | 192 | * |
baf249e4 SA |
193 | * v4l2_fwnode_endpoint_alloc_parse() has two important differences to |
194 | * v4l2_fwnode_endpoint_parse(): | |
195 | * | |
196 | * 1. It also parses variable size data. | |
197 | * | |
198 | * 2. The memory it has allocated to store the variable size data must be freed | |
199 | * using v4l2_fwnode_endpoint_free() when no longer needed. | |
200 | * | |
2e6e3932 SA |
201 | * Return: %0 on success or a negative error code on failure: |
202 | * %-ENOMEM on memory allocation failure | |
203 | * %-EINVAL on parsing failure | |
204 | * %-ENXIO on mismatching bus types | |
baf249e4 | 205 | */ |
6087b215 MCC |
206 | int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode, |
207 | struct v4l2_fwnode_endpoint *vep); | |
baf249e4 SA |
208 | |
209 | /** | |
210 | * v4l2_fwnode_parse_link() - parse a link between two endpoints | |
211 | * @fwnode: pointer to the endpoint's fwnode at the local end of the link | |
212 | * @link: pointer to the V4L2 fwnode link data structure | |
213 | * | |
214 | * Fill the link structure with the local and remote nodes and port numbers. | |
215 | * The local_node and remote_node fields are set to point to the local and | |
216 | * remote port's parent nodes respectively (the port parent node being the | |
217 | * parent node of the port node if that node isn't a 'ports' node, or the | |
218 | * grand-parent node of the port node otherwise). | |
219 | * | |
220 | * A reference is taken to both the local and remote nodes, the caller must use | |
221 | * v4l2_fwnode_put_link() to drop the references when done with the | |
222 | * link. | |
223 | * | |
224 | * Return: 0 on success, or -ENOLINK if the remote endpoint fwnode can't be | |
225 | * found. | |
226 | */ | |
ca50c197 SA |
227 | int v4l2_fwnode_parse_link(struct fwnode_handle *fwnode, |
228 | struct v4l2_fwnode_link *link); | |
baf249e4 SA |
229 | |
230 | /** | |
231 | * v4l2_fwnode_put_link() - drop references to nodes in a link | |
232 | * @link: pointer to the V4L2 fwnode link data structure | |
233 | * | |
234 | * Drop references to the local and remote nodes in the link. This function | |
235 | * must be called on every link parsed with v4l2_fwnode_parse_link(). | |
236 | */ | |
ca50c197 SA |
237 | void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link); |
238 | ||
e2cec865 MCC |
239 | /** |
240 | * typedef parse_endpoint_func - Driver's callback function to be called on | |
241 | * each V4L2 fwnode endpoint. | |
242 | * | |
243 | * @dev: pointer to &struct device | |
244 | * @vep: pointer to &struct v4l2_fwnode_endpoint | |
245 | * @asd: pointer to &struct v4l2_async_subdev | |
246 | * | |
247 | * Return: | |
248 | * * %0 on success | |
249 | * * %-ENOTCONN if the endpoint is to be skipped but this | |
250 | * should not be considered as an error | |
251 | * * %-EINVAL if the endpoint configuration is invalid | |
252 | */ | |
253 | typedef int (*parse_endpoint_func)(struct device *dev, | |
254 | struct v4l2_fwnode_endpoint *vep, | |
255 | struct v4l2_async_subdev *asd); | |
256 | ||
9ca46531 SA |
257 | /** |
258 | * v4l2_async_notifier_parse_fwnode_endpoints - Parse V4L2 fwnode endpoints in a | |
259 | * device node | |
260 | * @dev: the device the endpoints of which are to be parsed | |
261 | * @notifier: notifier for @dev | |
262 | * @asd_struct_size: size of the driver's async sub-device struct, including | |
263 | * sizeof(struct v4l2_async_subdev). The &struct | |
264 | * v4l2_async_subdev shall be the first member of | |
265 | * the driver's async sub-device struct, i.e. both | |
266 | * begin at the same memory address. | |
267 | * @parse_endpoint: Driver's callback function called on each V4L2 fwnode | |
268 | * endpoint. Optional. | |
9ca46531 SA |
269 | * |
270 | * Parse the fwnode endpoints of the @dev device and populate the async sub- | |
eae2aed1 | 271 | * devices list in the notifier. The @parse_endpoint callback function is |
9ca46531 SA |
272 | * called for each endpoint with the corresponding async sub-device pointer to |
273 | * let the caller initialize the driver-specific part of the async sub-device | |
274 | * structure. | |
275 | * | |
276 | * The notifier memory shall be zeroed before this function is called on the | |
277 | * notifier. | |
278 | * | |
279 | * This function may not be called on a registered notifier and may be called on | |
280 | * a notifier only once. | |
281 | * | |
9ca46531 SA |
282 | * The &struct v4l2_fwnode_endpoint passed to the callback function |
283 | * @parse_endpoint is released once the function is finished. If there is a need | |
284 | * to retain that configuration, the user needs to allocate memory for it. | |
285 | * | |
286 | * Any notifier populated using this function must be released with a call to | |
287 | * v4l2_async_notifier_cleanup() after it has been unregistered and the async | |
288 | * sub-devices are no longer in use, even if the function returned an error. | |
289 | * | |
290 | * Return: %0 on success, including when no async sub-devices are found | |
291 | * %-ENOMEM if memory allocation failed | |
292 | * %-EINVAL if graph or endpoint parsing failed | |
293 | * Other error codes as returned by @parse_endpoint | |
294 | */ | |
6087b215 MCC |
295 | int |
296 | v4l2_async_notifier_parse_fwnode_endpoints(struct device *dev, | |
297 | struct v4l2_async_notifier *notifier, | |
298 | size_t asd_struct_size, | |
299 | parse_endpoint_func parse_endpoint); | |
9ca46531 SA |
300 | |
301 | /** | |
302 | * v4l2_async_notifier_parse_fwnode_endpoints_by_port - Parse V4L2 fwnode | |
303 | * endpoints of a port in a | |
304 | * device node | |
305 | * @dev: the device the endpoints of which are to be parsed | |
306 | * @notifier: notifier for @dev | |
307 | * @asd_struct_size: size of the driver's async sub-device struct, including | |
308 | * sizeof(struct v4l2_async_subdev). The &struct | |
309 | * v4l2_async_subdev shall be the first member of | |
310 | * the driver's async sub-device struct, i.e. both | |
311 | * begin at the same memory address. | |
312 | * @port: port number where endpoints are to be parsed | |
313 | * @parse_endpoint: Driver's callback function called on each V4L2 fwnode | |
314 | * endpoint. Optional. | |
9ca46531 SA |
315 | * |
316 | * This function is just like v4l2_async_notifier_parse_fwnode_endpoints() with | |
317 | * the exception that it only parses endpoints in a given port. This is useful | |
318 | * on devices that have both sinks and sources: the async sub-devices connected | |
319 | * to sources have already been configured by another driver (on capture | |
320 | * devices). In this case the driver must know which ports to parse. | |
321 | * | |
322 | * Parse the fwnode endpoints of the @dev device on a given @port and populate | |
eae2aed1 | 323 | * the async sub-devices list of the notifier. The @parse_endpoint callback |
9ca46531 SA |
324 | * function is called for each endpoint with the corresponding async sub-device |
325 | * pointer to let the caller initialize the driver-specific part of the async | |
326 | * sub-device structure. | |
327 | * | |
328 | * The notifier memory shall be zeroed before this function is called on the | |
329 | * notifier the first time. | |
330 | * | |
331 | * This function may not be called on a registered notifier and may be called on | |
332 | * a notifier only once per port. | |
333 | * | |
9ca46531 SA |
334 | * The &struct v4l2_fwnode_endpoint passed to the callback function |
335 | * @parse_endpoint is released once the function is finished. If there is a need | |
336 | * to retain that configuration, the user needs to allocate memory for it. | |
337 | * | |
338 | * Any notifier populated using this function must be released with a call to | |
339 | * v4l2_async_notifier_cleanup() after it has been unregistered and the async | |
340 | * sub-devices are no longer in use, even if the function returned an error. | |
341 | * | |
342 | * Return: %0 on success, including when no async sub-devices are found | |
343 | * %-ENOMEM if memory allocation failed | |
344 | * %-EINVAL if graph or endpoint parsing failed | |
345 | * Other error codes as returned by @parse_endpoint | |
346 | */ | |
6087b215 MCC |
347 | int |
348 | v4l2_async_notifier_parse_fwnode_endpoints_by_port(struct device *dev, | |
349 | struct v4l2_async_notifier *notifier, | |
350 | size_t asd_struct_size, unsigned int port, | |
351 | parse_endpoint_func parse_endpoint); | |
9ca46531 | 352 | |
7a9ec808 SA |
353 | /** |
354 | * v4l2_fwnode_reference_parse_sensor_common - parse common references on | |
355 | * sensors for async sub-devices | |
356 | * @dev: the device node the properties of which are parsed for references | |
357 | * @notifier: the async notifier where the async subdevs will be added | |
358 | * | |
359 | * Parse common sensor properties for remote devices related to the | |
360 | * sensor and set up async sub-devices for them. | |
361 | * | |
362 | * Any notifier populated using this function must be released with a call to | |
363 | * v4l2_async_notifier_release() after it has been unregistered and the async | |
364 | * sub-devices are no longer in use, even in the case the function returned an | |
365 | * error. | |
366 | * | |
367 | * Return: 0 on success | |
368 | * -ENOMEM if memory allocation failed | |
369 | * -EINVAL if property parsing failed | |
370 | */ | |
6087b215 MCC |
371 | int v4l2_async_notifier_parse_fwnode_sensor_common(struct device *dev, |
372 | struct v4l2_async_notifier *notifier); | |
7a9ec808 | 373 | |
1634f0ed SL |
374 | /** |
375 | * v4l2_async_register_fwnode_subdev - registers a sub-device to the | |
376 | * asynchronous sub-device framework | |
377 | * and parses fwnode endpoints | |
378 | * | |
379 | * @sd: pointer to struct &v4l2_subdev | |
380 | * @asd_struct_size: size of the driver's async sub-device struct, including | |
381 | * sizeof(struct v4l2_async_subdev). The &struct | |
382 | * v4l2_async_subdev shall be the first member of | |
383 | * the driver's async sub-device struct, i.e. both | |
384 | * begin at the same memory address. | |
385 | * @ports: array of port id's to parse for fwnode endpoints. If NULL, will | |
386 | * parse all ports owned by the sub-device. | |
387 | * @num_ports: number of ports in @ports array. Ignored if @ports is NULL. | |
388 | * @parse_endpoint: Driver's callback function called on each V4L2 fwnode | |
389 | * endpoint. Optional. | |
390 | * | |
391 | * This function is just like v4l2_async_register_subdev() with the | |
392 | * exception that calling it will also allocate a notifier for the | |
393 | * sub-device, parse the sub-device's firmware node endpoints using | |
394 | * v4l2_async_notifier_parse_fwnode_endpoints() or | |
395 | * v4l2_async_notifier_parse_fwnode_endpoints_by_port(), and | |
396 | * registers the sub-device notifier. The sub-device is similarly | |
397 | * unregistered by calling v4l2_async_unregister_subdev(). | |
398 | * | |
399 | * While registered, the subdev module is marked as in-use. | |
400 | * | |
401 | * An error is returned if the module is no longer loaded on any attempts | |
402 | * to register it. | |
403 | */ | |
6087b215 MCC |
404 | int |
405 | v4l2_async_register_fwnode_subdev(struct v4l2_subdev *sd, | |
406 | size_t asd_struct_size, | |
407 | unsigned int *ports, | |
408 | unsigned int num_ports, | |
409 | int (*parse_endpoint)(struct device *dev, | |
410 | struct v4l2_fwnode_endpoint *vep, | |
411 | struct v4l2_async_subdev *asd)); | |
1634f0ed | 412 | |
ca50c197 | 413 | #endif /* _V4L2_FWNODE_H */ |