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 /** 29 * struct v4l2_fwnode_endpoint - the endpoint data structure 30 * @base: fwnode endpoint of the v4l2_fwnode 31 * @bus_type: bus type 32 * @bus: bus configuration data structure 33 * @bus.parallel: embedded &struct v4l2_mbus_config_parallel. 34 * Used if the bus is parallel. 35 * @bus.mipi_csi1: embedded &struct v4l2_mbus_config_mipi_csi1. 36 * Used if the bus is MIPI Alliance's Camera Serial 37 * Interface version 1 (MIPI CSI1) or Standard 38 * Mobile Imaging Architecture's Compact Camera Port 2 39 * (SMIA CCP2). 40 * @bus.mipi_csi2: embedded &struct v4l2_mbus_config_mipi_csi2. 41 * Used if the bus is MIPI Alliance's Camera Serial 42 * Interface version 2 (MIPI CSI2). 43 * @link_frequencies: array of supported link frequencies 44 * @nr_of_link_frequencies: number of elements in link_frequenccies array 45 */ 46 struct v4l2_fwnode_endpoint { 47 struct fwnode_endpoint base; 48 /* 49 * Fields below this line will be zeroed by 50 * v4l2_fwnode_endpoint_parse() 51 */ 52 enum v4l2_mbus_type bus_type; 53 struct { 54 struct v4l2_mbus_config_parallel parallel; 55 struct v4l2_mbus_config_mipi_csi1 mipi_csi1; 56 struct v4l2_mbus_config_mipi_csi2 mipi_csi2; 57 } bus; 58 u64 *link_frequencies; 59 unsigned int nr_of_link_frequencies; 60 }; 61 62 /** 63 * V4L2_FWNODE_PROPERTY_UNSET - identify a non initialized property 64 * 65 * All properties in &struct v4l2_fwnode_device_properties are initialized 66 * to this value. 67 */ 68 #define V4L2_FWNODE_PROPERTY_UNSET (-1U) 69 70 /** 71 * enum v4l2_fwnode_orientation - possible device orientation 72 * @V4L2_FWNODE_ORIENTATION_FRONT: device installed on the front side 73 * @V4L2_FWNODE_ORIENTATION_BACK: device installed on the back side 74 * @V4L2_FWNODE_ORIENTATION_EXTERNAL: device externally located 75 */ 76 enum v4l2_fwnode_orientation { 77 V4L2_FWNODE_ORIENTATION_FRONT, 78 V4L2_FWNODE_ORIENTATION_BACK, 79 V4L2_FWNODE_ORIENTATION_EXTERNAL 80 }; 81 82 /** 83 * struct v4l2_fwnode_device_properties - fwnode device properties 84 * @orientation: device orientation. See &enum v4l2_fwnode_orientation 85 * @rotation: device rotation 86 */ 87 struct v4l2_fwnode_device_properties { 88 enum v4l2_fwnode_orientation orientation; 89 unsigned int rotation; 90 }; 91 92 /** 93 * struct v4l2_fwnode_link - a link between two endpoints 94 * @local_node: pointer to device_node of this endpoint 95 * @local_port: identifier of the port this endpoint belongs to 96 * @local_id: identifier of the id this endpoint belongs to 97 * @remote_node: pointer to device_node of the remote endpoint 98 * @remote_port: identifier of the port the remote endpoint belongs to 99 * @remote_id: identifier of the id the remote endpoint belongs to 100 */ 101 struct v4l2_fwnode_link { 102 struct fwnode_handle *local_node; 103 unsigned int local_port; 104 unsigned int local_id; 105 struct fwnode_handle *remote_node; 106 unsigned int remote_port; 107 unsigned int remote_id; 108 }; 109 110 /** 111 * enum v4l2_connector_type - connector type 112 * @V4L2_CONN_UNKNOWN: unknown connector type, no V4L2 connector configuration 113 * @V4L2_CONN_COMPOSITE: analog composite connector 114 * @V4L2_CONN_SVIDEO: analog svideo connector 115 */ 116 enum v4l2_connector_type { 117 V4L2_CONN_UNKNOWN, 118 V4L2_CONN_COMPOSITE, 119 V4L2_CONN_SVIDEO, 120 }; 121 122 /** 123 * struct v4l2_connector_link - connector link data structure 124 * @head: structure to be used to add the link to the 125 * &struct v4l2_fwnode_connector 126 * @fwnode_link: &struct v4l2_fwnode_link link between the connector and the 127 * device the connector belongs to. 128 */ 129 struct v4l2_connector_link { 130 struct list_head head; 131 struct v4l2_fwnode_link fwnode_link; 132 }; 133 134 /** 135 * struct v4l2_fwnode_connector_analog - analog connector data structure 136 * @sdtv_stds: sdtv standards this connector supports, set to V4L2_STD_ALL 137 * if no restrictions are specified. 138 */ 139 struct v4l2_fwnode_connector_analog { 140 v4l2_std_id sdtv_stds; 141 }; 142 143 /** 144 * struct v4l2_fwnode_connector - the connector data structure 145 * @name: the connector device name 146 * @label: optional connector label 147 * @type: connector type 148 * @links: list of all connector &struct v4l2_connector_link links 149 * @nr_of_links: total number of links 150 * @connector: connector configuration 151 * @connector.analog: analog connector configuration 152 * &struct v4l2_fwnode_connector_analog 153 */ 154 struct v4l2_fwnode_connector { 155 const char *name; 156 const char *label; 157 enum v4l2_connector_type type; 158 struct list_head links; 159 unsigned int nr_of_links; 160 161 union { 162 struct v4l2_fwnode_connector_analog analog; 163 /* future connectors */ 164 } connector; 165 }; 166 167 /** 168 * enum v4l2_fwnode_bus_type - Video bus types defined by firmware properties 169 * @V4L2_FWNODE_BUS_TYPE_GUESS: Default value if no bus-type fwnode property 170 * @V4L2_FWNODE_BUS_TYPE_CSI2_CPHY: MIPI CSI-2 bus, C-PHY physical layer 171 * @V4L2_FWNODE_BUS_TYPE_CSI1: MIPI CSI-1 bus 172 * @V4L2_FWNODE_BUS_TYPE_CCP2: SMIA Compact Camera Port 2 bus 173 * @V4L2_FWNODE_BUS_TYPE_CSI2_DPHY: MIPI CSI-2 bus, D-PHY physical layer 174 * @V4L2_FWNODE_BUS_TYPE_PARALLEL: Camera Parallel Interface bus 175 * @V4L2_FWNODE_BUS_TYPE_BT656: BT.656 video format bus-type 176 * @NR_OF_V4L2_FWNODE_BUS_TYPE: Number of bus-types 177 */ 178 enum v4l2_fwnode_bus_type { 179 V4L2_FWNODE_BUS_TYPE_GUESS = 0, 180 V4L2_FWNODE_BUS_TYPE_CSI2_CPHY, 181 V4L2_FWNODE_BUS_TYPE_CSI1, 182 V4L2_FWNODE_BUS_TYPE_CCP2, 183 V4L2_FWNODE_BUS_TYPE_CSI2_DPHY, 184 V4L2_FWNODE_BUS_TYPE_PARALLEL, 185 V4L2_FWNODE_BUS_TYPE_BT656, 186 NR_OF_V4L2_FWNODE_BUS_TYPE 187 }; 188 189 /** 190 * v4l2_fwnode_endpoint_parse() - parse all fwnode node properties 191 * @fwnode: pointer to the endpoint's fwnode handle 192 * @vep: pointer to the V4L2 fwnode data structure 193 * 194 * This function parses the V4L2 fwnode endpoint specific parameters from the 195 * firmware. There are two ways to use this function, either by letting it 196 * obtain the type of the bus (by setting the @vep.bus_type field to 197 * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum 198 * v4l2_mbus_type types. 199 * 200 * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type" 201 * property to determine the type when it is available. The caller is 202 * responsible for validating the contents of @vep.bus_type field after the call 203 * returns. 204 * 205 * As a deprecated functionality to support older DT bindings without "bus-type" 206 * property for devices that support multiple types, if the "bus-type" property 207 * does not exist, the function will attempt to guess the type based on the 208 * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW 209 * DRIVERS OR BINDINGS. 210 * 211 * It is also possible to set @vep.bus_type corresponding to an actual bus. In 212 * this case the function will only attempt to parse properties related to this 213 * bus, and it will return an error if the value of the "bus-type" property 214 * corresponds to a different bus. 215 * 216 * The caller is required to initialise all fields of @vep, either with 217 * explicitly values, or by zeroing them. 218 * 219 * The function does not change the V4L2 fwnode endpoint state if it fails. 220 * 221 * NOTE: This function does not parse "link-frequencies" property as its size is 222 * not known in advance. Please use v4l2_fwnode_endpoint_alloc_parse() if you 223 * need properties of variable size. 224 * 225 * Return: %0 on success or a negative error code on failure: 226 * %-ENOMEM on memory allocation failure 227 * %-EINVAL on parsing failure 228 * %-ENXIO on mismatching bus types 229 */ 230 int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode, 231 struct v4l2_fwnode_endpoint *vep); 232 233 /** 234 * v4l2_fwnode_endpoint_free() - free the V4L2 fwnode acquired by 235 * v4l2_fwnode_endpoint_alloc_parse() 236 * @vep: the V4L2 fwnode the resources of which are to be released 237 * 238 * It is safe to call this function with NULL argument or on a V4L2 fwnode the 239 * parsing of which failed. 240 */ 241 void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep); 242 243 /** 244 * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties 245 * @fwnode: pointer to the endpoint's fwnode handle 246 * @vep: pointer to the V4L2 fwnode data structure 247 * 248 * This function parses the V4L2 fwnode endpoint specific parameters from the 249 * firmware. There are two ways to use this function, either by letting it 250 * obtain the type of the bus (by setting the @vep.bus_type field to 251 * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum 252 * v4l2_mbus_type types. 253 * 254 * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type" 255 * property to determine the type when it is available. The caller is 256 * responsible for validating the contents of @vep.bus_type field after the call 257 * returns. 258 * 259 * As a deprecated functionality to support older DT bindings without "bus-type" 260 * property for devices that support multiple types, if the "bus-type" property 261 * does not exist, the function will attempt to guess the type based on the 262 * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW 263 * DRIVERS OR BINDINGS. 264 * 265 * It is also possible to set @vep.bus_type corresponding to an actual bus. In 266 * this case the function will only attempt to parse properties related to this 267 * bus, and it will return an error if the value of the "bus-type" property 268 * corresponds to a different bus. 269 * 270 * The caller is required to initialise all fields of @vep, either with 271 * explicitly values, or by zeroing them. 272 * 273 * The function does not change the V4L2 fwnode endpoint state if it fails. 274 * 275 * v4l2_fwnode_endpoint_alloc_parse() has two important differences to 276 * v4l2_fwnode_endpoint_parse(): 277 * 278 * 1. It also parses variable size data. 279 * 280 * 2. The memory it has allocated to store the variable size data must be freed 281 * using v4l2_fwnode_endpoint_free() when no longer needed. 282 * 283 * Return: %0 on success or a negative error code on failure: 284 * %-ENOMEM on memory allocation failure 285 * %-EINVAL on parsing failure 286 * %-ENXIO on mismatching bus types 287 */ 288 int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode, 289 struct v4l2_fwnode_endpoint *vep); 290 291 /** 292 * v4l2_fwnode_parse_link() - parse a link between two endpoints 293 * @fwnode: pointer to the endpoint's fwnode at the local end of the link 294 * @link: pointer to the V4L2 fwnode link data structure 295 * 296 * Fill the link structure with the local and remote nodes and port numbers. 297 * The local_node and remote_node fields are set to point to the local and 298 * remote port's parent nodes respectively (the port parent node being the 299 * parent node of the port node if that node isn't a 'ports' node, or the 300 * grand-parent node of the port node otherwise). 301 * 302 * A reference is taken to both the local and remote nodes, the caller must use 303 * v4l2_fwnode_put_link() to drop the references when done with the 304 * link. 305 * 306 * Return: 0 on success, or -ENOLINK if the remote endpoint fwnode can't be 307 * found. 308 */ 309 int v4l2_fwnode_parse_link(struct fwnode_handle *fwnode, 310 struct v4l2_fwnode_link *link); 311 312 /** 313 * v4l2_fwnode_put_link() - drop references to nodes in a link 314 * @link: pointer to the V4L2 fwnode link data structure 315 * 316 * Drop references to the local and remote nodes in the link. This function 317 * must be called on every link parsed with v4l2_fwnode_parse_link(). 318 */ 319 void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link); 320 321 /** 322 * v4l2_fwnode_connector_free() - free the V4L2 connector acquired memory 323 * @connector: the V4L2 connector resources of which are to be released 324 * 325 * Free all allocated memory and put all links acquired by 326 * v4l2_fwnode_connector_parse() and v4l2_fwnode_connector_add_link(). 327 * 328 * It is safe to call this function with NULL argument or on a V4L2 connector 329 * the parsing of which failed. 330 */ 331 void v4l2_fwnode_connector_free(struct v4l2_fwnode_connector *connector); 332 333 /** 334 * v4l2_fwnode_connector_parse() - initialize the 'struct v4l2_fwnode_connector' 335 * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector 336 * is connected to or to the connector endpoint fwnode handle. 337 * @connector: pointer to the V4L2 fwnode connector data structure 338 * 339 * Fill the &struct v4l2_fwnode_connector with the connector type, label and 340 * all &enum v4l2_connector_type specific connector data. The label is optional 341 * so it is set to %NULL if no one was found. The function initialize the links 342 * to zero. Adding links to the connector is done by calling 343 * v4l2_fwnode_connector_add_link(). 344 * 345 * The memory allocated for the label must be freed when no longer needed. 346 * Freeing the memory is done by v4l2_fwnode_connector_free(). 347 * 348 * Return: 349 * * %0 on success or a negative error code on failure: 350 * * %-EINVAL if @fwnode is invalid 351 * * %-ENOTCONN if connector type is unknown or connector device can't be found 352 */ 353 int v4l2_fwnode_connector_parse(struct fwnode_handle *fwnode, 354 struct v4l2_fwnode_connector *connector); 355 356 /** 357 * v4l2_fwnode_connector_add_link - add a link between a connector node and 358 * a v4l2-subdev node. 359 * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector 360 * is connected to 361 * @connector: pointer to the V4L2 fwnode connector data structure 362 * 363 * Add a new &struct v4l2_connector_link link to the 364 * &struct v4l2_fwnode_connector connector links list. The link local_node 365 * points to the connector node, the remote_node to the host v4l2 (sub)dev. 366 * 367 * The taken references to remote_node and local_node must be dropped and the 368 * allocated memory must be freed when no longer needed. Both is done by calling 369 * v4l2_fwnode_connector_free(). 370 * 371 * Return: 372 * * %0 on success or a negative error code on failure: 373 * * %-EINVAL if @fwnode or @connector is invalid or @connector type is unknown 374 * * %-ENOMEM on link memory allocation failure 375 * * %-ENOTCONN if remote connector device can't be found 376 * * %-ENOLINK if link parsing between v4l2 (sub)dev and connector fails 377 */ 378 int v4l2_fwnode_connector_add_link(struct fwnode_handle *fwnode, 379 struct v4l2_fwnode_connector *connector); 380 381 /** 382 * v4l2_fwnode_device_parse() - parse fwnode device properties 383 * @dev: pointer to &struct device 384 * @props: pointer to &struct v4l2_fwnode_device_properties where to store the 385 * parsed properties values 386 * 387 * This function parses and validates the V4L2 fwnode device properties from the 388 * firmware interface, and fills the @struct v4l2_fwnode_device_properties 389 * provided by the caller. 390 * 391 * Return: 392 * % 0 on success 393 * %-EINVAL if a parsed property value is not valid 394 */ 395 int v4l2_fwnode_device_parse(struct device *dev, 396 struct v4l2_fwnode_device_properties *props); 397 398 /** 399 * typedef parse_endpoint_func - Driver's callback function to be called on 400 * each V4L2 fwnode endpoint. 401 * 402 * @dev: pointer to &struct device 403 * @vep: pointer to &struct v4l2_fwnode_endpoint 404 * @asd: pointer to &struct v4l2_async_subdev 405 * 406 * Return: 407 * * %0 on success 408 * * %-ENOTCONN if the endpoint is to be skipped but this 409 * should not be considered as an error 410 * * %-EINVAL if the endpoint configuration is invalid 411 */ 412 typedef int (*parse_endpoint_func)(struct device *dev, 413 struct v4l2_fwnode_endpoint *vep, 414 struct v4l2_async_subdev *asd); 415 416 /** 417 * v4l2_async_nf_parse_fwnode_endpoints - Parse V4L2 fwnode endpoints in a 418 * device node 419 * @dev: the device the endpoints of which are to be parsed 420 * @notifier: notifier for @dev 421 * @asd_struct_size: size of the driver's async sub-device struct, including 422 * sizeof(struct v4l2_async_subdev). The &struct 423 * v4l2_async_subdev shall be the first member of 424 * the driver's async sub-device struct, i.e. both 425 * begin at the same memory address. 426 * @parse_endpoint: Driver's callback function called on each V4L2 fwnode 427 * endpoint. Optional. 428 * 429 * DEPRECATED! This function is deprecated. Don't use it in new drivers. 430 * Instead see an example in cio2_parse_firmware() function in 431 * drivers/media/pci/intel/ipu3/ipu3-cio2.c . 432 * 433 * Parse the fwnode endpoints of the @dev device and populate the async sub- 434 * devices list in the notifier. The @parse_endpoint callback function is 435 * called for each endpoint with the corresponding async sub-device pointer to 436 * let the caller initialize the driver-specific part of the async sub-device 437 * structure. 438 * 439 * The notifier memory shall be zeroed before this function is called on the 440 * notifier. 441 * 442 * This function may not be called on a registered notifier and may be called on 443 * a notifier only once. 444 * 445 * The &struct v4l2_fwnode_endpoint passed to the callback function 446 * @parse_endpoint is released once the function is finished. If there is a need 447 * to retain that configuration, the user needs to allocate memory for it. 448 * 449 * Any notifier populated using this function must be released with a call to 450 * v4l2_async_nf_cleanup() after it has been unregistered and the async 451 * sub-devices are no longer in use, even if the function returned an error. 452 * 453 * Return: %0 on success, including when no async sub-devices are found 454 * %-ENOMEM if memory allocation failed 455 * %-EINVAL if graph or endpoint parsing failed 456 * Other error codes as returned by @parse_endpoint 457 */ 458 int 459 v4l2_async_nf_parse_fwnode_endpoints(struct device *dev, 460 struct v4l2_async_notifier *notifier, 461 size_t asd_struct_size, 462 parse_endpoint_func parse_endpoint); 463 464 /* Helper macros to access the connector links. */ 465 466 /** v4l2_connector_last_link - Helper macro to get the first 467 * &struct v4l2_fwnode_connector link 468 * @v4l2c: &struct v4l2_fwnode_connector owning the connector links 469 * 470 * This marco returns the first added &struct v4l2_connector_link connector 471 * link or @NULL if the connector has no links. 472 */ 473 #define v4l2_connector_first_link(v4l2c) \ 474 list_first_entry_or_null(&(v4l2c)->links, \ 475 struct v4l2_connector_link, head) 476 477 /** v4l2_connector_last_link - Helper macro to get the last 478 * &struct v4l2_fwnode_connector link 479 * @v4l2c: &struct v4l2_fwnode_connector owning the connector links 480 * 481 * This marco returns the last &struct v4l2_connector_link added connector link. 482 */ 483 #define v4l2_connector_last_link(v4l2c) \ 484 list_last_entry(&(v4l2c)->links, struct v4l2_connector_link, head) 485 486 #endif /* _V4L2_FWNODE_H */ 487