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         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 */