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