Documentation/media-framework.txt

Linux kernel media framework
============================

This document describes the Linux kernel media framework, its data structures,
functions and their usage.


Introduction
------------

The media controller API is documented in DocBook format in
Documentation/DocBook/v4l/media-controller.xml. This document will focus on
the kernel-side implementation of the media framework.


Media device
------------

A media device is represented by a struct media_device instance, defined in
include/media/media-device.h. Allocation of the structure is handled by the
media device driver, usually by embedding the media_device instance in a
larger driver-specific structure.

Drivers register media device instances by calling

	media_device_register(struct media_device *mdev);

The caller is responsible for initializing the media_device structure before
registration. The following fields must be set:

 - dev must point to the parent device (usually a pci_dev, usb_interface or
   platform_device instance).

 - model must be filled with the device model name as a NUL-terminated UTF-8
   string. The device/model revision must not be stored in this field.

The following fields are optional:

 - serial is a unique serial number stored as a NUL-terminated ASCII string.
   The field is big enough to store a GUID in text form. If the hardware
   doesn't provide a unique serial number this field must be left empty.

 - bus_info represents the location of the device in the system as a
   NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to
   "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices,
   the usb_make_path() function must be used. This field is used by
   applications to distinguish between otherwise identical devices that don't
   provide a serial number.

 - hw_revision is the hardware device revision in a driver-specific format.
   When possible the revision should be formatted with the KERNEL_VERSION
   macro.

 - driver_version is formatted with the KERNEL_VERSION macro. The version
   minor must be incremented when new features are added to the userspace API
   without breaking binary compatibility. The version major must be
   incremented when binary compatibility is broken.

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.

Drivers unregister media device instances by calling

	media_device_unregister(struct media_device *mdev);

Unregistering a media device that hasn't been registered is *NOT* safe.