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