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 struct fwnode_handle; 25 struct v4l2_async_notifier; 26 struct v4l2_async_subdev; 27 28 #define V4L2_FWNODE_CSI2_MAX_DATA_LANES 4 29 30 /** 31 * struct v4l2_fwnode_bus_mipi_csi2 - MIPI CSI-2 bus data structure 32 * @flags: media bus (V4L2_MBUS_*) flags 33 * @data_lanes: an array of physical data lane indexes 34 * @clock_lane: physical lane index of the clock lane 35 * @num_data_lanes: number of data lanes 36 * @lane_polarities: polarity of the lanes. The order is the same of 37 * the physical lanes. 38 */ 39 struct v4l2_fwnode_bus_mipi_csi2 { 40 unsigned int flags; 41 unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES]; 42 unsigned char clock_lane; 43 unsigned short num_data_lanes; 44 bool lane_polarities[1 + V4L2_FWNODE_CSI2_MAX_DATA_LANES]; 45 }; 46 47 /** 48 * struct v4l2_fwnode_bus_parallel - parallel data bus data structure 49 * @flags: media bus (V4L2_MBUS_*) flags 50 * @bus_width: bus width in bits 51 * @data_shift: data shift in bits 52 */ 53 struct v4l2_fwnode_bus_parallel { 54 unsigned int flags; 55 unsigned char bus_width; 56 unsigned char data_shift; 57 }; 58 59 /** 60 * struct v4l2_fwnode_bus_mipi_csi1 - CSI-1/CCP2 data bus structure 61 * @clock_inv: polarity of clock/strobe signal 62 * false - not inverted, true - inverted 63 * @strobe: false - data/clock, true - data/strobe 64 * @lane_polarity: the polarities of the clock (index 0) and data lanes 65 * index (1) 66 * @data_lane: the number of the data lane 67 * @clock_lane: the number of the clock lane 68 */ 69 struct v4l2_fwnode_bus_mipi_csi1 { 70 unsigned char clock_inv:1; 71 unsigned char strobe:1; 72 bool lane_polarity[2]; 73 unsigned char data_lane; 74 unsigned char clock_lane; 75 }; 76 77 /** 78 * struct v4l2_fwnode_endpoint - the endpoint data structure 79 * @base: fwnode endpoint of the v4l2_fwnode 80 * @bus_type: bus type 81 * @bus: union with bus configuration data structure 82 * @bus.parallel: embedded &struct v4l2_fwnode_bus_parallel. 83 * Used if the bus is parallel. 84 * @bus.mipi_csi1: embedded &struct v4l2_fwnode_bus_mipi_csi1. 85 * Used if the bus is MIPI Alliance's Camera Serial 86 * Interface version 1 (MIPI CSI1) or Standard 87 * Mobile Imaging Architecture's Compact Camera Port 2 88 * (SMIA CCP2). 89 * @bus.mipi_csi2: embedded &struct v4l2_fwnode_bus_mipi_csi2. 90 * Used if the bus is MIPI Alliance's Camera Serial 91 * Interface version 2 (MIPI CSI2). 92 * @link_frequencies: array of supported link frequencies 93 * @nr_of_link_frequencies: number of elements in link_frequenccies array 94 */ 95 struct v4l2_fwnode_endpoint { 96 struct fwnode_endpoint base; 97 /* 98 * Fields below this line will be zeroed by 99 * v4l2_fwnode_endpoint_parse() 100 */ 101 enum v4l2_mbus_type bus_type; 102 union { 103 struct v4l2_fwnode_bus_parallel parallel; 104 struct v4l2_fwnode_bus_mipi_csi1 mipi_csi1; 105 struct v4l2_fwnode_bus_mipi_csi2 mipi_csi2; 106 } bus; 107 u64 *link_frequencies; 108 unsigned int nr_of_link_frequencies; 109 }; 110 111 /** 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 /** 142 * struct v4l2_fwnode_link - a link between two endpoints 143 * @local_node: pointer to device_node of this endpoint 144 * @local_port: identifier of the port this endpoint belongs to 145 * @local_id: identifier of the id this endpoint belongs to 146 * @remote_node: pointer to device_node of the remote endpoint 147 * @remote_port: identifier of the port the remote endpoint belongs to 148 * @remote_id: identifier of the id the remote endpoint belongs to 149 */ 150 struct v4l2_fwnode_link { 151 struct fwnode_handle *local_node; 152 unsigned int local_port; 153 unsigned int local_id; 154 struct fwnode_handle *remote_node; 155 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; 214 }; 215 216 /** 217 * v4l2_fwnode_endpoint_parse() - parse all fwnode node properties 218 * @fwnode: pointer to the endpoint's fwnode handle 219 * @vep: pointer to the V4L2 fwnode data structure 220 * 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 * As a compatibility means guessing the bus type is also supported by setting 230 * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default 231 * configuration in this case as the defaults are specific to a given bus type. 232 * This functionality is deprecated and should not be used in new drivers and it 233 * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses. 234 * 235 * The function does not change the V4L2 fwnode endpoint state if it fails. 236 * 237 * NOTE: This function does not parse properties the size of which is variable 238 * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in 239 * new drivers instead. 240 * 241 * Return: %0 on success or a negative error code on failure: 242 * %-ENOMEM on memory allocation failure 243 * %-EINVAL on parsing failure 244 * %-ENXIO on mismatching bus types 245 */ 246 int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode, 247 struct v4l2_fwnode_endpoint *vep); 248 249 /** 250 * v4l2_fwnode_endpoint_free() - free the V4L2 fwnode acquired by 251 * v4l2_fwnode_endpoint_alloc_parse() 252 * @vep: the V4L2 fwnode the resources of which are to be released 253 * 254 * It is safe to call this function with NULL argument or on a V4L2 fwnode the 255 * parsing of which failed. 256 */ 257 void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); 258 259 /** 260 * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties 261 * @fwnode: pointer to the endpoint's fwnode handle 262 * @vep: pointer to the V4L2 fwnode data structure 263 * 264 * This function parses the V4L2 fwnode endpoint specific parameters from the 265 * firmware. The caller is responsible for assigning @vep.bus_type to a valid 266 * media bus type. The caller may also set the default configuration for the 267 * endpoint --- a configuration that shall be in line with the DT binding 268 * documentation. Should a device support multiple bus types, the caller may 269 * call this function once the correct type is found --- with a default 270 * configuration valid for that type. 271 * 272 * As a compatibility means guessing the bus type is also supported by setting 273 * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default 274 * configuration in this case as the defaults are specific to a given bus type. 275 * This functionality is deprecated and should not be used in new drivers and it 276 * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses. 277 * 278 * The function does not change the V4L2 fwnode endpoint state if it fails. 279 * 280 * v4l2_fwnode_endpoint_alloc_parse() has two important differences to 281 * v4l2_fwnode_endpoint_parse(): 282 * 283 * 1. It also parses variable size data. 284 * 285 * 2. The memory it has allocated to store the variable size data must be freed 286 * using v4l2_fwnode_endpoint_free() when no longer needed. 287 * 288 * Return: %0 on success or a negative error code on failure: 289 * %-ENOMEM on memory allocation failure 290 * %-EINVAL on parsing failure 291 * %-ENXIO on mismatching bus types 292 */ 293 int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode, 294 struct v4l2_fwnode_endpoint *vep); 295 296 /** 297 * v4l2_fwnode_parse_link() - parse a link between two endpoints 298 * @fwnode: pointer to the endpoint's fwnode at the local end of the link 299 * @link: pointer to the V4L2 fwnode link data structure 300 * 301 * Fill the link structure with the local and remote nodes and port numbers. 302 * The local_node and remote_node fields are set to point to the local and 303 * remote port's parent nodes respectively (the port parent node being the 304 * parent node of the port node if that node isn't a 'ports' node, or the 305 * grand-parent node of the port node otherwise). 306 * 307 * A reference is taken to both the local and remote nodes, the caller must use 308 * v4l2_fwnode_put_link() to drop the references when done with the 309 * link. 310 * 311 * Return: 0 on success, or -ENOLINK if the remote endpoint fwnode can't be 312 * found. 313 */ 314 int v4l2_fwnode_parse_link(struct fwnode_handle *fwnode, 315 struct v4l2_fwnode_link *link); 316 317 /** 318 * v4l2_fwnode_put_link() - drop references to nodes in a link 319 * @link: pointer to the V4L2 fwnode link data structure 320 * 321 * Drop references to the local and remote nodes in the link. This function 322 * must be called on every link parsed with v4l2_fwnode_parse_link(). 323 */ 324 void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link); 325 326 /** 327 * v4l2_fwnode_connector_free() - free the V4L2 connector acquired memory 328 * @connector: the V4L2 connector resources of which are to be released 329 * 330 * Free all allocated memory and put all links acquired by 331 * v4l2_fwnode_connector_parse() and v4l2_fwnode_connector_add_link(). 332 * 333 * It is safe to call this function with NULL argument or on a V4L2 connector 334 * the parsing of which failed. 335 */ 336 void v4l2_fwnode_connector_free(struct v4l2_fwnode_connector *connector); 337 338 /** 339 * v4l2_fwnode_connector_parse() - initialize the 'struct v4l2_fwnode_connector' 340 * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector 341 * is connected to or to the connector endpoint fwnode handle. 342 * @connector: pointer to the V4L2 fwnode connector data structure 343 * 344 * Fill the &struct v4l2_fwnode_connector with the connector type, label and 345 * all &enum v4l2_connector_type specific connector data. The label is optional 346 * so it is set to %NULL if no one was found. The function initialize the links 347 * to zero. Adding links to the connector is done by calling 348 * v4l2_fwnode_connector_add_link(). 349 * 350 * The memory allocated for the label must be freed when no longer needed. 351 * Freeing the memory is done by v4l2_fwnode_connector_free(). 352 * 353 * Return: 354 * * %0 on success or a negative error code on failure: 355 * * %-EINVAL if @fwnode is invalid 356 * * %-ENOTCONN if connector type is unknown or connector device can't be found 357 */ 358 int v4l2_fwnode_connector_parse(struct fwnode_handle *fwnode, 359 struct v4l2_fwnode_connector *connector); 360 361 /** 362 * v4l2_fwnode_connector_add_link - add a link between a connector node and 363 * a v4l2-subdev node. 364 * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector 365 * is connected to 366 * @connector: pointer to the V4L2 fwnode connector data structure 367 * 368 * Add a new &struct v4l2_connector_link link to the 369 * &struct v4l2_fwnode_connector connector links list. The link local_node 370 * points to the connector node, the remote_node to the host v4l2 (sub)dev. 371 * 372 * The taken references to remote_node and local_node must be dropped and the 373 * allocated memory must be freed when no longer needed. Both is done by calling 374 * v4l2_fwnode_connector_free(). 375 * 376 * Return: 377 * * %0 on success or a negative error code on failure: 378 * * %-EINVAL if @fwnode or @connector is invalid or @connector type is unknown 379 * * %-ENOMEM on link memory allocation failure 380 * * %-ENOTCONN if remote connector device can't be found 381 * * %-ENOLINK if link parsing between v4l2 (sub)dev and connector fails 382 */ 383 int v4l2_fwnode_connector_add_link(struct fwnode_handle *fwnode, 384 struct v4l2_fwnode_connector *connector); 385 386 /** 387 * v4l2_fwnode_device_parse() - parse fwnode device properties 388 * @dev: pointer to &struct device 389 * @props: pointer to &struct v4l2_fwnode_device_properties where to store the 390 * parsed properties values 391 * 392 * This function parses and validates the V4L2 fwnode device properties from the 393 * firmware interface, and fills the @struct v4l2_fwnode_device_properties 394 * provided by the caller. 395 * 396 * Return: 397 * % 0 on success 398 * %-EINVAL if a parsed property value is not valid 399 */ 400 int v4l2_fwnode_device_parse(struct device *dev, 401 struct v4l2_fwnode_device_properties *props); 402 403 /** 404 * typedef parse_endpoint_func - Driver's callback function to be called on 405 * each V4L2 fwnode endpoint. 406 * 407 * @dev: pointer to &struct device 408 * @vep: pointer to &struct v4l2_fwnode_endpoint 409 * @asd: pointer to &struct v4l2_async_subdev 410 * 411 * Return: 412 * * %0 on success 413 * * %-ENOTCONN if the endpoint is to be skipped but this 414 * should not be considered as an error 415 * * %-EINVAL if the endpoint configuration is invalid 416 */ 417 typedef int (*parse_endpoint_func)(struct device *dev, 418 struct v4l2_fwnode_endpoint *vep, 419 struct v4l2_async_subdev *asd); 420 421 /** 422 * v4l2_async_notifier_parse_fwnode_endpoints - Parse V4L2 fwnode endpoints in a 423 * device node 424 * @dev: the device the endpoints of which are to be parsed 425 * @notifier: notifier for @dev 426 * @asd_struct_size: size of the driver's async sub-device struct, including 427 * sizeof(struct v4l2_async_subdev). The &struct 428 * v4l2_async_subdev shall be the first member of 429 * the driver's async sub-device struct, i.e. both 430 * begin at the same memory address. 431 * @parse_endpoint: Driver's callback function called on each V4L2 fwnode 432 * endpoint. Optional. 433 * 434 * Parse the fwnode endpoints of the @dev device and populate the async sub- 435 * devices list in the notifier. The @parse_endpoint callback function is 436 * called for each endpoint with the corresponding async sub-device pointer to 437 * let the caller initialize the driver-specific part of the async sub-device 438 * structure. 439 * 440 * The notifier memory shall be zeroed before this function is called on the 441 * notifier. 442 * 443 * This function may not be called on a registered notifier and may be called on 444 * a notifier only once. 445 * 446 * The &struct v4l2_fwnode_endpoint passed to the callback function 447 * @parse_endpoint is released once the function is finished. If there is a need 448 * to retain that configuration, the user needs to allocate memory for it. 449 * 450 * Any notifier populated using this function must be released with a call to 451 * v4l2_async_notifier_cleanup() after it has been unregistered and the async 452 * sub-devices are no longer in use, even if the function returned an error. 453 * 454 * Return: %0 on success, including when no async sub-devices are found 455 * %-ENOMEM if memory allocation failed 456 * %-EINVAL if graph or endpoint parsing failed 457 * Other error codes as returned by @parse_endpoint 458 */ 459 int 460 v4l2_async_notifier_parse_fwnode_endpoints(struct device *dev, 461 struct v4l2_async_notifier *notifier, 462 size_t asd_struct_size, 463 parse_endpoint_func parse_endpoint); 464 465 /** 466 * v4l2_async_notifier_parse_fwnode_endpoints_by_port - Parse V4L2 fwnode 467 * endpoints of a port in a 468 * device node 469 * @dev: the device the endpoints of which are to be parsed 470 * @notifier: notifier for @dev 471 * @asd_struct_size: size of the driver's async sub-device struct, including 472 * sizeof(struct v4l2_async_subdev). The &struct 473 * v4l2_async_subdev shall be the first member of 474 * the driver's async sub-device struct, i.e. both 475 * begin at the same memory address. 476 * @port: port number where endpoints are to be parsed 477 * @parse_endpoint: Driver's callback function called on each V4L2 fwnode 478 * endpoint. Optional. 479 * 480 * This function is just like v4l2_async_notifier_parse_fwnode_endpoints() with 481 * the exception that it only parses endpoints in a given port. This is useful 482 * on devices that have both sinks and sources: the async sub-devices connected 483 * to sources have already been configured by another driver (on capture 484 * devices). In this case the driver must know which ports to parse. 485 * 486 * Parse the fwnode endpoints of the @dev device on a given @port and populate 487 * the async sub-devices list of the notifier. The @parse_endpoint callback 488 * function is called for each endpoint with the corresponding async sub-device 489 * pointer to let the caller initialize the driver-specific part of the async 490 * sub-device structure. 491 * 492 * The notifier memory shall be zeroed before this function is called on the 493 * notifier the first time. 494 * 495 * This function may not be called on a registered notifier and may be called on 496 * a notifier only once per port. 497 * 498 * The &struct v4l2_fwnode_endpoint passed to the callback function 499 * @parse_endpoint is released once the function is finished. If there is a need 500 * to retain that configuration, the user needs to allocate memory for it. 501 * 502 * Any notifier populated using this function must be released with a call to 503 * v4l2_async_notifier_cleanup() after it has been unregistered and the async 504 * sub-devices are no longer in use, even if the function returned an error. 505 * 506 * Return: %0 on success, including when no async sub-devices are found 507 * %-ENOMEM if memory allocation failed 508 * %-EINVAL if graph or endpoint parsing failed 509 * Other error codes as returned by @parse_endpoint 510 */ 511 int 512 v4l2_async_notifier_parse_fwnode_endpoints_by_port(struct device *dev, 513 struct v4l2_async_notifier *notifier, 514 size_t asd_struct_size, 515 unsigned int port, 516 parse_endpoint_func parse_endpoint); 517 518 /** 519 * v4l2_fwnode_reference_parse_sensor_common - parse common references on 520 * sensors for async sub-devices 521 * @dev: the device node the properties of which are parsed for references 522 * @notifier: the async notifier where the async subdevs will be added 523 * 524 * Parse common sensor properties for remote devices related to the 525 * sensor and set up async sub-devices for them. 526 * 527 * Any notifier populated using this function must be released with a call to 528 * v4l2_async_notifier_release() after it has been unregistered and the async 529 * sub-devices are no longer in use, even in the case the function returned an 530 * error. 531 * 532 * Return: 0 on success 533 * -ENOMEM if memory allocation failed 534 * -EINVAL if property parsing failed 535 */ 536 int v4l2_async_notifier_parse_fwnode_sensor_common(struct device *dev, 537 struct v4l2_async_notifier *notifier); 538 539 /* Helper macros to access the connector links. */ 540 541 /** v4l2_connector_last_link - Helper macro to get the first 542 * &struct v4l2_fwnode_connector link 543 * @v4l2c: &struct v4l2_fwnode_connector owning the connector links 544 * 545 * This marco returns the first added &struct v4l2_connector_link connector 546 * link or @NULL if the connector has no links. 547 */ 548 #define v4l2_connector_first_link(v4l2c) \ 549 list_first_entry_or_null(&(v4l2c)->links, \ 550 struct v4l2_connector_link, head) 551 552 /** v4l2_connector_last_link - Helper macro to get the last 553 * &struct v4l2_fwnode_connector link 554 * @v4l2c: &struct v4l2_fwnode_connector owning the connector links 555 * 556 * This marco returns the last &struct v4l2_connector_link added connector link. 557 */ 558 #define v4l2_connector_last_link(v4l2c) \ 559 list_last_entry(&(v4l2c)->links, struct v4l2_connector_link, head) 560 561 #endif /* _V4L2_FWNODE_H */ 562