include/media/media-device.h

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