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
  19 #ifndef _MEDIA_DEVICE_H
  20 #define _MEDIA_DEVICE_H
  21
  22 #include <linux/list.h>
  23 #include <linux/mutex.h>
  24
  25 #include <media/media-devnode.h>
  26 #include <media/media-entity.h>
  27
  28 struct ida;
  29 struct device;
  30
  31 /**
  32  * struct media_entity_notify - Media Entity Notify
  33  *
  34  * @list: List head
  35  * @notify_data: Input data to invoke the callback
  36  * @notify: Callback function pointer
  37  *
  38  * Drivers may register a callback to take action when new entities get
  39  * registered with the media device. This handler is intended for creating
  40  * links between existing entities and should not create entities and register
  41  * them.
  42  */
  43 struct media_entity_notify {
  44         struct list_head list;
  45         void *notify_data;
  46         void (*notify)(struct media_entity *entity, void *notify_data);
  47 };
  48
  49 /**
  50  * struct media_device_ops - Media device operations
  51  * @link_notify: Link state change notification callback. This callback is
  52  *               called with the graph_mutex held.
  53  */
  54 struct media_device_ops {
  55         int (*link_notify)(struct media_link *link, u32 flags,
  56                            unsigned int notification);
  57 };
  58
  59 /**
  60  * struct media_device - Media device
  61  * @dev:        Parent device
  62  * @devnode:    Media device node
  63  * @driver_name: Optional device driver name. If not set, calls to
  64  *              %MEDIA_IOC_DEVICE_INFO will return ``dev->driver->name``.
  65  *              This is needed for USB drivers for example, as otherwise
  66  *              they'll all appear as if the driver name was "usb".
  67  * @model:      Device model name
  68  * @serial:     Device serial number (optional)
  69  * @bus_info:   Unique and stable device location identifier
  70  * @hw_revision: Hardware device revision
  71  * @driver_version: Device driver version
  72  * @topology_version: Monotonic counter for storing the version of the graph
  73  *              topology. Should be incremented each time the topology changes.
  74  * @id:         Unique ID used on the last registered graph object
  75  * @entity_internal_idx: Unique internal entity ID used by the graph traversal
  76  *              algorithms
  77  * @entity_internal_idx_max: Allocated internal entity indices
  78  * @entities:   List of registered entities
  79  * @interfaces: List of registered interfaces
  80  * @pads:       List of registered pads
  81  * @links:      List of registered links
  82  * @entity_notify: List of registered entity_notify callbacks
  83  * @graph_mutex: Protects access to struct media_device data
  84  * @pm_count_walk: Graph walk for power state walk. Access serialised using
  85  *                 graph_mutex.
  86  *
  87  * @source_priv: Driver Private data for enable/disable source handlers
  88  * @enable_source: Enable Source Handler function pointer
  89  * @disable_source: Disable Source Handler function pointer
  90  *
  91  * @ops:        Operation handler callbacks
  92  *
  93  * This structure represents an abstract high-level media device. It allows easy
  94  * access to entities and provides basic media device-level support. The
  95  * structure can be allocated directly or embedded in a larger structure.
  96  *
  97  * The parent @dev is a physical device. It must be set before registering the
  98  * media device.
  99  *
 100  * @model is a descriptive model name exported through sysfs. It doesn't have to
 101  * be unique.
 102  *
 103  * @enable_source is a handler to find source entity for the
 104  * sink entity  and activate the link between them if source
 105  * entity is free. Drivers should call this handler before
 106  * accessing the source.
 107  *
 108  * @disable_source is a handler to find source entity for the
 109  * sink entity  and deactivate the link between them. Drivers
 110  * should call this handler to release the source.
 111  *
 112  * Use-case: find tuner entity connected to the decoder
 113  * entity and check if it is available, and activate the
 114  * the link between them from @enable_source and deactivate
 115  * from @disable_source.
 116  *
 117  * .. note::
 118  *
 119  *    Bridge driver is expected to implement and set the
 120  *    handler when &media_device is registered or when
 121  *    bridge driver finds the media_device during probe.
 122  *    Bridge driver sets source_priv with information
 123  *    necessary to run @enable_source and @disable_source handlers.
 124  *    Callers should hold graph_mutex to access and call @enable_source
 125  *    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_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 /* Iterate over all entities. */
 377 #define media_device_for_each_entity(entity, mdev)                      \
 378         list_for_each_entry(entity, &(mdev)->entities, graph_obj.list)
 379
 380 /* Iterate over all interfaces. */
 381 #define media_device_for_each_intf(intf, mdev)                  \
 382         list_for_each_entry(intf, &(mdev)->interfaces, graph_obj.list)
 383
 384 /* Iterate over all pads. */
 385 #define media_device_for_each_pad(pad, mdev)                    \
 386         list_for_each_entry(pad, &(mdev)->pads, graph_obj.list)
 387
 388 /* Iterate over all links. */
 389 #define media_device_for_each_link(link, mdev)                  \
 390         list_for_each_entry(link, &(mdev)->links, graph_obj.list)
 391
 392 /**
 393  * media_device_pci_init() - create and initialize a
 394  *      struct &media_device from a PCI device.
 395  *
 396  * @mdev:       pointer to struct &media_device
 397  * @pci_dev:    pointer to struct pci_dev
 398  * @name:       media device name. If %NULL, the routine will use the default
 399  *              name for the pci device, given by pci_name() macro.
 400  */
 401 void media_device_pci_init(struct media_device *mdev,
 402                            struct pci_dev *pci_dev,
 403                            const char *name);
 404 /**
 405  * __media_device_usb_init() - create and initialize a
 406  *      struct &media_device from a PCI device.
 407  *
 408  * @mdev:       pointer to struct &media_device
 409  * @udev:       pointer to struct usb_device
 410  * @board_name: media device name. If %NULL, the routine will use the usb
 411  *              product name, if available.
 412  * @driver_name: name of the driver. if %NULL, the routine will use the name
 413  *              given by ``udev->dev->driver->name``, with is usually the wrong
 414  *              thing to do.
 415  *
 416  * .. note::
 417  *
 418  *    It is better to call media_device_usb_init() instead, as
 419  *    such macro fills driver_name with %KBUILD_MODNAME.
 420  */
 421 void __media_device_usb_init(struct media_device *mdev,
 422                              struct usb_device *udev,
 423                              const char *board_name,
 424                              const char *driver_name);
 425
 426 #else
 427 static inline int media_device_register(struct media_device *mdev)
 428 {
 429         return 0;
 430 }
 431 static inline void media_device_unregister(struct media_device *mdev)
 432 {
 433 }
 434 static inline int media_device_register_entity(struct media_device *mdev,
 435                                                 struct media_entity *entity)
 436 {
 437         return 0;
 438 }
 439 static inline void media_device_unregister_entity(struct media_entity *entity)
 440 {
 441 }
 442 static inline int media_device_register_entity_notify(
 443                                         struct media_device *mdev,
 444                                         struct media_entity_notify *nptr)
 445 {
 446         return 0;
 447 }
 448 static inline void media_device_unregister_entity_notify(
 449                                         struct media_device *mdev,
 450                                         struct media_entity_notify *nptr)
 451 {
 452 }
 453
 454 static inline void media_device_pci_init(struct media_device *mdev,
 455                                          struct pci_dev *pci_dev,
 456                                          char *name)
 457 {
 458 }
 459
 460 static inline void __media_device_usb_init(struct media_device *mdev,
 461                                            struct usb_device *udev,
 462                                            char *board_name,
 463                                            char *driver_name)
 464 {
 465 }
 466
 467 #endif /* CONFIG_MEDIA_CONTROLLER */
 468
 469 /**
 470  * media_device_usb_init() - create and initialize a
 471  *      struct &media_device from a PCI device.
 472  *
 473  * @mdev:       pointer to struct &media_device
 474  * @udev:       pointer to struct usb_device
 475  * @name:       media device name. If %NULL, the routine will use the usb
 476  *              product name, if available.
 477  *
 478  * This macro calls media_device_usb_init() passing the
 479  * media_device_usb_init() **driver_name** parameter filled with
 480  * %KBUILD_MODNAME.
 481  */
 482 #define media_device_usb_init(mdev, udev, name) \
 483         __media_device_usb_init(mdev, udev, name, KBUILD_MODNAME)
 484
 485 #endif