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