Branch data Line data Source code
1 : : /* SPDX-License-Identifier: GPL-2.0-only */ 2 : : /* 3 : : * Media device 4 : : * 5 : : * Copyright (C) 2010 Nokia Corporation 6 : : * 7 : : * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com> 8 : : * Sakari Ailus <sakari.ailus@iki.fi> 9 : : */ 10 : : 11 : : #ifndef _MEDIA_DEVICE_H 12 : : #define _MEDIA_DEVICE_H 13 : : 14 : : #include <linux/list.h> 15 : : #include <linux/mutex.h> 16 : : 17 : : #include <media/media-devnode.h> 18 : : #include <media/media-entity.h> 19 : : 20 : : struct ida; 21 : : struct device; 22 : : struct media_device; 23 : : 24 : : /** 25 : : * struct media_entity_notify - Media Entity Notify 26 : : * 27 : : * @list: List head 28 : : * @notify_data: Input data to invoke the callback 29 : : * @notify: Callback function pointer 30 : : * 31 : : * Drivers may register a callback to take action when new entities get 32 : : * registered with the media device. This handler is intended for creating 33 : : * links between existing entities and should not create entities and register 34 : : * them. 35 : : */ 36 : : struct media_entity_notify { 37 : : struct list_head list; 38 : : void *notify_data; 39 : : void (*notify)(struct media_entity *entity, void *notify_data); 40 : : }; 41 : : 42 : : /** 43 : : * struct media_device_ops - Media device operations 44 : : * @link_notify: Link state change notification callback. This callback is 45 : : * called with the graph_mutex held. 46 : : * @req_alloc: Allocate a request. Set this if you need to allocate a struct 47 : : * larger then struct media_request. @req_alloc and @req_free must 48 : : * either both be set or both be NULL. 49 : : * @req_free: Free a request. Set this if @req_alloc was set as well, leave 50 : : * to NULL otherwise. 51 : : * @req_validate: Validate a request, but do not queue yet. The req_queue_mutex 52 : : * lock is held when this op is called. 53 : : * @req_queue: Queue a validated request, cannot fail. If something goes 54 : : * wrong when queueing this request then it should be marked 55 : : * as such internally in the driver and any related buffers 56 : : * must eventually return to vb2 with state VB2_BUF_STATE_ERROR. 57 : : * The req_queue_mutex lock is held when this op is called. 58 : : * It is important that vb2 buffer objects are queued last after 59 : : * all other object types are queued: queueing a buffer kickstarts 60 : : * the request processing, so all other objects related to the 61 : : * request (and thus the buffer) must be available to the driver. 62 : : * And once a buffer is queued, then the driver can complete 63 : : * or delete objects from the request before req_queue exits. 64 : : */ 65 : : struct media_device_ops { 66 : : int (*link_notify)(struct media_link *link, u32 flags, 67 : : unsigned int notification); 68 : : struct media_request *(*req_alloc)(struct media_device *mdev); 69 : : void (*req_free)(struct media_request *req); 70 : : int (*req_validate)(struct media_request *req); 71 : : void (*req_queue)(struct media_request *req); 72 : : }; 73 : : 74 : : /** 75 : : * struct media_device - Media device 76 : : * @dev: Parent device 77 : : * @devnode: Media device node 78 : : * @driver_name: Optional device driver name. If not set, calls to 79 : : * %MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``. 80 : : * This is needed for USB drivers for example, as otherwise 81 : : * they'll all appear as if the driver name was "usb". 82 : : * @model: Device model name 83 : : * @serial: Device serial number (optional) 84 : : * @bus_info: Unique and stable device location identifier 85 : : * @hw_revision: Hardware device revision 86 : : * @topology_version: Monotonic counter for storing the version of the graph 87 : : * topology. Should be incremented each time the topology changes. 88 : : * @id: Unique ID used on the last registered graph object 89 : : * @entity_internal_idx: Unique internal entity ID used by the graph traversal 90 : : * algorithms 91 : : * @entity_internal_idx_max: Allocated internal entity indices 92 : : * @entities: List of registered entities 93 : : * @interfaces: List of registered interfaces 94 : : * @pads: List of registered pads 95 : : * @links: List of registered links 96 : : * @entity_notify: List of registered entity_notify callbacks 97 : : * @graph_mutex: Protects access to struct media_device data 98 : : * @pm_count_walk: Graph walk for power state walk. Access serialised using 99 : : * graph_mutex. 100 : : * 101 : : * @source_priv: Driver Private data for enable/disable source handlers 102 : : * @enable_source: Enable Source Handler function pointer 103 : : * @disable_source: Disable Source Handler function pointer 104 : : * 105 : : * @ops: Operation handler callbacks 106 : : * @req_queue_mutex: Serialise the MEDIA_REQUEST_IOC_QUEUE ioctl w.r.t. 107 : : * other operations that stop or start streaming. 108 : : * @request_id: Used to generate unique request IDs 109 : : * 110 : : * This structure represents an abstract high-level media device. It allows easy 111 : : * access to entities and provides basic media device-level support. The 112 : : * structure can be allocated directly or embedded in a larger structure. 113 : : * 114 : : * The parent @dev is a physical device. It must be set before registering the 115 : : * media device. 116 : : * 117 : : * @model is a descriptive model name exported through sysfs. It doesn't have to 118 : : * be unique. 119 : : * 120 : : * @enable_source is a handler to find source entity for the 121 : : * sink entity and activate the link between them if source 122 : : * entity is free. Drivers should call this handler before 123 : : * accessing the source. 124 : : * 125 : : * @disable_source is a handler to find source entity for the 126 : : * sink entity and deactivate the link between them. Drivers 127 : : * should call this handler to release the source. 128 : : * 129 : : * Use-case: find tuner entity connected to the decoder 130 : : * entity and check if it is available, and activate the 131 : : * the link between them from @enable_source and deactivate 132 : : * from @disable_source. 133 : : * 134 : : * .. note:: 135 : : * 136 : : * Bridge driver is expected to implement and set the 137 : : * handler when &media_device is registered or when 138 : : * bridge driver finds the media_device during probe. 139 : : * Bridge driver sets source_priv with information 140 : : * necessary to run @enable_source and @disable_source handlers. 141 : : * Callers should hold graph_mutex to access and call @enable_source 142 : : * and @disable_source handlers. 143 : : */ 144 : : struct media_device { 145 : : /* dev->driver_data points to this struct. */ 146 : : struct device *dev; 147 : : struct media_devnode *devnode; 148 : : 149 : : char model[32]; 150 : : char driver_name[32]; 151 : : char serial[40]; 152 : : char bus_info[32]; 153 : : u32 hw_revision; 154 : : 155 : : u64 topology_version; 156 : : 157 : : u32 id; 158 : : struct ida entity_internal_idx; 159 : : int entity_internal_idx_max; 160 : : 161 : : struct list_head entities; 162 : : struct list_head interfaces; 163 : : struct list_head pads; 164 : : struct list_head links; 165 : : 166 : : /* notify callback list invoked when a new entity is registered */ 167 : : struct list_head entity_notify; 168 : : 169 : : /* Serializes graph operations. */ 170 : : struct mutex graph_mutex; 171 : : struct media_graph pm_count_walk; 172 : : 173 : : void *source_priv; 174 : : int (*enable_source)(struct media_entity *entity, 175 : : struct media_pipeline *pipe); 176 : : void (*disable_source)(struct media_entity *entity); 177 : : 178 : : const struct media_device_ops *ops; 179 : : 180 : : struct mutex req_queue_mutex; 181 : : atomic_t request_id; 182 : : }; 183 : : 184 : : /* We don't need to include pci.h or usb.h here */ 185 : : struct pci_dev; 186 : : struct usb_device; 187 : : 188 : : #ifdef CONFIG_MEDIA_CONTROLLER 189 : : 190 : : /* Supported link_notify @notification values. */ 191 : : #define MEDIA_DEV_NOTIFY_PRE_LINK_CH 0 192 : : #define MEDIA_DEV_NOTIFY_POST_LINK_CH 1 193 : : 194 : : /** 195 : : * media_entity_enum_init - Initialise an entity enumeration 196 : : * 197 : : * @ent_enum: Entity enumeration to be initialised 198 : : * @mdev: The related media device 199 : : * 200 : : * Return: zero on success or a negative error code. 201 : : */ 202 : : static inline __must_check int media_entity_enum_init( 203 : : struct media_entity_enum *ent_enum, struct media_device *mdev) 204 : : { 205 : 3 : return __media_entity_enum_init(ent_enum, 206 : 3 : mdev->entity_internal_idx_max + 1); 207 : : } 208 : : 209 : : /** 210 : : * media_device_init() - Initializes a media device element 211 : : * 212 : : * @mdev: pointer to struct &media_device 213 : : * 214 : : * This function initializes the media device prior to its registration. 215 : : * The media device initialization and registration is split in two functions 216 : : * to avoid race conditions and make the media device available to user-space 217 : : * before the media graph has been completed. 218 : : * 219 : : * So drivers need to first initialize the media device, register any entity 220 : : * within the media device, create pad to pad links and then finally register 221 : : * the media device by calling media_device_register() as a final step. 222 : : */ 223 : : void media_device_init(struct media_device *mdev); 224 : : 225 : : /** 226 : : * media_device_cleanup() - Cleanups a media device element 227 : : * 228 : : * @mdev: pointer to struct &media_device 229 : : * 230 : : * This function that will destroy the graph_mutex that is 231 : : * initialized in media_device_init(). 232 : : */ 233 : : void media_device_cleanup(struct media_device *mdev); 234 : : 235 : : /** 236 : : * __media_device_register() - Registers a media device element 237 : : * 238 : : * @mdev: pointer to struct &media_device 239 : : * @owner: should be filled with %THIS_MODULE 240 : : * 241 : : * Users, should, instead, call the media_device_register() macro. 242 : : * 243 : : * The caller is responsible for initializing the &media_device structure 244 : : * before registration. The following fields of &media_device must be set: 245 : : * 246 : : * - &media_entity.dev must point to the parent device (usually a &pci_dev, 247 : : * &usb_interface or &platform_device instance). 248 : : * 249 : : * - &media_entity.model must be filled with the device model name as a 250 : : * NUL-terminated UTF-8 string. The device/model revision must not be 251 : : * stored in this field. 252 : : * 253 : : * The following fields are optional: 254 : : * 255 : : * - &media_entity.serial is a unique serial number stored as a 256 : : * NUL-terminated ASCII string. The field is big enough to store a GUID 257 : : * in text form. If the hardware doesn't provide a unique serial number 258 : : * this field must be left empty. 259 : : * 260 : : * - &media_entity.bus_info represents the location of the device in the 261 : : * system as a NUL-terminated ASCII string. For PCI/PCIe devices 262 : : * &media_entity.bus_info must be set to "PCI:" (or "PCIe:") followed by 263 : : * the value of pci_name(). For USB devices,the usb_make_path() function 264 : : * must be used. This field is used by applications to distinguish between 265 : : * otherwise identical devices that don't provide a serial number. 266 : : * 267 : : * - &media_entity.hw_revision is the hardware device revision in a 268 : : * driver-specific format. When possible the revision should be formatted 269 : : * with the KERNEL_VERSION() macro. 270 : : * 271 : : * .. note:: 272 : : * 273 : : * #) Upon successful registration a character device named media[0-9]+ is created. The device major and minor numbers are dynamic. The model name is exported as a sysfs attribute. 274 : : * 275 : : * #) Unregistering a media device that hasn't been registered is **NOT** safe. 276 : : * 277 : : * Return: returns zero on success or a negative error code. 278 : : */ 279 : : int __must_check __media_device_register(struct media_device *mdev, 280 : : struct module *owner); 281 : : 282 : : 283 : : /** 284 : : * media_device_register() - Registers a media device element 285 : : * 286 : : * @mdev: pointer to struct &media_device 287 : : * 288 : : * This macro calls __media_device_register() passing %THIS_MODULE as 289 : : * the __media_device_register() second argument (**owner**). 290 : : */ 291 : : #define media_device_register(mdev) __media_device_register(mdev, THIS_MODULE) 292 : : 293 : : /** 294 : : * media_device_unregister() - Unregisters a media device element 295 : : * 296 : : * @mdev: pointer to struct &media_device 297 : : * 298 : : * It is safe to call this function on an unregistered (but initialised) 299 : : * media device. 300 : : */ 301 : : void media_device_unregister(struct media_device *mdev); 302 : : 303 : : /** 304 : : * media_device_register_entity() - registers a media entity inside a 305 : : * previously registered media device. 306 : : * 307 : : * @mdev: pointer to struct &media_device 308 : : * @entity: pointer to struct &media_entity to be registered 309 : : * 310 : : * Entities are identified by a unique positive integer ID. The media 311 : : * controller framework will such ID automatically. IDs are not guaranteed 312 : : * to be contiguous, and the ID number can change on newer Kernel versions. 313 : : * So, neither the driver nor userspace should hardcode ID numbers to refer 314 : : * to the entities, but, instead, use the framework to find the ID, when 315 : : * needed. 316 : : * 317 : : * The media_entity name, type and flags fields should be initialized before 318 : : * calling media_device_register_entity(). Entities embedded in higher-level 319 : : * standard structures can have some of those fields set by the higher-level 320 : : * framework. 321 : : * 322 : : * If the device has pads, media_entity_pads_init() should be called before 323 : : * this function. Otherwise, the &media_entity.pad and &media_entity.num_pads 324 : : * should be zeroed before calling this function. 325 : : * 326 : : * Entities have flags that describe the entity capabilities and state: 327 : : * 328 : : * %MEDIA_ENT_FL_DEFAULT 329 : : * indicates the default entity for a given type. 330 : : * This can be used to report the default audio and video devices or the 331 : : * default camera sensor. 332 : : * 333 : : * .. note:: 334 : : * 335 : : * Drivers should set the entity function before calling this function. 336 : : * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and 337 : : * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers. 338 : : */ 339 : : int __must_check media_device_register_entity(struct media_device *mdev, 340 : : struct media_entity *entity); 341 : : 342 : : /** 343 : : * media_device_unregister_entity() - unregisters a media entity. 344 : : * 345 : : * @entity: pointer to struct &media_entity to be unregistered 346 : : * 347 : : * All links associated with the entity and all PADs are automatically 348 : : * unregistered from the media_device when this function is called. 349 : : * 350 : : * Unregistering an entity will not change the IDs of the other entities and 351 : : * the previoully used ID will never be reused for a newly registered entities. 352 : : * 353 : : * When a media device is unregistered, all its entities are unregistered 354 : : * automatically. No manual entities unregistration is then required. 355 : : * 356 : : * .. note:: 357 : : * 358 : : * The media_entity instance itself must be freed explicitly by 359 : : * the driver if required. 360 : : */ 361 : : void media_device_unregister_entity(struct media_entity *entity); 362 : : 363 : : /** 364 : : * media_device_register_entity_notify() - Registers a media entity_notify 365 : : * callback 366 : : * 367 : : * @mdev: The media device 368 : : * @nptr: The media_entity_notify 369 : : * 370 : : * .. note:: 371 : : * 372 : : * When a new entity is registered, all the registered 373 : : * media_entity_notify callbacks are invoked. 374 : : */ 375 : : 376 : : int __must_check media_device_register_entity_notify(struct media_device *mdev, 377 : : struct media_entity_notify *nptr); 378 : : 379 : : /** 380 : : * media_device_unregister_entity_notify() - Unregister a media entity notify 381 : : * callback 382 : : * 383 : : * @mdev: The media device 384 : : * @nptr: The media_entity_notify 385 : : * 386 : : */ 387 : : void media_device_unregister_entity_notify(struct media_device *mdev, 388 : : struct media_entity_notify *nptr); 389 : : 390 : : /* Iterate over all entities. */ 391 : : #define media_device_for_each_entity(entity, mdev) \ 392 : : list_for_each_entry(entity, &(mdev)->entities, graph_obj.list) 393 : : 394 : : /* Iterate over all interfaces. */ 395 : : #define media_device_for_each_intf(intf, mdev) \ 396 : : list_for_each_entry(intf, &(mdev)->interfaces, graph_obj.list) 397 : : 398 : : /* Iterate over all pads. */ 399 : : #define media_device_for_each_pad(pad, mdev) \ 400 : : list_for_each_entry(pad, &(mdev)->pads, graph_obj.list) 401 : : 402 : : /* Iterate over all links. */ 403 : : #define media_device_for_each_link(link, mdev) \ 404 : : list_for_each_entry(link, &(mdev)->links, graph_obj.list) 405 : : 406 : : /** 407 : : * media_device_pci_init() - create and initialize a 408 : : * struct &media_device from a PCI device. 409 : : * 410 : : * @mdev: pointer to struct &media_device 411 : : * @pci_dev: pointer to struct pci_dev 412 : : * @name: media device name. If %NULL, the routine will use the default 413 : : * name for the pci device, given by pci_name() macro. 414 : : */ 415 : : void media_device_pci_init(struct media_device *mdev, 416 : : struct pci_dev *pci_dev, 417 : : const char *name); 418 : : /** 419 : : * __media_device_usb_init() - create and initialize a 420 : : * struct &media_device from a PCI device. 421 : : * 422 : : * @mdev: pointer to struct &media_device 423 : : * @udev: pointer to struct usb_device 424 : : * @board_name: media device name. If %NULL, the routine will use the usb 425 : : * product name, if available. 426 : : * @driver_name: name of the driver. if %NULL, the routine will use the name 427 : : * given by ``udev->dev->driver->name``, with is usually the wrong 428 : : * thing to do. 429 : : * 430 : : * .. note:: 431 : : * 432 : : * It is better to call media_device_usb_init() instead, as 433 : : * such macro fills driver_name with %KBUILD_MODNAME. 434 : : */ 435 : : void __media_device_usb_init(struct media_device *mdev, 436 : : struct usb_device *udev, 437 : : const char *board_name, 438 : : const char *driver_name); 439 : : 440 : : #else 441 : : static inline int media_device_register(struct media_device *mdev) 442 : : { 443 : : return 0; 444 : : } 445 : : static inline void media_device_unregister(struct media_device *mdev) 446 : : { 447 : : } 448 : : static inline int media_device_register_entity(struct media_device *mdev, 449 : : struct media_entity *entity) 450 : : { 451 : : return 0; 452 : : } 453 : : static inline void media_device_unregister_entity(struct media_entity *entity) 454 : : { 455 : : } 456 : : static inline int media_device_register_entity_notify( 457 : : struct media_device *mdev, 458 : : struct media_entity_notify *nptr) 459 : : { 460 : : return 0; 461 : : } 462 : : static inline void media_device_unregister_entity_notify( 463 : : struct media_device *mdev, 464 : : struct media_entity_notify *nptr) 465 : : { 466 : : } 467 : : 468 : : static inline void media_device_pci_init(struct media_device *mdev, 469 : : struct pci_dev *pci_dev, 470 : : char *name) 471 : : { 472 : : } 473 : : 474 : : static inline void __media_device_usb_init(struct media_device *mdev, 475 : : struct usb_device *udev, 476 : : char *board_name, 477 : : char *driver_name) 478 : : { 479 : : } 480 : : 481 : : #endif /* CONFIG_MEDIA_CONTROLLER */ 482 : : 483 : : /** 484 : : * media_device_usb_init() - create and initialize a 485 : : * struct &media_device from a PCI device. 486 : : * 487 : : * @mdev: pointer to struct &media_device 488 : : * @udev: pointer to struct usb_device 489 : : * @name: media device name. If %NULL, the routine will use the usb 490 : : * product name, if available. 491 : : * 492 : : * This macro calls media_device_usb_init() passing the 493 : : * media_device_usb_init() **driver_name** parameter filled with 494 : : * %KBUILD_MODNAME. 495 : : */ 496 : : #define media_device_usb_init(mdev, udev, name) \ 497 : : __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME) 498 : : 499 : : #endif