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