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