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