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