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