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 24struct fwnode_handle; 25struct v4l2_async_notifier; 26struct 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 */ 39struct 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 char 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 */ 53struct 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 */ 69struct 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: 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 */ 95struct 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 struct { 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 */ 125enum 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 */ 136struct 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 */ 150struct 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 */ 165enum 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 */ 178struct 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 */ 188struct 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 */ 203struct 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 * 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. 238 * 239 * NOTE: This function does not parse properties the size of which is variable 240 * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in 241 * new drivers instead. 242 * 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 247 */ 248int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode, 249 struct v4l2_fwnode_endpoint *vep); 250 251/** 252 * v4l2_fwnode_endpoint_free() - free the V4L2 fwnode acquired by 253 * v4l2_fwnode_endpoint_alloc_parse() 254 * @vep: the V4L2 fwnode the resources of which are to be released 255 * 256 * It is safe to call this function with NULL argument or on a V4L2 fwnode the 257 * parsing of which failed. 258 */ 259void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); 260 261/** 262 * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties 263 * @fwnode: pointer to the endpoint's fwnode handle 264 * @vep: pointer to the V4L2 fwnode data structure 265 * 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. 283 * 284 * v4l2_fwnode_endpoint_alloc_parse() has two important differences to 285 * v4l2_fwnode_endpoint_parse(): 286 * 287 * 1. It also parses variable size data. 288 * 289 * 2. The memory it has allocated to store the variable size data must be freed 290 * using v4l2_fwnode_endpoint_free() when no longer needed. 291 * 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 296 */ 297int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode, 298 struct v4l2_fwnode_endpoint *vep); 299 300/** 301 * v4l2_fwnode_parse_link() - parse a link between two endpoints 302 * @fwnode: pointer to the endpoint's fwnode at the local end of the link 303 * @link: pointer to the V4L2 fwnode link data structure 304 * 305 * Fill the link structure with the local and remote nodes and port numbers. 306 * The local_node and remote_node fields are set to point to the local and 307 * remote port's parent nodes respectively (the port parent node being the 308 * parent node of the port node if that node isn't a 'ports' node, or the 309 * grand-parent node of the port node otherwise). 310 * 311 * A reference is taken to both the local and remote nodes, the caller must use 312 * v4l2_fwnode_put_link() to drop the references when done with the 313 * link. 314 * 315 * Return: 0 on success, or -ENOLINK if the remote endpoint fwnode can't be 316 * found. 317 */ 318int v4l2_fwnode_parse_link(struct fwnode_handle *fwnode, 319 struct v4l2_fwnode_link *link); 320 321/** 322 * v4l2_fwnode_put_link() - drop references to nodes in a link 323 * @link: pointer to the V4L2 fwnode link data structure 324 * 325 * Drop references to the local and remote nodes in the link. This function 326 * must be called on every link parsed with v4l2_fwnode_parse_link(). 327 */ 328void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link); 329 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 */ 340void 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 */ 362int 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 */ 387int 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 */ 404int v4l2_fwnode_device_parse(struct device *dev, 405 struct v4l2_fwnode_device_properties *props); 406 407/** 408 * typedef parse_endpoint_func - Driver's callback function to be called on 409 * each V4L2 fwnode endpoint. 410 * 411 * @dev: pointer to &struct device 412 * @vep: pointer to &struct v4l2_fwnode_endpoint 413 * @asd: pointer to &struct v4l2_async_subdev 414 * 415 * Return: 416 * * %0 on success 417 * * %-ENOTCONN if the endpoint is to be skipped but this 418 * should not be considered as an error 419 * * %-EINVAL if the endpoint configuration is invalid 420 */ 421typedef int (*parse_endpoint_func)(struct device *dev, 422 struct v4l2_fwnode_endpoint *vep, 423 struct v4l2_async_subdev *asd); 424 425/** 426 * v4l2_async_notifier_parse_fwnode_endpoints - Parse V4L2 fwnode endpoints in a 427 * device node 428 * @dev: the device the endpoints of which are to be parsed 429 * @notifier: notifier for @dev 430 * @asd_struct_size: size of the driver's async sub-device struct, including 431 * sizeof(struct v4l2_async_subdev). The &struct 432 * v4l2_async_subdev shall be the first member of 433 * the driver's async sub-device struct, i.e. both 434 * begin at the same memory address. 435 * @parse_endpoint: Driver's callback function called on each V4L2 fwnode 436 * endpoint. Optional. 437 * 438 * Parse the fwnode endpoints of the @dev device and populate the async sub- 439 * devices list in the notifier. The @parse_endpoint callback function is 440 * called for each endpoint with the corresponding async sub-device pointer to 441 * let the caller initialize the driver-specific part of the async sub-device 442 * structure. 443 * 444 * The notifier memory shall be zeroed before this function is called on the 445 * notifier. 446 * 447 * This function may not be called on a registered notifier and may be called on 448 * a notifier only once. 449 * 450 * The &struct v4l2_fwnode_endpoint passed to the callback function 451 * @parse_endpoint is released once the function is finished. If there is a need 452 * to retain that configuration, the user needs to allocate memory for it. 453 * 454 * Any notifier populated using this function must be released with a call to 455 * v4l2_async_notifier_cleanup() after it has been unregistered and the async 456 * sub-devices are no longer in use, even if the function returned an error. 457 * 458 * Return: %0 on success, including when no async sub-devices are found 459 * %-ENOMEM if memory allocation failed 460 * %-EINVAL if graph or endpoint parsing failed 461 * Other error codes as returned by @parse_endpoint 462 */ 463int 464v4l2_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); 468 469/** 470 * v4l2_async_notifier_parse_fwnode_endpoints_by_port - Parse V4L2 fwnode 471 * endpoints of a port in a 472 * device node 473 * @dev: the device the endpoints of which are to be parsed 474 * @notifier: notifier for @dev 475 * @asd_struct_size: size of the driver's async sub-device struct, including 476 * sizeof(struct v4l2_async_subdev). The &struct 477 * v4l2_async_subdev shall be the first member of 478 * the driver's async sub-device struct, i.e. both 479 * begin at the same memory address. 480 * @port: port number where endpoints are to be parsed 481 * @parse_endpoint: Driver's callback function called on each V4L2 fwnode 482 * endpoint. Optional. 483 * 484 * This function is just like v4l2_async_notifier_parse_fwnode_endpoints() with 485 * the exception that it only parses endpoints in a given port. This is useful 486 * on devices that have both sinks and sources: the async sub-devices connected 487 * to sources have already been configured by another driver (on capture 488 * devices). In this case the driver must know which ports to parse. 489 * 490 * Parse the fwnode endpoints of the @dev device on a given @port and populate 491 * the async sub-devices list of the notifier. The @parse_endpoint callback 492 * function is called for each endpoint with the corresponding async sub-device 493 * pointer to let the caller initialize the driver-specific part of the async 494 * sub-device structure. 495 * 496 * The notifier memory shall be zeroed before this function is called on the 497 * notifier the first time. 498 * 499 * This function may not be called on a registered notifier and may be called on 500 * a notifier only once per port. 501 * 502 * The &struct v4l2_fwnode_endpoint passed to the callback function 503 * @parse_endpoint is released once the function is finished. If there is a need 504 * to retain that configuration, the user needs to allocate memory for it. 505 * 506 * Any notifier populated using this function must be released with a call to 507 * v4l2_async_notifier_cleanup() after it has been unregistered and the async 508 * sub-devices are no longer in use, even if the function returned an error. 509 * 510 * Return: %0 on success, including when no async sub-devices are found 511 * %-ENOMEM if memory allocation failed 512 * %-EINVAL if graph or endpoint parsing failed 513 * Other error codes as returned by @parse_endpoint 514 */ 515int 516v4l2_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); 521 522/** 523 * v4l2_fwnode_reference_parse_sensor_common - parse common references on 524 * sensors for async sub-devices 525 * @dev: the device node the properties of which are parsed for references 526 * @notifier: the async notifier where the async subdevs will be added 527 * 528 * Parse common sensor properties for remote devices related to the 529 * sensor and set up async sub-devices for them. 530 * 531 * Any notifier populated using this function must be released with a call to 532 * v4l2_async_notifier_release() after it has been unregistered and the async 533 * sub-devices are no longer in use, even in the case the function returned an 534 * error. 535 * 536 * Return: 0 on success 537 * -ENOMEM if memory allocation failed 538 * -EINVAL if property parsing failed 539 */ 540int 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) 564 565#endif /* _V4L2_FWNODE_H */ 566