include/media/v4l2-async.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2 /*
   3  * V4L2 asynchronous subdevice registration API
   4  *
   5  * Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
   6  */
   7
   8 #ifndef V4L2_ASYNC_H
   9 #define V4L2_ASYNC_H
  10
  11 #include <linux/list.h>
  12 #include <linux/mutex.h>
  13
  14 struct device;
  15 struct device_node;
  16 struct v4l2_device;
  17 struct v4l2_subdev;
  18 struct v4l2_async_notifier;
  19
  20 /**
  21  * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
  22  *      in order to identify a match
  23  *
  24  * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
  25  *      v4l2_async_subdev.match ops
  26  * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
  27  * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
  28  * @V4L2_ASYNC_MATCH_FWNODE: Match will use firmware node
  29  *
  30  * This enum is used by the asyncrhronous sub-device logic to define the
  31  * algorithm that will be used to match an asynchronous device.
  32  */
  33 enum v4l2_async_match_type {
  34         V4L2_ASYNC_MATCH_CUSTOM,
  35         V4L2_ASYNC_MATCH_DEVNAME,
  36         V4L2_ASYNC_MATCH_I2C,
  37         V4L2_ASYNC_MATCH_FWNODE,
  38 };
  39
  40 /**
  41  * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
  42  *
  43  * @match_type: type of match that will be used
  44  * @match:      union of per-bus type matching data sets
  45  * @match.fwnode:
  46  *              pointer to &struct fwnode_handle to be matched.
  47  *              Used if @match_type is %V4L2_ASYNC_MATCH_FWNODE.
  48  * @match.device_name:
  49  *              string containing the device name to be matched.
  50  *              Used if @match_type is %V4L2_ASYNC_MATCH_DEVNAME.
  51  * @match.i2c:  embedded struct with I2C parameters to be matched.
  52  *              Both @match.i2c.adapter_id and @match.i2c.address
  53  *              should be matched.
  54  *              Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
  55  * @match.i2c.adapter_id:
  56  *              I2C adapter ID to be matched.
  57  *              Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
  58  * @match.i2c.address:
  59  *              I2C address to be matched.
  60  *              Used if @match_type is %V4L2_ASYNC_MATCH_I2C.
  61  * @match.custom:
  62  *              Driver-specific match criteria.
  63  *              Used if @match_type is %V4L2_ASYNC_MATCH_CUSTOM.
  64  * @match.custom.match:
  65  *              Driver-specific match function to be used if
  66  *              %V4L2_ASYNC_MATCH_CUSTOM.
  67  * @match.custom.priv:
  68  *              Driver-specific private struct with match parameters
  69  *              to be used if %V4L2_ASYNC_MATCH_CUSTOM.
  70  * @asd_list:   used to add struct v4l2_async_subdev objects to the
  71  *              master notifier @asd_list
  72  * @list:       used to link struct v4l2_async_subdev objects, waiting to be
  73  *              probed, to a notifier->waiting list
  74  *
  75  * When this struct is used as a member in a driver specific struct,
  76  * the driver specific struct shall contain the &struct
  77  * v4l2_async_subdev as its first member.
  78  */
  79 struct v4l2_async_subdev {
  80         enum v4l2_async_match_type match_type;
  81         union {
  82                 struct fwnode_handle *fwnode;
  83                 const char *device_name;
  84                 struct {
  85                         int adapter_id;
  86                         unsigned short address;
  87                 } i2c;
  88                 struct {
  89                         bool (*match)(struct device *dev,
  90                                       struct v4l2_async_subdev *sd);
  91                         void *priv;
  92                 } custom;
  93         } match;
  94
  95         /* v4l2-async core private: not to be used by drivers */
  96         struct list_head list;
  97         struct list_head asd_list;
  98 };
  99
 100 /**
 101  * struct v4l2_async_notifier_operations - Asynchronous V4L2 notifier operations
 102  * @bound:      a subdevice driver has successfully probed one of the subdevices
 103  * @complete:   All subdevices have been probed successfully. The complete
 104  *              callback is only executed for the root notifier.
 105  * @unbind:     a subdevice is leaving
 106  */
 107 struct v4l2_async_notifier_operations {
 108         int (*bound)(struct v4l2_async_notifier *notifier,
 109                      struct v4l2_subdev *subdev,
 110                      struct v4l2_async_subdev *asd);
 111         int (*complete)(struct v4l2_async_notifier *notifier);
 112         void (*unbind)(struct v4l2_async_notifier *notifier,
 113                        struct v4l2_subdev *subdev,
 114                        struct v4l2_async_subdev *asd);
 115 };
 116
 117 /**
 118  * struct v4l2_async_notifier - v4l2_device notifier data
 119  *
 120  * @ops:        notifier operations
 121  * @v4l2_dev:   v4l2_device of the root notifier, NULL otherwise
 122  * @sd:         sub-device that registered the notifier, NULL otherwise
 123  * @parent:     parent notifier
 124  * @asd_list:   master list of struct v4l2_async_subdev
 125  * @waiting:    list of struct v4l2_async_subdev, waiting for their drivers
 126  * @done:       list of struct v4l2_subdev, already probed
 127  * @list:       member in a global list of notifiers
 128  */
 129 struct v4l2_async_notifier {
 130         const struct v4l2_async_notifier_operations *ops;
 131         struct v4l2_device *v4l2_dev;
 132         struct v4l2_subdev *sd;
 133         struct v4l2_async_notifier *parent;
 134         struct list_head asd_list;
 135         struct list_head waiting;
 136         struct list_head done;
 137         struct list_head list;
 138 };
 139
 140 /**
 141  * v4l2_async_notifier_init - Initialize a notifier.
 142  *
 143  * @notifier: pointer to &struct v4l2_async_notifier
 144  *
 145  * This function initializes the notifier @asd_list. It must be called
 146  * before the first call to @v4l2_async_notifier_add_subdev.
 147  */
 148 void v4l2_async_notifier_init(struct v4l2_async_notifier *notifier);
 149
 150 /**
 151  * v4l2_async_notifier_add_subdev - Add an async subdev to the
 152  *                              notifier's master asd list.
 153  *
 154  * @notifier: pointer to &struct v4l2_async_notifier
 155  * @asd: pointer to &struct v4l2_async_subdev
 156  *
 157  * Call this function before registering a notifier to link the
 158  * provided asd to the notifiers master @asd_list.
 159  */
 160 int v4l2_async_notifier_add_subdev(struct v4l2_async_notifier *notifier,
 161                                    struct v4l2_async_subdev *asd);
 162
 163 /**
 164  * v4l2_async_notifier_add_fwnode_subdev - Allocate and add a fwnode async
 165  *                              subdev to the notifier's master asd_list.
 166  *
 167  * @notifier: pointer to &struct v4l2_async_notifier
 168  * @fwnode: fwnode handle of the sub-device to be matched
 169  * @asd_struct_size: size of the driver's async sub-device struct, including
 170  *                   sizeof(struct v4l2_async_subdev). The &struct
 171  *                   v4l2_async_subdev shall be the first member of
 172  *                   the driver's async sub-device struct, i.e. both
 173  *                   begin at the same memory address.
 174  *
 175  * Allocate a fwnode-matched asd of size asd_struct_size, and add it to the
 176  * notifiers @asd_list. The function also gets a reference of the fwnode which
 177  * is released later at notifier cleanup time.
 178  */
 179 struct v4l2_async_subdev *
 180 v4l2_async_notifier_add_fwnode_subdev(struct v4l2_async_notifier *notifier,
 181                                       struct fwnode_handle *fwnode,
 182                                       unsigned int asd_struct_size);
 183
 184 /**
 185  * v4l2_async_notifier_add_fwnode_remote_subdev - Allocate and add a fwnode
 186  *                                                remote async subdev to the
 187  *                                                notifier's master asd_list.
 188  *
 189  * @notif: pointer to &struct v4l2_async_notifier
 190  * @endpoint: local endpoint pointing to the remote sub-device to be matched
 191  * @asd: Async sub-device struct allocated by the caller. The &struct
 192  *       v4l2_async_subdev shall be the first member of the driver's async
 193  *       sub-device struct, i.e. both begin at the same memory address.
 194  *
 195  * Gets the remote endpoint of a given local endpoint, set it up for fwnode
 196  * matching and adds the async sub-device to the notifier's @asd_list. The
 197  * function also gets a reference of the fwnode which is released later at
 198  * notifier cleanup time.
 199  *
 200  * This is just like @v4l2_async_notifier_add_fwnode_subdev, but with the
 201  * exception that the fwnode refers to a local endpoint, not the remote one, and
 202  * the function relies on the caller to allocate the async sub-device struct.
 203  */
 204 int
 205 v4l2_async_notifier_add_fwnode_remote_subdev(struct v4l2_async_notifier *notif,
 206                                              struct fwnode_handle *endpoint,
 207                                              struct v4l2_async_subdev *asd);
 208
 209 /**
 210  * v4l2_async_notifier_add_i2c_subdev - Allocate and add an i2c async
 211  *                              subdev to the notifier's master asd_list.
 212  *
 213  * @notifier: pointer to &struct v4l2_async_notifier
 214  * @adapter_id: I2C adapter ID to be matched
 215  * @address: I2C address of sub-device to be matched
 216  * @asd_struct_size: size of the driver's async sub-device struct, including
 217  *                   sizeof(struct v4l2_async_subdev). The &struct
 218  *                   v4l2_async_subdev shall be the first member of
 219  *                   the driver's async sub-device struct, i.e. both
 220  *                   begin at the same memory address.
 221  *
 222  * Same as above but for I2C matched sub-devices.
 223  */
 224 struct v4l2_async_subdev *
 225 v4l2_async_notifier_add_i2c_subdev(struct v4l2_async_notifier *notifier,
 226                                    int adapter_id, unsigned short address,
 227                                    unsigned int asd_struct_size);
 228
 229 /**
 230  * v4l2_async_notifier_add_devname_subdev - Allocate and add a device-name
 231  *                              async subdev to the notifier's master asd_list.
 232  *
 233  * @notifier: pointer to &struct v4l2_async_notifier
 234  * @device_name: device name string to be matched
 235  * @asd_struct_size: size of the driver's async sub-device struct, including
 236  *                   sizeof(struct v4l2_async_subdev). The &struct
 237  *                   v4l2_async_subdev shall be the first member of
 238  *                   the driver's async sub-device struct, i.e. both
 239  *                   begin at the same memory address.
 240  *
 241  * Same as above but for device-name matched sub-devices.
 242  */
 243 struct v4l2_async_subdev *
 244 v4l2_async_notifier_add_devname_subdev(struct v4l2_async_notifier *notifier,
 245                                        const char *device_name,
 246                                        unsigned int asd_struct_size);
 247
 248 /**
 249  * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
 250  *
 251  * @v4l2_dev: pointer to &struct v4l2_device
 252  * @notifier: pointer to &struct v4l2_async_notifier
 253  */
 254 int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
 255                                  struct v4l2_async_notifier *notifier);
 256
 257 /**
 258  * v4l2_async_subdev_notifier_register - registers a subdevice asynchronous
 259  *                                       notifier for a sub-device
 260  *
 261  * @sd: pointer to &struct v4l2_subdev
 262  * @notifier: pointer to &struct v4l2_async_notifier
 263  */
 264 int v4l2_async_subdev_notifier_register(struct v4l2_subdev *sd,
 265                                         struct v4l2_async_notifier *notifier);
 266
 267 /**
 268  * v4l2_async_notifier_unregister - unregisters a subdevice
 269  *      asynchronous notifier
 270  *
 271  * @notifier: pointer to &struct v4l2_async_notifier
 272  */
 273 void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
 274
 275 /**
 276  * v4l2_async_notifier_cleanup - clean up notifier resources
 277  * @notifier: the notifier the resources of which are to be cleaned up
 278  *
 279  * Release memory resources related to a notifier, including the async
 280  * sub-devices allocated for the purposes of the notifier but not the notifier
 281  * itself. The user is responsible for calling this function to clean up the
 282  * notifier after calling
 283  * @v4l2_async_notifier_add_subdev,
 284  * @v4l2_async_notifier_parse_fwnode_endpoints or
 285  * @v4l2_fwnode_reference_parse_sensor_common.
 286  *
 287  * There is no harm from calling v4l2_async_notifier_cleanup in other
 288  * cases as long as its memory has been zeroed after it has been
 289  * allocated.
 290  */
 291 void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier);
 292
 293 /**
 294  * v4l2_async_register_subdev - registers a sub-device to the asynchronous
 295  *      subdevice framework
 296  *
 297  * @sd: pointer to &struct v4l2_subdev
 298  */
 299 int v4l2_async_register_subdev(struct v4l2_subdev *sd);
 300
 301 /**
 302  * v4l2_async_register_subdev_sensor_common - registers a sensor sub-device to
 303  *                                            the asynchronous sub-device
 304  *                                            framework and parse set up common
 305  *                                            sensor related devices
 306  *
 307  * @sd: pointer to struct &v4l2_subdev
 308  *
 309  * This function is just like v4l2_async_register_subdev() with the exception
 310  * that calling it will also parse firmware interfaces for remote references
 311  * using v4l2_async_notifier_parse_fwnode_sensor_common() and registers the
 312  * async sub-devices. The sub-device is similarly unregistered by calling
 313  * v4l2_async_unregister_subdev().
 314  *
 315  * While registered, the subdev module is marked as in-use.
 316  *
 317  * An error is returned if the module is no longer loaded on any attempts
 318  * to register it.
 319  */
 320 int __must_check
 321 v4l2_async_register_subdev_sensor_common(struct v4l2_subdev *sd);
 322
 323 /**
 324  * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
 325  *      subdevice framework
 326  *
 327  * @sd: pointer to &struct v4l2_subdev
 328  */
 329 void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
 330 #endif