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
 176  * to the notifiers @asd_list.
 177  */
 178 struct v4l2_async_subdev *
 179 v4l2_async_notifier_add_fwnode_subdev(struct v4l2_async_notifier *notifier,
 180                                       struct fwnode_handle *fwnode,
 181                                       unsigned int asd_struct_size);
 182
 183 /**
 184  * v4l2_async_notifier_add_i2c_subdev - Allocate and add an i2c async
 185  *                              subdev to the notifier's master asd_list.
 186  *
 187  * @notifier: pointer to &struct v4l2_async_notifier
 188  * @adapter_id: I2C adapter ID to be matched
 189  * @address: I2C address of sub-device to be matched
 190  * @asd_struct_size: size of the driver's async sub-device struct, including
 191  *                   sizeof(struct v4l2_async_subdev). The &struct
 192  *                   v4l2_async_subdev shall be the first member of
 193  *                   the driver's async sub-device struct, i.e. both
 194  *                   begin at the same memory address.
 195  *
 196  * Same as above but for I2C matched sub-devices.
 197  */
 198 struct v4l2_async_subdev *
 199 v4l2_async_notifier_add_i2c_subdev(struct v4l2_async_notifier *notifier,
 200                                    int adapter_id, unsigned short address,
 201                                    unsigned int asd_struct_size);
 202
 203 /**
 204  * v4l2_async_notifier_add_devname_subdev - Allocate and add a device-name
 205  *                              async subdev to the notifier's master asd_list.
 206  *
 207  * @notifier: pointer to &struct v4l2_async_notifier
 208  * @device_name: device name string to be matched
 209  * @asd_struct_size: size of the driver's async sub-device struct, including
 210  *                   sizeof(struct v4l2_async_subdev). The &struct
 211  *                   v4l2_async_subdev shall be the first member of
 212  *                   the driver's async sub-device struct, i.e. both
 213  *                   begin at the same memory address.
 214  *
 215  * Same as above but for device-name matched sub-devices.
 216  */
 217 struct v4l2_async_subdev *
 218 v4l2_async_notifier_add_devname_subdev(struct v4l2_async_notifier *notifier,
 219                                        const char *device_name,
 220                                        unsigned int asd_struct_size);
 221
 222 /**
 223  * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
 224  *
 225  * @v4l2_dev: pointer to &struct v4l2_device
 226  * @notifier: pointer to &struct v4l2_async_notifier
 227  */
 228 int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
 229                                  struct v4l2_async_notifier *notifier);
 230
 231 /**
 232  * v4l2_async_subdev_notifier_register - registers a subdevice asynchronous
 233  *                                       notifier for a sub-device
 234  *
 235  * @sd: pointer to &struct v4l2_subdev
 236  * @notifier: pointer to &struct v4l2_async_notifier
 237  */
 238 int v4l2_async_subdev_notifier_register(struct v4l2_subdev *sd,
 239                                         struct v4l2_async_notifier *notifier);
 240
 241 /**
 242  * v4l2_async_notifier_unregister - unregisters a subdevice
 243  *      asynchronous notifier
 244  *
 245  * @notifier: pointer to &struct v4l2_async_notifier
 246  */
 247 void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
 248
 249 /**
 250  * v4l2_async_notifier_cleanup - clean up notifier resources
 251  * @notifier: the notifier the resources of which are to be cleaned up
 252  *
 253  * Release memory resources related to a notifier, including the async
 254  * sub-devices allocated for the purposes of the notifier but not the notifier
 255  * itself. The user is responsible for calling this function to clean up the
 256  * notifier after calling
 257  * @v4l2_async_notifier_add_subdev,
 258  * @v4l2_async_notifier_parse_fwnode_endpoints or
 259  * @v4l2_fwnode_reference_parse_sensor_common.
 260  *
 261  * There is no harm from calling v4l2_async_notifier_cleanup in other
 262  * cases as long as its memory has been zeroed after it has been
 263  * allocated.
 264  */
 265 void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier);
 266
 267 /**
 268  * v4l2_async_register_subdev - registers a sub-device to the asynchronous
 269  *      subdevice framework
 270  *
 271  * @sd: pointer to &struct v4l2_subdev
 272  */
 273 int v4l2_async_register_subdev(struct v4l2_subdev *sd);
 274
 275 /**
 276  * v4l2_async_register_subdev_sensor_common - registers a sensor sub-device to
 277  *                                            the asynchronous sub-device
 278  *                                            framework and parse set up common
 279  *                                            sensor related devices
 280  *
 281  * @sd: pointer to struct &v4l2_subdev
 282  *
 283  * This function is just like v4l2_async_register_subdev() with the exception
 284  * that calling it will also parse firmware interfaces for remote references
 285  * using v4l2_async_notifier_parse_fwnode_sensor_common() and registers the
 286  * async sub-devices. The sub-device is similarly unregistered by calling
 287  * v4l2_async_unregister_subdev().
 288  *
 289  * While registered, the subdev module is marked as in-use.
 290  *
 291  * An error is returned if the module is no longer loaded on any attempts
 292  * to register it.
 293  */
 294 int __must_check
 295 v4l2_async_register_subdev_sensor_common(struct v4l2_subdev *sd);
 296
 297 /**
 298  * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
 299  *      subdevice framework
 300  *
 301  * @sd: pointer to &struct v4l2_subdev
 302  */
 303 void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
 304 #endif