forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2023-12-08 01573e231f18eb2d99162747186f59511f56b64d 
 kernel/include/media/v4l2-fwnode.h
....@@ -1,3 +1,4 @@
1
+/* SPDX-License-Identifier: GPL-2.0-only */
12 /*
23  * V4L2 fwnode binding parsing library
34  *
....@@ -9,10 +10,6 @@
910  *
1011  * Copyright (C) 2012 Renesas Electronics Corp.
1112  * 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.
1613  */
1714 #ifndef _V4L2_FWNODE_H
1815 #define _V4L2_FWNODE_H
....@@ -43,7 +40,7 @@
4340 	unsigned int flags;
4441 	unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES];
4542 	unsigned char clock_lane;
46
-	unsigned short num_data_lanes;
43
+	unsigned char num_data_lanes;
4744 	bool lane_polarities[1 + V4L2_FWNODE_CSI2_MAX_DATA_LANES];
4845 };
4946 
....@@ -70,8 +67,8 @@
7067  * @clock_lane: the number of the clock lane
7168  */
7269 struct v4l2_fwnode_bus_mipi_csi1 {
73
-	bool clock_inv;
74
-	bool strobe;
70
+	unsigned char clock_inv:1;
71
+	unsigned char strobe:1;
7572 	bool lane_polarity[2];
7673 	unsigned char data_lane;
7774 	unsigned char clock_lane;
....@@ -81,7 +78,7 @@
8178  * struct v4l2_fwnode_endpoint - the endpoint data structure
8279  * @base: fwnode endpoint of the v4l2_fwnode
8380  * @bus_type: bus type
84
- * @bus: union with bus configuration data structure
81
+ * @bus: bus configuration data structure
8582  * @bus.parallel: embedded &struct v4l2_fwnode_bus_parallel.
8683  *		  Used if the bus is parallel.
8784  * @bus.mipi_csi1: embedded &struct v4l2_fwnode_bus_mipi_csi1.
....@@ -102,7 +99,7 @@
10299 	 * v4l2_fwnode_endpoint_parse()
103100 	 */
104101 	enum v4l2_mbus_type bus_type;
105
-	union {
102
+	struct {
106103 		struct v4l2_fwnode_bus_parallel parallel;
107104 		struct v4l2_fwnode_bus_mipi_csi1 mipi_csi1;
108105 		struct v4l2_fwnode_bus_mipi_csi2 mipi_csi2;
....@@ -112,17 +109,108 @@
112109 };
113110 
114111 /**
112
+ * V4L2_FWNODE_PROPERTY_UNSET - identify a non initialized property
113
+ *
114
+ * All properties in &struct v4l2_fwnode_device_properties are initialized
115
+ * to this value.
116
+ */
117
+#define V4L2_FWNODE_PROPERTY_UNSET   (-1U)
118
+
119
+/**
120
+ * enum v4l2_fwnode_orientation - possible device orientation
121
+ * @V4L2_FWNODE_ORIENTATION_FRONT: device installed on the front side
122
+ * @V4L2_FWNODE_ORIENTATION_BACK: device installed on the back side
123
+ * @V4L2_FWNODE_ORIENTATION_EXTERNAL: device externally located
124
+ */
125
+enum v4l2_fwnode_orientation {
126
+	V4L2_FWNODE_ORIENTATION_FRONT,
127
+	V4L2_FWNODE_ORIENTATION_BACK,
128
+	V4L2_FWNODE_ORIENTATION_EXTERNAL
129
+};
130
+
131
+/**
132
+ * struct v4l2_fwnode_device_properties - fwnode device properties
133
+ * @orientation: device orientation. See &enum v4l2_fwnode_orientation
134
+ * @rotation: device rotation
135
+ */
136
+struct v4l2_fwnode_device_properties {
137
+	enum v4l2_fwnode_orientation orientation;
138
+	unsigned int rotation;
139
+};
140
+
141
+/**
115142  * struct v4l2_fwnode_link - a link between two endpoints
116143  * @local_node: pointer to device_node of this endpoint
117144  * @local_port: identifier of the port this endpoint belongs to
145
+ * @local_id: identifier of the id this endpoint belongs to
118146  * @remote_node: pointer to device_node of the remote endpoint
119147  * @remote_port: identifier of the port the remote endpoint belongs to
148
+ * @remote_id: identifier of the id the remote endpoint belongs to
120149  */
121150 struct v4l2_fwnode_link {
122151 	struct fwnode_handle *local_node;
123152 	unsigned int local_port;
153
+	unsigned int local_id;
124154 	struct fwnode_handle *remote_node;
125155 	unsigned int remote_port;
156
+	unsigned int remote_id;
157
+};
158
+
159
+/**
160
+ * enum v4l2_connector_type - connector type
161
+ * @V4L2_CONN_UNKNOWN:   unknown connector type, no V4L2 connector configuration
162
+ * @V4L2_CONN_COMPOSITE: analog composite connector
163
+ * @V4L2_CONN_SVIDEO:    analog svideo connector
164
+ */
165
+enum v4l2_connector_type {
166
+	V4L2_CONN_UNKNOWN,
167
+	V4L2_CONN_COMPOSITE,
168
+	V4L2_CONN_SVIDEO,
169
+};
170
+
171
+/**
172
+ * struct v4l2_connector_link - connector link data structure
173
+ * @head: structure to be used to add the link to the
174
+ *        &struct v4l2_fwnode_connector
175
+ * @fwnode_link: &struct v4l2_fwnode_link link between the connector and the
176
+ *               device the connector belongs to.
177
+ */
178
+struct v4l2_connector_link {
179
+	struct list_head head;
180
+	struct v4l2_fwnode_link fwnode_link;
181
+};
182
+
183
+/**
184
+ * struct v4l2_fwnode_connector_analog - analog connector data structure
185
+ * @sdtv_stds: sdtv standards this connector supports, set to V4L2_STD_ALL
186
+ *             if no restrictions are specified.
187
+ */
188
+struct v4l2_fwnode_connector_analog {
189
+	v4l2_std_id sdtv_stds;
190
+};
191
+
192
+/**
193
+ * struct v4l2_fwnode_connector - the connector data structure
194
+ * @name: the connector device name
195
+ * @label: optional connector label
196
+ * @type: connector type
197
+ * @links: list of all connector &struct v4l2_connector_link links
198
+ * @nr_of_links: total number of links
199
+ * @connector: connector configuration
200
+ * @connector.analog: analog connector configuration
201
+ *                    &struct v4l2_fwnode_connector_analog
202
+ */
203
+struct v4l2_fwnode_connector {
204
+	const char *name;
205
+	const char *label;
206
+	enum v4l2_connector_type type;
207
+	struct list_head links;
208
+	unsigned int nr_of_links;
209
+
210
+	union {
211
+		struct v4l2_fwnode_connector_analog analog;
212
+		/* future connectors */
213
+	} connector;
126214 };
127215 
128216 /**
....@@ -130,19 +218,32 @@
130218  * @fwnode: pointer to the endpoint's fwnode handle
131219  * @vep: pointer to the V4L2 fwnode data structure
132220  *
133
- * All properties are optional. If none are found, we don't set any flags. This
134
- * means the port has a static configuration and no properties have to be
135
- * specified explicitly. If any properties that identify the bus as parallel
136
- * are found and slave-mode isn't set, we set V4L2_MBUS_MASTER. Similarly, if
137
- * we recognise the bus as serial CSI-2 and clock-noncontinuous isn't set, we
138
- * set the V4L2_MBUS_CSI2_CONTINUOUS_CLOCK flag. The caller should hold a
139
- * reference to @fwnode.
221
+ * This function parses the V4L2 fwnode endpoint specific parameters from the
222
+ * firmware. The caller is responsible for assigning @vep.bus_type to a valid
223
+ * media bus type. The caller may also set the default configuration for the
224
+ * endpoint --- a configuration that shall be in line with the DT binding
225
+ * documentation. Should a device support multiple bus types, the caller may
226
+ * call this function once the correct type is found --- with a default
227
+ * configuration valid for that type.
228
+ *
229
+ * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
230
+ * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
231
+ * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
232
+ * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
233
+ *
234
+ * The caller is required to initialise all fields of @vep, either with
235
+ * explicitly values, or by zeroing them.
236
+ *
237
+ * The function does not change the V4L2 fwnode endpoint state if it fails.
140238  *
141239  * NOTE: This function does not parse properties the size of which is variable
142240  * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in
143241  * new drivers instead.
144242  *
145
- * Return: 0 on success or a negative error code on failure.
243
+ * Return: %0 on success or a negative error code on failure:
244
+ *	   %-ENOMEM on memory allocation failure
245
+ *	   %-EINVAL on parsing failure
246
+ *	   %-ENXIO on mismatching bus types
146247  */
147248 int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode,
148249 			       struct v4l2_fwnode_endpoint *vep);
....@@ -160,14 +261,25 @@
160261 /**
161262  * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties
162263  * @fwnode: pointer to the endpoint's fwnode handle
264
+ * @vep: pointer to the V4L2 fwnode data structure
163265  *
164
- * All properties are optional. If none are found, we don't set any flags. This
165
- * means the port has a static configuration and no properties have to be
166
- * specified explicitly. If any properties that identify the bus as parallel
167
- * are found and slave-mode isn't set, we set V4L2_MBUS_MASTER. Similarly, if
168
- * we recognise the bus as serial CSI-2 and clock-noncontinuous isn't set, we
169
- * set the V4L2_MBUS_CSI2_CONTINUOUS_CLOCK flag. The caller should hold a
170
- * reference to @fwnode.
266
+ * This function parses the V4L2 fwnode endpoint specific parameters from the
267
+ * firmware. The caller is responsible for assigning @vep.bus_type to a valid
268
+ * media bus type. The caller may also set the default configuration for the
269
+ * endpoint --- a configuration that shall be in line with the DT binding
270
+ * documentation. Should a device support multiple bus types, the caller may
271
+ * call this function once the correct type is found --- with a default
272
+ * configuration valid for that type.
273
+ *
274
+ * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
275
+ * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
276
+ * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
277
+ * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
278
+ *
279
+ * The caller is required to initialise all fields of @vep, either with
280
+ * explicitly values, or by zeroing them.
281
+ *
282
+ * The function does not change the V4L2 fwnode endpoint state if it fails.
171283  *
172284  * v4l2_fwnode_endpoint_alloc_parse() has two important differences to
173285  * v4l2_fwnode_endpoint_parse():
....@@ -177,11 +289,13 @@
177289  * 2. The memory it has allocated to store the variable size data must be freed
178290  *    using v4l2_fwnode_endpoint_free() when no longer needed.
179291  *
180
- * Return: Pointer to v4l2_fwnode_endpoint if successful, on an error pointer
181
- * on error.
292
+ * Return: %0 on success or a negative error code on failure:
293
+ *	   %-ENOMEM on memory allocation failure
294
+ *	   %-EINVAL on parsing failure
295
+ *	   %-ENXIO on mismatching bus types
182296  */
183
-struct v4l2_fwnode_endpoint *v4l2_fwnode_endpoint_alloc_parse(
184
-	struct fwnode_handle *fwnode);
297
+int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode,
298
+				     struct v4l2_fwnode_endpoint *vep);
185299 
186300 /**
187301  * v4l2_fwnode_parse_link() - parse a link between two endpoints
....@@ -213,6 +327,82 @@
213327  */
214328 void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link);
215329 
330
+/**
331
+ * v4l2_fwnode_connector_free() - free the V4L2 connector acquired memory
332
+ * @connector: the V4L2 connector resources of which are to be released
333
+ *
334
+ * Free all allocated memory and put all links acquired by
335
+ * v4l2_fwnode_connector_parse() and v4l2_fwnode_connector_add_link().
336
+ *
337
+ * It is safe to call this function with NULL argument or on a V4L2 connector
338
+ * the parsing of which failed.
339
+ */
340
+void v4l2_fwnode_connector_free(struct v4l2_fwnode_connector *connector);
341
+
342
+/**
343
+ * v4l2_fwnode_connector_parse() - initialize the 'struct v4l2_fwnode_connector'
344
+ * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector
345
+ *	    is connected to or to the connector endpoint fwnode handle.
346
+ * @connector: pointer to the V4L2 fwnode connector data structure
347
+ *
348
+ * Fill the &struct v4l2_fwnode_connector with the connector type, label and
349
+ * all &enum v4l2_connector_type specific connector data. The label is optional
350
+ * so it is set to %NULL if no one was found. The function initialize the links
351
+ * to zero. Adding links to the connector is done by calling
352
+ * v4l2_fwnode_connector_add_link().
353
+ *
354
+ * The memory allocated for the label must be freed when no longer needed.
355
+ * Freeing the memory is done by v4l2_fwnode_connector_free().
356
+ *
357
+ * Return:
358
+ * * %0 on success or a negative error code on failure:
359
+ * * %-EINVAL if @fwnode is invalid
360
+ * * %-ENOTCONN if connector type is unknown or connector device can't be found
361
+ */
362
+int v4l2_fwnode_connector_parse(struct fwnode_handle *fwnode,
363
+				struct v4l2_fwnode_connector *connector);
364
+
365
+/**
366
+ * v4l2_fwnode_connector_add_link - add a link between a connector node and
367
+ *				    a v4l2-subdev node.
368
+ * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector
369
+ *          is connected to
370
+ * @connector: pointer to the V4L2 fwnode connector data structure
371
+ *
372
+ * Add a new &struct v4l2_connector_link link to the
373
+ * &struct v4l2_fwnode_connector connector links list. The link local_node
374
+ * points to the connector node, the remote_node to the host v4l2 (sub)dev.
375
+ *
376
+ * The taken references to remote_node and local_node must be dropped and the
377
+ * allocated memory must be freed when no longer needed. Both is done by calling
378
+ * v4l2_fwnode_connector_free().
379
+ *
380
+ * Return:
381
+ * * %0 on success or a negative error code on failure:
382
+ * * %-EINVAL if @fwnode or @connector is invalid or @connector type is unknown
383
+ * * %-ENOMEM on link memory allocation failure
384
+ * * %-ENOTCONN if remote connector device can't be found
385
+ * * %-ENOLINK if link parsing between v4l2 (sub)dev and connector fails
386
+ */
387
+int v4l2_fwnode_connector_add_link(struct fwnode_handle *fwnode,
388
+				   struct v4l2_fwnode_connector *connector);
389
+
390
+/**
391
+ * v4l2_fwnode_device_parse() - parse fwnode device properties
392
+ * @dev: pointer to &struct device
393
+ * @props: pointer to &struct v4l2_fwnode_device_properties where to store the
394
+ *	   parsed properties values
395
+ *
396
+ * This function parses and validates the V4L2 fwnode device properties from the
397
+ * firmware interface, and fills the @struct v4l2_fwnode_device_properties
398
+ * provided by the caller.
399
+ *
400
+ * Return:
401
+ *	% 0 on success
402
+ *	%-EINVAL if a parsed property value is not valid
403
+ */
404
+int v4l2_fwnode_device_parse(struct device *dev,
405
+			     struct v4l2_fwnode_device_properties *props);
216406 
217407 /**
218408  * typedef parse_endpoint_func - Driver's callback function to be called on
....@@ -232,7 +422,6 @@
232422 				  struct v4l2_fwnode_endpoint *vep,
233423 				  struct v4l2_async_subdev *asd);
234424 
235
-
236425 /**
237426  * v4l2_async_notifier_parse_fwnode_endpoints - Parse V4L2 fwnode endpoints in a
238427  *						device node
....@@ -247,7 +436,7 @@
247436  *		    endpoint. Optional.
248437  *
249438  * Parse the fwnode endpoints of the @dev device and populate the async sub-
250
- * devices array of the notifier. The @parse_endpoint callback function is
439
+ * devices list in the notifier. The @parse_endpoint callback function is
251440  * called for each endpoint with the corresponding async sub-device pointer to
252441  * let the caller initialize the driver-specific part of the async sub-device
253442  * structure.
....@@ -257,11 +446,6 @@
257446  *
258447  * This function may not be called on a registered notifier and may be called on
259448  * a notifier only once.
260
- *
261
- * Do not change the notifier's subdevs array, take references to the subdevs
262
- * array itself or change the notifier's num_subdevs field. This is because this
263
- * function allocates and reallocates the subdevs array based on parsing
264
- * endpoints.
265449  *
266450  * The &struct v4l2_fwnode_endpoint passed to the callback function
267451  * @parse_endpoint is released once the function is finished. If there is a need
....@@ -276,10 +460,11 @@
276460  *	   %-EINVAL if graph or endpoint parsing failed
277461  *	   Other error codes as returned by @parse_endpoint
278462  */
279
-int v4l2_async_notifier_parse_fwnode_endpoints(
280
-	struct device *dev, struct v4l2_async_notifier *notifier,
281
-	size_t asd_struct_size,
282
-	parse_endpoint_func parse_endpoint);
463
+int
464
+v4l2_async_notifier_parse_fwnode_endpoints(struct device *dev,
465
+					   struct v4l2_async_notifier *notifier,
466
+					   size_t asd_struct_size,
467
+					   parse_endpoint_func parse_endpoint);
283468 
284469 /**
285470  * v4l2_async_notifier_parse_fwnode_endpoints_by_port - Parse V4L2 fwnode
....@@ -303,7 +488,7 @@
303488  * devices). In this case the driver must know which ports to parse.
304489  *
305490  * Parse the fwnode endpoints of the @dev device on a given @port and populate
306
- * the async sub-devices array of the notifier. The @parse_endpoint callback
491
+ * the async sub-devices list of the notifier. The @parse_endpoint callback
307492  * function is called for each endpoint with the corresponding async sub-device
308493  * pointer to let the caller initialize the driver-specific part of the async
309494  * sub-device structure.
....@@ -313,11 +498,6 @@
313498  *
314499  * This function may not be called on a registered notifier and may be called on
315500  * a notifier only once per port.
316
- *
317
- * Do not change the notifier's subdevs array, take references to the subdevs
318
- * array itself or change the notifier's num_subdevs field. This is because this
319
- * function allocates and reallocates the subdevs array based on parsing
320
- * endpoints.
321501  *
322502  * The &struct v4l2_fwnode_endpoint passed to the callback function
323503  * @parse_endpoint is released once the function is finished. If there is a need
....@@ -332,10 +512,12 @@
332512  *	   %-EINVAL if graph or endpoint parsing failed
333513  *	   Other error codes as returned by @parse_endpoint
334514  */
335
-int v4l2_async_notifier_parse_fwnode_endpoints_by_port(
336
-	struct device *dev, struct v4l2_async_notifier *notifier,
337
-	size_t asd_struct_size, unsigned int port,
338
-	parse_endpoint_func parse_endpoint);
515
+int
516
+v4l2_async_notifier_parse_fwnode_endpoints_by_port(struct device *dev,
517
+						   struct v4l2_async_notifier *notifier,
518
+						   size_t asd_struct_size,
519
+						   unsigned int port,
520
+						   parse_endpoint_func parse_endpoint);
339521 
340522 /**
341523  * v4l2_fwnode_reference_parse_sensor_common - parse common references on
....@@ -355,7 +537,29 @@
355537  *	   -ENOMEM if memory allocation failed
356538  *	   -EINVAL if property parsing failed
357539  */
358
-int v4l2_async_notifier_parse_fwnode_sensor_common(
359
-	struct device *dev, struct v4l2_async_notifier *notifier);
540
+int v4l2_async_notifier_parse_fwnode_sensor_common(struct device *dev,
541
+						   struct v4l2_async_notifier *notifier);
542
+
543
+/* Helper macros to access the connector links. */
544
+
545
+/** v4l2_connector_last_link - Helper macro to get the first
546
+ *                             &struct v4l2_fwnode_connector link
547
+ * @v4l2c: &struct v4l2_fwnode_connector owning the connector links
548
+ *
549
+ * This marco returns the first added &struct v4l2_connector_link connector
550
+ * link or @NULL if the connector has no links.
551
+ */
552
+#define v4l2_connector_first_link(v4l2c)				       \
553
+	list_first_entry_or_null(&(v4l2c)->links,			       \
554
+				 struct v4l2_connector_link, head)
555
+
556
+/** v4l2_connector_last_link - Helper macro to get the last
557
+ *                             &struct v4l2_fwnode_connector link
558
+ * @v4l2c: &struct v4l2_fwnode_connector owning the connector links
559
+ *
560
+ * This marco returns the last &struct v4l2_connector_link added connector link.
561
+ */
562
+#define v4l2_connector_last_link(v4l2c)					       \
563
+	list_last_entry(&(v4l2c)->links, struct v4l2_connector_link, head)
360564 
361565 #endif /* _V4L2_FWNODE_H */