aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Documentation/ABI/testing/sysfs-bus-media6
-rw-r--r--Documentation/DocBook/media-entities.tmpl2
-rw-r--r--Documentation/DocBook/media.tmpl3
-rw-r--r--Documentation/DocBook/v4l/media-controller.xml56
-rw-r--r--Documentation/media-framework.txt67
-rw-r--r--drivers/media/Makefile2
-rw-r--r--drivers/media/media-device.c100
-rw-r--r--include/media/media-device.h69
8 files changed, 304 insertions, 1 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-media b/Documentation/ABI/testing/sysfs-bus-media
new file mode 100644
index 000000000000..7057e574154a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-media
@@ -0,0 +1,6 @@
1What: /sys/bus/media/devices/.../model
2Date: January 2011
3Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
4 linux-media@vger.kernel.org
5Description: Contains the device model name in UTF-8. The device version is
6 is not be appended to the model name.
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index d2f99e5a3a2f..c47897f046b1 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -327,6 +327,8 @@
327<!ENTITY sub-media-entities SYSTEM "media-entities.tmpl"> 327<!ENTITY sub-media-entities SYSTEM "media-entities.tmpl">
328<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl"> 328<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">
329 329
330<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">
331
330<!-- Function Reference --> 332<!-- Function Reference -->
331<!ENTITY close SYSTEM "v4l/func-close.xml"> 333<!ENTITY close SYSTEM "v4l/func-close.xml">
332<!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml"> 334<!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml">
diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl
index a99088aae1aa..88f2cc680cc2 100644
--- a/Documentation/DocBook/media.tmpl
+++ b/Documentation/DocBook/media.tmpl
@@ -106,6 +106,9 @@ Foundation. A copy of the license is included in the chapter entitled
106&sub-remote_controllers; 106&sub-remote_controllers;
107</chapter> 107</chapter>
108</part> 108</part>
109<part id="media_common">
110&sub-media-controller;
111</part>
109 112
110&sub-fdl-appendix; 113&sub-fdl-appendix;
111 114
diff --git a/Documentation/DocBook/v4l/media-controller.xml b/Documentation/DocBook/v4l/media-controller.xml
new file mode 100644
index 000000000000..253ddb4426c9
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-controller.xml
@@ -0,0 +1,56 @@
1<partinfo>
2 <authorgroup>
3 <author>
4 <firstname>Laurent</firstname>
5 <surname>Pinchart</surname>
6 <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation>
7 <contrib>Initial version.</contrib>
8 </author>
9 </authorgroup>
10 <copyright>
11 <year>2010</year>
12 <holder>Laurent Pinchart</holder>
13 </copyright>
14
15 <revhistory>
16 <!-- Put document revisions here, newest first. -->
17 <revision>
18 <revnumber>1.0.0</revnumber>
19 <date>2010-11-10</date>
20 <authorinitials>lp</authorinitials>
21 <revremark>Initial revision</revremark>
22 </revision>
23 </revhistory>
24</partinfo>
25
26<title>Media Controller API</title>
27
28<chapter id="media_controller">
29 <title>Media Controller</title>
30
31 <section id="media-controller-intro">
32 <title>Introduction</title>
33 <para>Media devices increasingly handle multiple related functions. Many USB
34 cameras include microphones, video capture hardware can also output video,
35 or SoC camera interfaces also perform memory-to-memory operations similar to
36 video codecs.</para>
37 <para>Independent functions, even when implemented in the same hardware, can
38 be modelled as separate devices. A USB camera with a microphone will be
39 presented to userspace applications as V4L2 and ALSA capture devices. The
40 devices' relationships (when using a webcam, end-users shouldn't have to
41 manually select the associated USB microphone), while not made available
42 directly to applications by the drivers, can usually be retrieved from
43 sysfs.</para>
44 <para>With more and more advanced SoC devices being introduced, the current
45 approach will not scale. Device topologies are getting increasingly complex
46 and can't always be represented by a tree structure. Hardware blocks are
47 shared between different functions, creating dependencies between seemingly
48 unrelated devices.</para>
49 <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for
50 applications to access hardware parameters. As newer hardware expose an
51 increasingly high number of those parameters, drivers need to guess what
52 applications really require based on limited information, thereby
53 implementing policies that belong to userspace.</para>
54 <para>The media controller API aims at solving those problems.</para>
55 </section>
56</chapter>
diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt
new file mode 100644
index 000000000000..1844c3f10728
--- /dev/null
+++ b/Documentation/media-framework.txt
@@ -0,0 +1,67 @@
1Linux kernel media framework
2============================
3
4This document describes the Linux kernel media framework, its data structures,
5functions and their usage.
6
7
8Introduction
9------------
10
11The media controller API is documented in DocBook format in
12Documentation/DocBook/v4l/media-controller.xml. This document will focus on
13the kernel-side implementation of the media framework.
14
15
16Media device
17------------
18
19A media device is represented by a struct media_device instance, defined in
20include/media/media-device.h. Allocation of the structure is handled by the
21media device driver, usually by embedding the media_device instance in a
22larger driver-specific structure.
23
24Drivers register media device instances by calling
25
26 media_device_register(struct media_device *mdev);
27
28The caller is responsible for initializing the media_device structure before
29registration. 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
37The 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
59Upon successful registration a character device named media[0-9]+ is created.
60The device major and minor numbers are dynamic. The model name is exported as
61a sysfs attribute.
62
63Drivers unregister media device instances by calling
64
65 media_device_unregister(struct media_device *mdev);
66
67Unregistering a media device that hasn't been registered is *NOT* safe.
diff --git a/drivers/media/Makefile b/drivers/media/Makefile
index d56349f6103f..36731aae57ea 100644
--- a/drivers/media/Makefile
+++ b/drivers/media/Makefile
@@ -2,7 +2,7 @@
2# Makefile for the kernel multimedia device drivers. 2# Makefile for the kernel multimedia device drivers.
3# 3#
4 4
5media-objs := media-devnode.o 5media-objs := media-device.o media-devnode.o
6 6
7ifeq ($(CONFIG_MEDIA_CONTROLLER),y) 7ifeq ($(CONFIG_MEDIA_CONTROLLER),y)
8 obj-$(CONFIG_MEDIA_SUPPORT) += media.o 8 obj-$(CONFIG_MEDIA_SUPPORT) += media.o
diff --git a/drivers/media/media-device.c b/drivers/media/media-device.c
new file mode 100644
index 000000000000..bcd3985d415a
--- /dev/null
+++ b/drivers/media/media-device.c
@@ -0,0 +1,100 @@
1/*
2 * Media device
3 *
4 * Copyright (C) 2010 Nokia Corporation
5 *
6 * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
7 * Sakari Ailus <sakari.ailus@iki.fi>
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License version 2 as
11 * published by the Free Software Foundation.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 */
22
23#include <linux/types.h>
24#include <linux/ioctl.h>
25
26#include <media/media-device.h>
27#include <media/media-devnode.h>
28
29static const struct media_file_operations media_device_fops = {
30 .owner = THIS_MODULE,
31};
32
33/* -----------------------------------------------------------------------------
34 * sysfs
35 */
36
37static ssize_t show_model(struct device *cd,
38 struct device_attribute *attr, char *buf)
39{
40 struct media_device *mdev = to_media_device(to_media_devnode(cd));
41
42 return sprintf(buf, "%.*s\n", (int)sizeof(mdev->model), mdev->model);
43}
44
45static DEVICE_ATTR(model, S_IRUGO, show_model, NULL);
46
47/* -----------------------------------------------------------------------------
48 * Registration/unregistration
49 */
50
51static void media_device_release(struct media_devnode *mdev)
52{
53}
54
55/**
56 * media_device_register - register a media device
57 * @mdev: The media device
58 *
59 * The caller is responsible for initializing the media device before
60 * registration. The following fields must be set:
61 *
62 * - dev must point to the parent device
63 * - model must be filled with the device model name
64 */
65int __must_check media_device_register(struct media_device *mdev)
66{
67 int ret;
68
69 if (WARN_ON(mdev->dev == NULL || mdev->model[0] == 0))
70 return -EINVAL;
71
72 /* Register the device node. */
73 mdev->devnode.fops = &media_device_fops;
74 mdev->devnode.parent = mdev->dev;
75 mdev->devnode.release = media_device_release;
76 ret = media_devnode_register(&mdev->devnode);
77 if (ret < 0)
78 return ret;
79
80 ret = device_create_file(&mdev->devnode.dev, &dev_attr_model);
81 if (ret < 0) {
82 media_devnode_unregister(&mdev->devnode);
83 return ret;
84 }
85
86 return 0;
87}
88EXPORT_SYMBOL_GPL(media_device_register);
89
90/**
91 * media_device_unregister - unregister a media device
92 * @mdev: The media device
93 *
94 */
95void media_device_unregister(struct media_device *mdev)
96{
97 device_remove_file(&mdev->devnode.dev, &dev_attr_model);
98 media_devnode_unregister(&mdev->devnode);
99}
100EXPORT_SYMBOL_GPL(media_device_unregister);
diff --git a/include/media/media-device.h b/include/media/media-device.h
new file mode 100644
index 000000000000..30857f7fc22b
--- /dev/null
+++ b/include/media/media-device.h
@@ -0,0 +1,69 @@
1/*
2 * Media device
3 *
4 * Copyright (C) 2010 Nokia Corporation
5 *
6 * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
7 * Sakari Ailus <sakari.ailus@iki.fi>
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License version 2 as
11 * published by the Free Software Foundation.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 *
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 */
22
23#ifndef _MEDIA_DEVICE_H
24#define _MEDIA_DEVICE_H
25
26#include <linux/device.h>
27#include <linux/list.h>
28
29#include <media/media-devnode.h>
30
31/**
32 * struct media_device - Media device
33 * @dev: Parent device
34 * @devnode: Media device node
35 * @model: Device model name
36 * @serial: Device serial number (optional)
37 * @bus_info: Unique and stable device location identifier
38 * @hw_revision: Hardware device revision
39 * @driver_version: Device driver version
40 *
41 * This structure represents an abstract high-level media device. It allows easy
42 * access to entities and provides basic media device-level support. The
43 * structure can be allocated directly or embedded in a larger structure.
44 *
45 * The parent @dev is a physical device. It must be set before registering the
46 * media device.
47 *
48 * @model is a descriptive model name exported through sysfs. It doesn't have to
49 * be unique.
50 */
51struct media_device {
52 /* dev->driver_data points to this struct. */
53 struct device *dev;
54 struct media_devnode devnode;
55
56 char model[32];
57 char serial[40];
58 char bus_info[32];
59 u32 hw_revision;
60 u32 driver_version;
61};
62
63/* media_devnode to media_device */
64#define to_media_device(node) container_of(node, struct media_device, devnode)
65
66int __must_check media_device_register(struct media_device *mdev);
67void media_device_unregister(struct media_device *mdev);
68
69#endif
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-22 12:46:26 -0500