Documentation/media-framework.txt

   1 Linux kernel media framework
   2 ============================
   3
   4 This document describes the Linux kernel media framework, its data structures,
   5 functions and their usage.
   6
   7
   8 Introduction
   9 ------------
  10
  11 The media controller API is documented in DocBook format in
  12 Documentation/DocBook/v4l/media-controller.xml. This document will focus on
  13 the kernel-side implementation of the media framework.
  14
  15
  16 Media device
  17 ------------
  18
  19 A media device is represented by a struct media_device instance, defined in
  20 include/media/media-device.h. Allocation of the structure is handled by the
  21 media device driver, usually by embedding the media_device instance in a
  22 larger driver-specific structure.
  23
  24 Drivers register media device instances by calling
  25
  26         media_device_register(struct media_device *mdev);
  27
  28 The caller is responsible for initializing the media_device structure before
  29 registration. The following fields must be set:
  30
  31  - dev must point to the parent device (usually a pci_dev, usb_interface or
  32    platform_device instance).
  33
  34  - model must be filled with the device model name as a NUL-terminated UTF-8
  35    string. The device/model revision must not be stored in this field.
  36
  37 The following fields are optional:
  38
  39  - serial is a unique serial number stored as a NUL-terminated ASCII string.
  40    The field is big enough to store a GUID in text form. If the hardware
  41    doesn't provide a unique serial number this field must be left empty.
  42
  43  - bus_info represents the location of the device in the system as a
  44    NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to
  45    "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices,
  46    the usb_make_path() function must be used. This field is used by
  47    applications to distinguish between otherwise identical devices that don't
  48    provide a serial number.
  49
  50  - hw_revision is the hardware device revision in a driver-specific format.
  51    When possible the revision should be formatted with the KERNEL_VERSION
  52    macro.
  53
  54  - driver_version is formatted with the KERNEL_VERSION macro. The version
  55    minor must be incremented when new features are added to the userspace API
  56    without breaking binary compatibility. The version major must be
  57    incremented when binary compatibility is broken.
  58
  59 Upon successful registration a character device named media[0-9]+ is created.
  60 The device major and minor numbers are dynamic. The model name is exported as
  61 a sysfs attribute.
  62
  63 Drivers unregister media device instances by calling
  64
  65         media_device_unregister(struct media_device *mdev);
  66
  67 Unregistering a media device that hasn't been registered is *NOT* safe.