1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * V4L2 fwnode binding parsing library |
4 | * |
5 | * Copyright (c) 2016 Intel Corporation. |
6 | * Author: Sakari Ailus <sakari.ailus@linux.intel.com> |
7 | * |
8 | * Copyright (C) 2012 - 2013 Samsung Electronics Co., Ltd. |
9 | * Author: Sylwester Nawrocki <s.nawrocki@samsung.com> |
10 | * |
11 | * Copyright (C) 2012 Renesas Electronics Corp. |
12 | * Author: Guennadi Liakhovetski <g.liakhovetski@gmx.de> |
13 | */ |
14 | #ifndef _V4L2_FWNODE_H |
15 | #define _V4L2_FWNODE_H |
16 | |
17 | #include <linux/errno.h> |
18 | #include <linux/fwnode.h> |
19 | #include <linux/list.h> |
20 | #include <linux/types.h> |
21 | |
22 | #include <media/v4l2-mediabus.h> |
23 | |
24 | /** |
25 | * struct v4l2_fwnode_endpoint - the endpoint data structure |
26 | * @base: fwnode endpoint of the v4l2_fwnode |
27 | * @bus_type: bus type |
28 | * @bus: bus configuration data structure |
29 | * @bus.parallel: embedded &struct v4l2_mbus_config_parallel. |
30 | * Used if the bus is parallel. |
31 | * @bus.mipi_csi1: embedded &struct v4l2_mbus_config_mipi_csi1. |
32 | * Used if the bus is MIPI Alliance's Camera Serial |
33 | * Interface version 1 (MIPI CSI1) or Standard |
34 | * Mobile Imaging Architecture's Compact Camera Port 2 |
35 | * (SMIA CCP2). |
36 | * @bus.mipi_csi2: embedded &struct v4l2_mbus_config_mipi_csi2. |
37 | * Used if the bus is MIPI Alliance's Camera Serial |
38 | * Interface version 2 (MIPI CSI2). |
39 | * @link_frequencies: array of supported link frequencies |
40 | * @nr_of_link_frequencies: number of elements in link_frequenccies array |
41 | */ |
42 | struct v4l2_fwnode_endpoint { |
43 | struct fwnode_endpoint base; |
44 | enum v4l2_mbus_type bus_type; |
45 | struct { |
46 | struct v4l2_mbus_config_parallel parallel; |
47 | struct v4l2_mbus_config_mipi_csi1 mipi_csi1; |
48 | struct v4l2_mbus_config_mipi_csi2 mipi_csi2; |
49 | } bus; |
50 | u64 *link_frequencies; |
51 | unsigned int nr_of_link_frequencies; |
52 | }; |
53 | |
54 | /** |
55 | * V4L2_FWNODE_PROPERTY_UNSET - identify a non initialized property |
56 | * |
57 | * All properties in &struct v4l2_fwnode_device_properties are initialized |
58 | * to this value. |
59 | */ |
60 | #define V4L2_FWNODE_PROPERTY_UNSET (-1U) |
61 | |
62 | /** |
63 | * enum v4l2_fwnode_orientation - possible device orientation |
64 | * @V4L2_FWNODE_ORIENTATION_FRONT: device installed on the front side |
65 | * @V4L2_FWNODE_ORIENTATION_BACK: device installed on the back side |
66 | * @V4L2_FWNODE_ORIENTATION_EXTERNAL: device externally located |
67 | */ |
68 | enum v4l2_fwnode_orientation { |
69 | V4L2_FWNODE_ORIENTATION_FRONT, |
70 | V4L2_FWNODE_ORIENTATION_BACK, |
71 | V4L2_FWNODE_ORIENTATION_EXTERNAL |
72 | }; |
73 | |
74 | /** |
75 | * struct v4l2_fwnode_device_properties - fwnode device properties |
76 | * @orientation: device orientation. See &enum v4l2_fwnode_orientation |
77 | * @rotation: device rotation |
78 | */ |
79 | struct v4l2_fwnode_device_properties { |
80 | enum v4l2_fwnode_orientation orientation; |
81 | unsigned int rotation; |
82 | }; |
83 | |
84 | /** |
85 | * struct v4l2_fwnode_link - a link between two endpoints |
86 | * @local_node: pointer to device_node of this endpoint |
87 | * @local_port: identifier of the port this endpoint belongs to |
88 | * @local_id: identifier of the id this endpoint belongs to |
89 | * @remote_node: pointer to device_node of the remote endpoint |
90 | * @remote_port: identifier of the port the remote endpoint belongs to |
91 | * @remote_id: identifier of the id the remote endpoint belongs to |
92 | */ |
93 | struct v4l2_fwnode_link { |
94 | struct fwnode_handle *local_node; |
95 | unsigned int local_port; |
96 | unsigned int local_id; |
97 | struct fwnode_handle *remote_node; |
98 | unsigned int remote_port; |
99 | unsigned int remote_id; |
100 | }; |
101 | |
102 | /** |
103 | * enum v4l2_connector_type - connector type |
104 | * @V4L2_CONN_UNKNOWN: unknown connector type, no V4L2 connector configuration |
105 | * @V4L2_CONN_COMPOSITE: analog composite connector |
106 | * @V4L2_CONN_SVIDEO: analog svideo connector |
107 | */ |
108 | enum v4l2_connector_type { |
109 | V4L2_CONN_UNKNOWN, |
110 | V4L2_CONN_COMPOSITE, |
111 | V4L2_CONN_SVIDEO, |
112 | }; |
113 | |
114 | /** |
115 | * struct v4l2_connector_link - connector link data structure |
116 | * @head: structure to be used to add the link to the |
117 | * &struct v4l2_fwnode_connector |
118 | * @fwnode_link: &struct v4l2_fwnode_link link between the connector and the |
119 | * device the connector belongs to. |
120 | */ |
121 | struct v4l2_connector_link { |
122 | struct list_head head; |
123 | struct v4l2_fwnode_link fwnode_link; |
124 | }; |
125 | |
126 | /** |
127 | * struct v4l2_fwnode_connector_analog - analog connector data structure |
128 | * @sdtv_stds: sdtv standards this connector supports, set to V4L2_STD_ALL |
129 | * if no restrictions are specified. |
130 | */ |
131 | struct v4l2_fwnode_connector_analog { |
132 | v4l2_std_id sdtv_stds; |
133 | }; |
134 | |
135 | /** |
136 | * struct v4l2_fwnode_connector - the connector data structure |
137 | * @name: the connector device name |
138 | * @label: optional connector label |
139 | * @type: connector type |
140 | * @links: list of all connector &struct v4l2_connector_link links |
141 | * @nr_of_links: total number of links |
142 | * @connector: connector configuration |
143 | * @connector.analog: analog connector configuration |
144 | * &struct v4l2_fwnode_connector_analog |
145 | */ |
146 | struct v4l2_fwnode_connector { |
147 | const char *name; |
148 | const char *label; |
149 | enum v4l2_connector_type type; |
150 | struct list_head links; |
151 | unsigned int nr_of_links; |
152 | |
153 | union { |
154 | struct v4l2_fwnode_connector_analog analog; |
155 | /* future connectors */ |
156 | } connector; |
157 | }; |
158 | |
159 | /** |
160 | * enum v4l2_fwnode_bus_type - Video bus types defined by firmware properties |
161 | * @V4L2_FWNODE_BUS_TYPE_GUESS: Default value if no bus-type fwnode property |
162 | * @V4L2_FWNODE_BUS_TYPE_CSI2_CPHY: MIPI CSI-2 bus, C-PHY physical layer |
163 | * @V4L2_FWNODE_BUS_TYPE_CSI1: MIPI CSI-1 bus |
164 | * @V4L2_FWNODE_BUS_TYPE_CCP2: SMIA Compact Camera Port 2 bus |
165 | * @V4L2_FWNODE_BUS_TYPE_CSI2_DPHY: MIPI CSI-2 bus, D-PHY physical layer |
166 | * @V4L2_FWNODE_BUS_TYPE_PARALLEL: Camera Parallel Interface bus |
167 | * @V4L2_FWNODE_BUS_TYPE_BT656: BT.656 video format bus-type |
168 | * @V4L2_FWNODE_BUS_TYPE_DPI: Video Parallel Interface bus |
169 | * @NR_OF_V4L2_FWNODE_BUS_TYPE: Number of bus-types |
170 | */ |
171 | enum v4l2_fwnode_bus_type { |
172 | V4L2_FWNODE_BUS_TYPE_GUESS = 0, |
173 | V4L2_FWNODE_BUS_TYPE_CSI2_CPHY, |
174 | V4L2_FWNODE_BUS_TYPE_CSI1, |
175 | V4L2_FWNODE_BUS_TYPE_CCP2, |
176 | V4L2_FWNODE_BUS_TYPE_CSI2_DPHY, |
177 | V4L2_FWNODE_BUS_TYPE_PARALLEL, |
178 | V4L2_FWNODE_BUS_TYPE_BT656, |
179 | V4L2_FWNODE_BUS_TYPE_DPI, |
180 | NR_OF_V4L2_FWNODE_BUS_TYPE |
181 | }; |
182 | |
183 | /** |
184 | * v4l2_fwnode_endpoint_parse() - parse all fwnode node properties |
185 | * @fwnode: pointer to the endpoint's fwnode handle |
186 | * @vep: pointer to the V4L2 fwnode data structure |
187 | * |
188 | * This function parses the V4L2 fwnode endpoint specific parameters from the |
189 | * firmware. There are two ways to use this function, either by letting it |
190 | * obtain the type of the bus (by setting the @vep.bus_type field to |
191 | * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum |
192 | * v4l2_mbus_type types. |
193 | * |
194 | * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type" |
195 | * property to determine the type when it is available. The caller is |
196 | * responsible for validating the contents of @vep.bus_type field after the call |
197 | * returns. |
198 | * |
199 | * As a deprecated functionality to support older DT bindings without "bus-type" |
200 | * property for devices that support multiple types, if the "bus-type" property |
201 | * does not exist, the function will attempt to guess the type based on the |
202 | * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW |
203 | * DRIVERS OR BINDINGS. |
204 | * |
205 | * It is also possible to set @vep.bus_type corresponding to an actual bus. In |
206 | * this case the function will only attempt to parse properties related to this |
207 | * bus, and it will return an error if the value of the "bus-type" property |
208 | * corresponds to a different bus. |
209 | * |
210 | * The caller is required to initialise all fields of @vep, either with |
211 | * explicitly values, or by zeroing them. |
212 | * |
213 | * The function does not change the V4L2 fwnode endpoint state if it fails. |
214 | * |
215 | * NOTE: This function does not parse "link-frequencies" property as its size is |
216 | * not known in advance. Please use v4l2_fwnode_endpoint_alloc_parse() if you |
217 | * need properties of variable size. |
218 | * |
219 | * Return: %0 on success or a negative error code on failure: |
220 | * %-ENOMEM on memory allocation failure |
221 | * %-EINVAL on parsing failure |
222 | * %-ENXIO on mismatching bus types |
223 | */ |
224 | int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode, |
225 | struct v4l2_fwnode_endpoint *vep); |
226 | |
227 | /** |
228 | * v4l2_fwnode_endpoint_free() - free the V4L2 fwnode acquired by |
229 | * v4l2_fwnode_endpoint_alloc_parse() |
230 | * @vep: the V4L2 fwnode the resources of which are to be released |
231 | * |
232 | * It is safe to call this function with NULL argument or on a V4L2 fwnode the |
233 | * parsing of which failed. |
234 | */ |
235 | void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); |
236 | |
237 | /** |
238 | * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties |
239 | * @fwnode: pointer to the endpoint's fwnode handle |
240 | * @vep: pointer to the V4L2 fwnode data structure |
241 | * |
242 | * This function parses the V4L2 fwnode endpoint specific parameters from the |
243 | * firmware. There are two ways to use this function, either by letting it |
244 | * obtain the type of the bus (by setting the @vep.bus_type field to |
245 | * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum |
246 | * v4l2_mbus_type types. |
247 | * |
248 | * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type" |
249 | * property to determine the type when it is available. The caller is |
250 | * responsible for validating the contents of @vep.bus_type field after the call |
251 | * returns. |
252 | * |
253 | * As a deprecated functionality to support older DT bindings without "bus-type" |
254 | * property for devices that support multiple types, if the "bus-type" property |
255 | * does not exist, the function will attempt to guess the type based on the |
256 | * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW |
257 | * DRIVERS OR BINDINGS. |
258 | * |
259 | * It is also possible to set @vep.bus_type corresponding to an actual bus. In |
260 | * this case the function will only attempt to parse properties related to this |
261 | * bus, and it will return an error if the value of the "bus-type" property |
262 | * corresponds to a different bus. |
263 | * |
264 | * The caller is required to initialise all fields of @vep, either with |
265 | * explicitly values, or by zeroing them. |
266 | * |
267 | * The function does not change the V4L2 fwnode endpoint state if it fails. |
268 | * |
269 | * v4l2_fwnode_endpoint_alloc_parse() has two important differences to |
270 | * v4l2_fwnode_endpoint_parse(): |
271 | * |
272 | * 1. It also parses variable size data. |
273 | * |
274 | * 2. The memory it has allocated to store the variable size data must be freed |
275 | * using v4l2_fwnode_endpoint_free() when no longer needed. |
276 | * |
277 | * Return: %0 on success or a negative error code on failure: |
278 | * %-ENOMEM on memory allocation failure |
279 | * %-EINVAL on parsing failure |
280 | * %-ENXIO on mismatching bus types |
281 | */ |
282 | int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode, |
283 | struct v4l2_fwnode_endpoint *vep); |
284 | |
285 | /** |
286 | * v4l2_fwnode_parse_link() - parse a link between two endpoints |
287 | * @fwnode: pointer to the endpoint's fwnode at the local end of the link |
288 | * @link: pointer to the V4L2 fwnode link data structure |
289 | * |
290 | * Fill the link structure with the local and remote nodes and port numbers. |
291 | * The local_node and remote_node fields are set to point to the local and |
292 | * remote port's parent nodes respectively (the port parent node being the |
293 | * parent node of the port node if that node isn't a 'ports' node, or the |
294 | * grand-parent node of the port node otherwise). |
295 | * |
296 | * A reference is taken to both the local and remote nodes, the caller must use |
297 | * v4l2_fwnode_put_link() to drop the references when done with the |
298 | * link. |
299 | * |
300 | * Return: 0 on success, or -ENOLINK if the remote endpoint fwnode can't be |
301 | * found. |
302 | */ |
303 | int v4l2_fwnode_parse_link(struct fwnode_handle *fwnode, |
304 | struct v4l2_fwnode_link *link); |
305 | |
306 | /** |
307 | * v4l2_fwnode_put_link() - drop references to nodes in a link |
308 | * @link: pointer to the V4L2 fwnode link data structure |
309 | * |
310 | * Drop references to the local and remote nodes in the link. This function |
311 | * must be called on every link parsed with v4l2_fwnode_parse_link(). |
312 | */ |
313 | void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link); |
314 | |
315 | /** |
316 | * v4l2_fwnode_connector_free() - free the V4L2 connector acquired memory |
317 | * @connector: the V4L2 connector resources of which are to be released |
318 | * |
319 | * Free all allocated memory and put all links acquired by |
320 | * v4l2_fwnode_connector_parse() and v4l2_fwnode_connector_add_link(). |
321 | * |
322 | * It is safe to call this function with NULL argument or on a V4L2 connector |
323 | * the parsing of which failed. |
324 | */ |
325 | void v4l2_fwnode_connector_free(struct v4l2_fwnode_connector *connector); |
326 | |
327 | /** |
328 | * v4l2_fwnode_connector_parse() - initialize the 'struct v4l2_fwnode_connector' |
329 | * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector |
330 | * is connected to or to the connector endpoint fwnode handle. |
331 | * @connector: pointer to the V4L2 fwnode connector data structure |
332 | * |
333 | * Fill the &struct v4l2_fwnode_connector with the connector type, label and |
334 | * all &enum v4l2_connector_type specific connector data. The label is optional |
335 | * so it is set to %NULL if no one was found. The function initialize the links |
336 | * to zero. Adding links to the connector is done by calling |
337 | * v4l2_fwnode_connector_add_link(). |
338 | * |
339 | * The memory allocated for the label must be freed when no longer needed. |
340 | * Freeing the memory is done by v4l2_fwnode_connector_free(). |
341 | * |
342 | * Return: |
343 | * * %0 on success or a negative error code on failure: |
344 | * * %-EINVAL if @fwnode is invalid |
345 | * * %-ENOTCONN if connector type is unknown or connector device can't be found |
346 | */ |
347 | int v4l2_fwnode_connector_parse(struct fwnode_handle *fwnode, |
348 | struct v4l2_fwnode_connector *connector); |
349 | |
350 | /** |
351 | * v4l2_fwnode_connector_add_link - add a link between a connector node and |
352 | * a v4l2-subdev node. |
353 | * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector |
354 | * is connected to |
355 | * @connector: pointer to the V4L2 fwnode connector data structure |
356 | * |
357 | * Add a new &struct v4l2_connector_link link to the |
358 | * &struct v4l2_fwnode_connector connector links list. The link local_node |
359 | * points to the connector node, the remote_node to the host v4l2 (sub)dev. |
360 | * |
361 | * The taken references to remote_node and local_node must be dropped and the |
362 | * allocated memory must be freed when no longer needed. Both is done by calling |
363 | * v4l2_fwnode_connector_free(). |
364 | * |
365 | * Return: |
366 | * * %0 on success or a negative error code on failure: |
367 | * * %-EINVAL if @fwnode or @connector is invalid or @connector type is unknown |
368 | * * %-ENOMEM on link memory allocation failure |
369 | * * %-ENOTCONN if remote connector device can't be found |
370 | * * %-ENOLINK if link parsing between v4l2 (sub)dev and connector fails |
371 | */ |
372 | int v4l2_fwnode_connector_add_link(struct fwnode_handle *fwnode, |
373 | struct v4l2_fwnode_connector *connector); |
374 | |
375 | /** |
376 | * v4l2_fwnode_device_parse() - parse fwnode device properties |
377 | * @dev: pointer to &struct device |
378 | * @props: pointer to &struct v4l2_fwnode_device_properties where to store the |
379 | * parsed properties values |
380 | * |
381 | * This function parses and validates the V4L2 fwnode device properties from the |
382 | * firmware interface, and fills the @struct v4l2_fwnode_device_properties |
383 | * provided by the caller. |
384 | * |
385 | * Return: |
386 | * % 0 on success |
387 | * %-EINVAL if a parsed property value is not valid |
388 | */ |
389 | int v4l2_fwnode_device_parse(struct device *dev, |
390 | struct v4l2_fwnode_device_properties *props); |
391 | |
392 | /* Helper macros to access the connector links. */ |
393 | |
394 | /** v4l2_connector_last_link - Helper macro to get the first |
395 | * &struct v4l2_fwnode_connector link |
396 | * @v4l2c: &struct v4l2_fwnode_connector owning the connector links |
397 | * |
398 | * This marco returns the first added &struct v4l2_connector_link connector |
399 | * link or @NULL if the connector has no links. |
400 | */ |
401 | #define v4l2_connector_first_link(v4l2c) \ |
402 | list_first_entry_or_null(&(v4l2c)->links, \ |
403 | struct v4l2_connector_link, head) |
404 | |
405 | /** v4l2_connector_last_link - Helper macro to get the last |
406 | * &struct v4l2_fwnode_connector link |
407 | * @v4l2c: &struct v4l2_fwnode_connector owning the connector links |
408 | * |
409 | * This marco returns the last &struct v4l2_connector_link added connector link. |
410 | */ |
411 | #define v4l2_connector_last_link(v4l2c) \ |
412 | list_last_entry(&(v4l2c)->links, struct v4l2_connector_link, head) |
413 | |
414 | #endif /* _V4L2_FWNODE_H */ |
415 | |