[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: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Hans Verkuil <hverkuil@xs4all.nl> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Laurent Pinchart
Mauro Carvalho Chehab
parent
cf4b9211b5
commit
176fb0d108
|
|
@ -0,0 +1,6 @@
|
|||
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;
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,56 @@
|
|||
<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>
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,100 @@
|
|||
/*
|
||||
* 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);
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
/*
|
||||
* 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
|
||||
Reference in New Issue