[media] media: Media device

What:		/sys/bus/media/devices/.../model

Date:		January 2011

Contact:	Laurent Pinchart <laurent.pinchart@ideasonboard.com>

		linux-media@vger.kernel.org

Description:	Contains the device model name in UTF-8. The device version is

		is not be appended to the model name.

<!ENTITY sub-media-entities SYSTEM "media-entities.tmpl">

<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">

<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">

<!-- Function Reference -->

<!ENTITY close SYSTEM "v4l/func-close.xml">

<!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml">

&sub-remote_controllers;

</chapter>

</part>

<part id="media_common">

&sub-media-controller;

</part>

&sub-fdl-appendix;

<partinfo>

  <authorgroup>

    <author>

      <firstname>Laurent</firstname>

      <surname>Pinchart</surname>

      <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation>

      <contrib>Initial version.</contrib>

    </author>

  </authorgroup>

  <copyright>

    <year>2010</year>

    <holder>Laurent Pinchart</holder>

  </copyright>

  <revhistory>

    <!-- Put document revisions here, newest first. -->

    <revision>

      <revnumber>1.0.0</revnumber>

      <date>2010-11-10</date>

      <authorinitials>lp</authorinitials>

      <revremark>Initial revision</revremark>

    </revision>

  </revhistory>

</partinfo>

<title>Media Controller API</title>

<chapter id="media_controller">

  <title>Media Controller</title>

  <section id="media-controller-intro">

    <title>Introduction</title>

    <para>Media devices increasingly handle multiple related functions. Many USB

    cameras include microphones, video capture hardware can also output video,

    or SoC camera interfaces also perform memory-to-memory operations similar to

    video codecs.</para>

    <para>Independent functions, even when implemented in the same hardware, can

    be modelled as separate devices. A USB camera with a microphone will be

    presented to userspace applications as V4L2 and ALSA capture devices. The

    devices' relationships (when using a webcam, end-users shouldn't have to

    manually select the associated USB microphone), while not made available

    directly to applications by the drivers, can usually be retrieved from

    sysfs.</para>

    <para>With more and more advanced SoC devices being introduced, the current

    approach will not scale. Device topologies are getting increasingly complex

    and can't always be represented by a tree structure. Hardware blocks are

    shared between different functions, creating dependencies between seemingly

    unrelated devices.</para>

    <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for

    applications to access hardware parameters. As newer hardware expose an

    increasingly high number of those parameters, drivers need to guess what

    applications really require based on limited information, thereby

    implementing policies that belong to userspace.</para>

    <para>The media controller API aims at solving those problems.</para>

  </section>

</chapter>

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.