Commit 176fb0d1 authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Mauro Carvalho Chehab

[media] media: Media device

The media_device structure abstracts functions common to all kind of
media devices (v4l2, dvb, alsa, ...). It manages media entities and
offers a userspace API to discover and configure the media device
internal topology.
Signed-off-by: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: default avatarHans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent cf4b9211
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.
......@@ -327,6 +327,8 @@
<!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">
......
......@@ -106,6 +106,9 @@ Foundation. A copy of the license is included in the chapter entitled
&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.
......@@ -2,7 +2,7 @@
# Makefile for the kernel multimedia device drivers.
#
media-objs := media-devnode.o
media-objs := media-device.o media-devnode.o
ifeq ($(CONFIG_MEDIA_CONTROLLER),y)
obj-$(CONFIG_MEDIA_SUPPORT) += media.o
......
/*
* Media device
*
* Copyright (C) 2010 Nokia Corporation
*
* Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
* Sakari Ailus <sakari.ailus@iki.fi>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#include <linux/types.h>
#include <linux/ioctl.h>
#include <media/media-device.h>
#include <media/media-devnode.h>
static const struct media_file_operations media_device_fops = {
.owner = THIS_MODULE,
};
/* -----------------------------------------------------------------------------
* sysfs
*/
static ssize_t show_model(struct device *cd,
struct device_attribute *attr, char *buf)
{
struct media_device *mdev = to_media_device(to_media_devnode(cd));
return sprintf(buf, "%.*s\n", (int)sizeof(mdev->model), mdev->model);
}
static DEVICE_ATTR(model, S_IRUGO, show_model, NULL);
/* -----------------------------------------------------------------------------
* Registration/unregistration
*/
static void media_device_release(struct media_devnode *mdev)
{
}
/**
* media_device_register - register a media device
* @mdev: The media device
*
* The caller is responsible for initializing the media device before
* registration. The following fields must be set:
*
* - dev must point to the parent device
* - model must be filled with the device model name
*/
int __must_check media_device_register(struct media_device *mdev)
{
int ret;
if (WARN_ON(mdev->dev == NULL || mdev->model[0] == 0))
return -EINVAL;
/* Register the device node. */
mdev->devnode.fops = &media_device_fops;
mdev->devnode.parent = mdev->dev;
mdev->devnode.release = media_device_release;
ret = media_devnode_register(&mdev->devnode);
if (ret < 0)
return ret;
ret = device_create_file(&mdev->devnode.dev, &dev_attr_model);
if (ret < 0) {
media_devnode_unregister(&mdev->devnode);
return ret;
}
return 0;
}
EXPORT_SYMBOL_GPL(media_device_register);
/**
* media_device_unregister - unregister a media device
* @mdev: The media device
*
*/
void media_device_unregister(struct media_device *mdev)
{
device_remove_file(&mdev->devnode.dev, &dev_attr_model);
media_devnode_unregister(&mdev->devnode);
}
EXPORT_SYMBOL_GPL(media_device_unregister);
/*
* Media device
*
* Copyright (C) 2010 Nokia Corporation
*
* Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
* Sakari Ailus <sakari.ailus@iki.fi>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef _MEDIA_DEVICE_H
#define _MEDIA_DEVICE_H
#include <linux/device.h>
#include <linux/list.h>
#include <media/media-devnode.h>
/**
* struct media_device - Media device
* @dev: Parent device
* @devnode: Media device node
* @model: Device model name
* @serial: Device serial number (optional)
* @bus_info: Unique and stable device location identifier
* @hw_revision: Hardware device revision
* @driver_version: Device driver version
*
* This structure represents an abstract high-level media device. It allows easy
* access to entities and provides basic media device-level support. The
* structure can be allocated directly or embedded in a larger structure.
*
* The parent @dev is a physical device. It must be set before registering the
* media device.
*
* @model is a descriptive model name exported through sysfs. It doesn't have to
* be unique.
*/
struct media_device {
/* dev->driver_data points to this struct. */
struct device *dev;
struct media_devnode devnode;
char model[32];
char serial[40];
char bus_info[32];
u32 hw_revision;
u32 driver_version;
};
/* media_devnode to media_device */
#define to_media_device(node) container_of(node, struct media_device, devnode)
int __must_check media_device_register(struct media_device *mdev);
void media_device_unregister(struct media_device *mdev);
#endif
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment