include/media/v4l2-fwnode.h

   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  * @V4L2_FWNODE_BUS_TYPE_DPI: Video Parallel Interface bus
 177  * @NR_OF_V4L2_FWNODE_BUS_TYPE: Number of bus-types
 178  */
 179 enum v4l2_fwnode_bus_type {
 180         V4L2_FWNODE_BUS_TYPE_GUESS = 0,
 181         V4L2_FWNODE_BUS_TYPE_CSI2_CPHY,
 182         V4L2_FWNODE_BUS_TYPE_CSI1,
 183         V4L2_FWNODE_BUS_TYPE_CCP2,
 184         V4L2_FWNODE_BUS_TYPE_CSI2_DPHY,
 185         V4L2_FWNODE_BUS_TYPE_PARALLEL,
 186         V4L2_FWNODE_BUS_TYPE_BT656,
 187         V4L2_FWNODE_BUS_TYPE_DPI,
 188         NR_OF_V4L2_FWNODE_BUS_TYPE
 189 };
 190
 191 /**
 192  * v4l2_fwnode_endpoint_parse() - parse all fwnode node properties
 193  * @fwnode: pointer to the endpoint's fwnode handle
 194  * @vep: pointer to the V4L2 fwnode data structure
 195  *
 196  * This function parses the V4L2 fwnode endpoint specific parameters from the
 197  * firmware. There are two ways to use this function, either by letting it
 198  * obtain the type of the bus (by setting the @vep.bus_type field to
 199  * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
 200  * v4l2_mbus_type types.
 201  *
 202  * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
 203  * property to determine the type when it is available. The caller is
 204  * responsible for validating the contents of @vep.bus_type field after the call
 205  * returns.
 206  *
 207  * As a deprecated functionality to support older DT bindings without "bus-type"
 208  * property for devices that support multiple types, if the "bus-type" property
 209  * does not exist, the function will attempt to guess the type based on the
 210  * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
 211  * DRIVERS OR BINDINGS.
 212  *
 213  * It is also possible to set @vep.bus_type corresponding to an actual bus. In
 214  * this case the function will only attempt to parse properties related to this
 215  * bus, and it will return an error if the value of the "bus-type" property
 216  * corresponds to a different bus.
 217  *
 218  * The caller is required to initialise all fields of @vep, either with
 219  * explicitly values, or by zeroing them.
 220  *
 221  * The function does not change the V4L2 fwnode endpoint state if it fails.
 222  *
 223  * NOTE: This function does not parse "link-frequencies" property as its size is
 224  * not known in advance. Please use v4l2_fwnode_endpoint_alloc_parse() if you
 225  * need properties of variable size.
 226  *
 227  * Return: %0 on success or a negative error code on failure:
 228  *         %-ENOMEM on memory allocation failure
 229  *         %-EINVAL on parsing failure
 230  *         %-ENXIO on mismatching bus types
 231  */
 232 int v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode,
 233                                struct v4l2_fwnode_endpoint *vep);
 234
 235 /**
 236  * v4l2_fwnode_endpoint_free() - free the V4L2 fwnode acquired by
 237  * v4l2_fwnode_endpoint_alloc_parse()
 238  * @vep: the V4L2 fwnode the resources of which are to be released
 239  *
 240  * It is safe to call this function with NULL argument or on a V4L2 fwnode the
 241  * parsing of which failed.
 242  */
 243 void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
 244
 245 /**
 246  * v4l2_fwnode_endpoint_alloc_parse() - parse all fwnode node properties
 247  * @fwnode: pointer to the endpoint's fwnode handle
 248  * @vep: pointer to the V4L2 fwnode data structure
 249  *
 250  * This function parses the V4L2 fwnode endpoint specific parameters from the
 251  * firmware. There are two ways to use this function, either by letting it
 252  * obtain the type of the bus (by setting the @vep.bus_type field to
 253  * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
 254  * v4l2_mbus_type types.
 255  *
 256  * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
 257  * property to determine the type when it is available. The caller is
 258  * responsible for validating the contents of @vep.bus_type field after the call
 259  * returns.
 260  *
 261  * As a deprecated functionality to support older DT bindings without "bus-type"
 262  * property for devices that support multiple types, if the "bus-type" property
 263  * does not exist, the function will attempt to guess the type based on the
 264  * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
 265  * DRIVERS OR BINDINGS.
 266  *
 267  * It is also possible to set @vep.bus_type corresponding to an actual bus. In
 268  * this case the function will only attempt to parse properties related to this
 269  * bus, and it will return an error if the value of the "bus-type" property
 270  * corresponds to a different bus.
 271  *
 272  * The caller is required to initialise all fields of @vep, either with
 273  * explicitly values, or by zeroing them.
 274  *
 275  * The function does not change the V4L2 fwnode endpoint state if it fails.
 276  *
 277  * v4l2_fwnode_endpoint_alloc_parse() has two important differences to
 278  * v4l2_fwnode_endpoint_parse():
 279  *
 280  * 1. It also parses variable size data.
 281  *
 282  * 2. The memory it has allocated to store the variable size data must be freed
 283  *    using v4l2_fwnode_endpoint_free() when no longer needed.
 284  *
 285  * Return: %0 on success or a negative error code on failure:
 286  *         %-ENOMEM on memory allocation failure
 287  *         %-EINVAL on parsing failure
 288  *         %-ENXIO on mismatching bus types
 289  */
 290 int v4l2_fwnode_endpoint_alloc_parse(struct fwnode_handle *fwnode,
 291                                      struct v4l2_fwnode_endpoint *vep);
 292
 293 /**
 294  * v4l2_fwnode_parse_link() - parse a link between two endpoints
 295  * @fwnode: pointer to the endpoint's fwnode at the local end of the link
 296  * @link: pointer to the V4L2 fwnode link data structure
 297  *
 298  * Fill the link structure with the local and remote nodes and port numbers.
 299  * The local_node and remote_node fields are set to point to the local and
 300  * remote port's parent nodes respectively (the port parent node being the
 301  * parent node of the port node if that node isn't a 'ports' node, or the
 302  * grand-parent node of the port node otherwise).
 303  *
 304  * A reference is taken to both the local and remote nodes, the caller must use
 305  * v4l2_fwnode_put_link() to drop the references when done with the
 306  * link.
 307  *
 308  * Return: 0 on success, or -ENOLINK if the remote endpoint fwnode can't be
 309  * found.
 310  */
 311 int v4l2_fwnode_parse_link(struct fwnode_handle *fwnode,
 312                            struct v4l2_fwnode_link *link);
 313
 314 /**
 315  * v4l2_fwnode_put_link() - drop references to nodes in a link
 316  * @link: pointer to the V4L2 fwnode link data structure
 317  *
 318  * Drop references to the local and remote nodes in the link. This function
 319  * must be called on every link parsed with v4l2_fwnode_parse_link().
 320  */
 321 void v4l2_fwnode_put_link(struct v4l2_fwnode_link *link);
 322
 323 /**
 324  * v4l2_fwnode_connector_free() - free the V4L2 connector acquired memory
 325  * @connector: the V4L2 connector resources of which are to be released
 326  *
 327  * Free all allocated memory and put all links acquired by
 328  * v4l2_fwnode_connector_parse() and v4l2_fwnode_connector_add_link().
 329  *
 330  * It is safe to call this function with NULL argument or on a V4L2 connector
 331  * the parsing of which failed.
 332  */
 333 void v4l2_fwnode_connector_free(struct v4l2_fwnode_connector *connector);
 334
 335 /**
 336  * v4l2_fwnode_connector_parse() - initialize the 'struct v4l2_fwnode_connector'
 337  * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector
 338  *          is connected to or to the connector endpoint fwnode handle.
 339  * @connector: pointer to the V4L2 fwnode connector data structure
 340  *
 341  * Fill the &struct v4l2_fwnode_connector with the connector type, label and
 342  * all &enum v4l2_connector_type specific connector data. The label is optional
 343  * so it is set to %NULL if no one was found. The function initialize the links
 344  * to zero. Adding links to the connector is done by calling
 345  * v4l2_fwnode_connector_add_link().
 346  *
 347  * The memory allocated for the label must be freed when no longer needed.
 348  * Freeing the memory is done by v4l2_fwnode_connector_free().
 349  *
 350  * Return:
 351  * * %0 on success or a negative error code on failure:
 352  * * %-EINVAL if @fwnode is invalid
 353  * * %-ENOTCONN if connector type is unknown or connector device can't be found
 354  */
 355 int v4l2_fwnode_connector_parse(struct fwnode_handle *fwnode,
 356                                 struct v4l2_fwnode_connector *connector);
 357
 358 /**
 359  * v4l2_fwnode_connector_add_link - add a link between a connector node and
 360  *                                  a v4l2-subdev node.
 361  * @fwnode: pointer to the subdev endpoint's fwnode handle where the connector
 362  *          is connected to
 363  * @connector: pointer to the V4L2 fwnode connector data structure
 364  *
 365  * Add a new &struct v4l2_connector_link link to the
 366  * &struct v4l2_fwnode_connector connector links list. The link local_node
 367  * points to the connector node, the remote_node to the host v4l2 (sub)dev.
 368  *
 369  * The taken references to remote_node and local_node must be dropped and the
 370  * allocated memory must be freed when no longer needed. Both is done by calling
 371  * v4l2_fwnode_connector_free().
 372  *
 373  * Return:
 374  * * %0 on success or a negative error code on failure:
 375  * * %-EINVAL if @fwnode or @connector is invalid or @connector type is unknown
 376  * * %-ENOMEM on link memory allocation failure
 377  * * %-ENOTCONN if remote connector device can't be found
 378  * * %-ENOLINK if link parsing between v4l2 (sub)dev and connector fails
 379  */
 380 int v4l2_fwnode_connector_add_link(struct fwnode_handle *fwnode,
 381                                    struct v4l2_fwnode_connector *connector);
 382
 383 /**
 384  * v4l2_fwnode_device_parse() - parse fwnode device properties
 385  * @dev: pointer to &struct device
 386  * @props: pointer to &struct v4l2_fwnode_device_properties where to store the
 387  *         parsed properties values
 388  *
 389  * This function parses and validates the V4L2 fwnode device properties from the
 390  * firmware interface, and fills the @struct v4l2_fwnode_device_properties
 391  * provided by the caller.
 392  *
 393  * Return:
 394  *      % 0 on success
 395  *      %-EINVAL if a parsed property value is not valid
 396  */
 397 int v4l2_fwnode_device_parse(struct device *dev,
 398                              struct v4l2_fwnode_device_properties *props);
 399
 400 /**
 401  * typedef parse_endpoint_func - Driver's callback function to be called on
 402  *      each V4L2 fwnode endpoint.
 403  *
 404  * @dev: pointer to &struct device
 405  * @vep: pointer to &struct v4l2_fwnode_endpoint
 406  * @asd: pointer to &struct v4l2_async_subdev
 407  *
 408  * Return:
 409  * * %0 on success
 410  * * %-ENOTCONN if the endpoint is to be skipped but this
 411  *   should not be considered as an error
 412  * * %-EINVAL if the endpoint configuration is invalid
 413  */
 414 typedef int (*parse_endpoint_func)(struct device *dev,
 415                                   struct v4l2_fwnode_endpoint *vep,
 416                                   struct v4l2_async_subdev *asd);
 417
 418 /**
 419  * v4l2_async_nf_parse_fwnode_endpoints - Parse V4L2 fwnode endpoints in a
 420  *                                              device node
 421  * @dev: the device the endpoints of which are to be parsed
 422  * @notifier: notifier for @dev
 423  * @asd_struct_size: size of the driver's async sub-device struct, including
 424  *                   sizeof(struct v4l2_async_subdev). The &struct
 425  *                   v4l2_async_subdev shall be the first member of
 426  *                   the driver's async sub-device struct, i.e. both
 427  *                   begin at the same memory address.
 428  * @parse_endpoint: Driver's callback function called on each V4L2 fwnode
 429  *                  endpoint. Optional.
 430  *
 431  * DEPRECATED! This function is deprecated. Don't use it in new drivers.
 432  * Instead see an example in cio2_parse_firmware() function in
 433  * drivers/media/pci/intel/ipu3/ipu3-cio2.c .
 434  *
 435  * Parse the fwnode endpoints of the @dev device and populate the async sub-
 436  * devices list in the notifier. The @parse_endpoint callback function is
 437  * called for each endpoint with the corresponding async sub-device pointer to
 438  * let the caller initialize the driver-specific part of the async sub-device
 439  * structure.
 440  *
 441  * The notifier memory shall be zeroed before this function is called on the
 442  * notifier.
 443  *
 444  * This function may not be called on a registered notifier and may be called on
 445  * a notifier only once.
 446  *
 447  * The &struct v4l2_fwnode_endpoint passed to the callback function
 448  * @parse_endpoint is released once the function is finished. If there is a need
 449  * to retain that configuration, the user needs to allocate memory for it.
 450  *
 451  * Any notifier populated using this function must be released with a call to
 452  * v4l2_async_nf_cleanup() after it has been unregistered and the async
 453  * sub-devices are no longer in use, even if the function returned an error.
 454  *
 455  * Return: %0 on success, including when no async sub-devices are found
 456  *         %-ENOMEM if memory allocation failed
 457  *         %-EINVAL if graph or endpoint parsing failed
 458  *         Other error codes as returned by @parse_endpoint
 459  */
 460 int
 461 v4l2_async_nf_parse_fwnode_endpoints(struct device *dev,
 462                                      struct v4l2_async_notifier *notifier,
 463                                      size_t asd_struct_size,
 464                                      parse_endpoint_func parse_endpoint);
 465
 466 /* Helper macros to access the connector links. */
 467
 468 /** v4l2_connector_last_link - Helper macro to get the first
 469  *                             &struct v4l2_fwnode_connector link
 470  * @v4l2c: &struct v4l2_fwnode_connector owning the connector links
 471  *
 472  * This marco returns the first added &struct v4l2_connector_link connector
 473  * link or @NULL if the connector has no links.
 474  */
 475 #define v4l2_connector_first_link(v4l2c)                                       \
 476         list_first_entry_or_null(&(v4l2c)->links,                              \
 477                                  struct v4l2_connector_link, head)
 478
 479 /** v4l2_connector_last_link - Helper macro to get the last
 480  *                             &struct v4l2_fwnode_connector link
 481  * @v4l2c: &struct v4l2_fwnode_connector owning the connector links
 482  *
 483  * This marco returns the last &struct v4l2_connector_link added connector link.
 484  */
 485 #define v4l2_connector_last_link(v4l2c)                                        \
 486         list_last_entry(&(v4l2c)->links, struct v4l2_connector_link, head)
 487
 488 #endif /* _V4L2_FWNODE_H */