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