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