linux-omap 2.6.37: sync with OE .dev
[glsdk/meta-ti-glsdk.git] / recipes-bsp / linux / linux-omap / media / 0009-media-Media-device.patch
1 From 6bfbc237b86be01ad23b836ba047e76e23cc7a00 Mon Sep 17 00:00:00 2001
2 From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
3 Date: Wed, 9 Dec 2009 12:39:58 +0100
4 Subject: [PATCH 09/43] media: Media device
6 The media_device structure abstracts functions common to all kind of
7 media devices (v4l2, dvb, alsa, ...). It manages media entities and
8 offers a userspace API to discover and configure the media device
9 internal topology.
11 Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
12 ---
13  Documentation/ABI/testing/sysfs-bus-media      |    6 ++
14  Documentation/DocBook/media-entities.tmpl      |    2 +
15  Documentation/DocBook/media.tmpl               |    3 +
16  Documentation/DocBook/v4l/media-controller.xml |   56 +++++++++++++
17  Documentation/media-framework.txt              |   67 ++++++++++++++++
18  drivers/media/Makefile                         |    2 +-
19  drivers/media/media-device.c                   |  100 ++++++++++++++++++++++++
20  include/media/media-device.h                   |   69 ++++++++++++++++
21  8 files changed, 304 insertions(+), 1 deletions(-)
22  create mode 100644 Documentation/ABI/testing/sysfs-bus-media
23  create mode 100644 Documentation/DocBook/v4l/media-controller.xml
24  create mode 100644 Documentation/media-framework.txt
25  create mode 100644 drivers/media/media-device.c
26  create mode 100644 include/media/media-device.h
28 diff --git a/Documentation/ABI/testing/sysfs-bus-media b/Documentation/ABI/testing/sysfs-bus-media
29 new file mode 100644
30 index 0000000..7057e57
31 --- /dev/null
32 +++ b/Documentation/ABI/testing/sysfs-bus-media
33 @@ -0,0 +1,6 @@
34 +What:          /sys/bus/media/devices/.../model
35 +Date:          January 2011
36 +Contact:       Laurent Pinchart <laurent.pinchart@ideasonboard.com>
37 +               linux-media@vger.kernel.org
38 +Description:   Contains the device model name in UTF-8. The device version is
39 +               is not be appended to the model name.
40 diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
41 index be34dcb..61d6f11 100644
42 --- a/Documentation/DocBook/media-entities.tmpl
43 +++ b/Documentation/DocBook/media-entities.tmpl
44 @@ -321,6 +321,8 @@
45  <!ENTITY sub-media-entities SYSTEM "media-entities.tmpl">
46  <!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">
47  
48 +<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">
49 +
50  <!-- Function Reference -->
51  <!ENTITY close SYSTEM "v4l/func-close.xml">
52  <!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml">
53 diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl
54 index f11048d..73464b0 100644
55 --- a/Documentation/DocBook/media.tmpl
56 +++ b/Documentation/DocBook/media.tmpl
57 @@ -106,6 +106,9 @@ Foundation. A copy of the license is included in the chapter entitled
58  &sub-remote_controllers;
59  </chapter>
60  </part>
61 +<part id="media_common">
62 +&sub-media-controller;
63 +</part>
64  
65  &sub-fdl-appendix;
66  
67 diff --git a/Documentation/DocBook/v4l/media-controller.xml b/Documentation/DocBook/v4l/media-controller.xml
68 new file mode 100644
69 index 0000000..253ddb4
70 --- /dev/null
71 +++ b/Documentation/DocBook/v4l/media-controller.xml
72 @@ -0,0 +1,56 @@
73 +<partinfo>
74 +  <authorgroup>
75 +    <author>
76 +      <firstname>Laurent</firstname>
77 +      <surname>Pinchart</surname>
78 +      <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation>
79 +      <contrib>Initial version.</contrib>
80 +    </author>
81 +  </authorgroup>
82 +  <copyright>
83 +    <year>2010</year>
84 +    <holder>Laurent Pinchart</holder>
85 +  </copyright>
86 +
87 +  <revhistory>
88 +    <!-- Put document revisions here, newest first. -->
89 +    <revision>
90 +      <revnumber>1.0.0</revnumber>
91 +      <date>2010-11-10</date>
92 +      <authorinitials>lp</authorinitials>
93 +      <revremark>Initial revision</revremark>
94 +    </revision>
95 +  </revhistory>
96 +</partinfo>
97 +
98 +<title>Media Controller API</title>
99 +
100 +<chapter id="media_controller">
101 +  <title>Media Controller</title>
103 +  <section id="media-controller-intro">
104 +    <title>Introduction</title>
105 +    <para>Media devices increasingly handle multiple related functions. Many USB
106 +    cameras include microphones, video capture hardware can also output video,
107 +    or SoC camera interfaces also perform memory-to-memory operations similar to
108 +    video codecs.</para>
109 +    <para>Independent functions, even when implemented in the same hardware, can
110 +    be modelled as separate devices. A USB camera with a microphone will be
111 +    presented to userspace applications as V4L2 and ALSA capture devices. The
112 +    devices' relationships (when using a webcam, end-users shouldn't have to
113 +    manually select the associated USB microphone), while not made available
114 +    directly to applications by the drivers, can usually be retrieved from
115 +    sysfs.</para>
116 +    <para>With more and more advanced SoC devices being introduced, the current
117 +    approach will not scale. Device topologies are getting increasingly complex
118 +    and can't always be represented by a tree structure. Hardware blocks are
119 +    shared between different functions, creating dependencies between seemingly
120 +    unrelated devices.</para>
121 +    <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for
122 +    applications to access hardware parameters. As newer hardware expose an
123 +    increasingly high number of those parameters, drivers need to guess what
124 +    applications really require based on limited information, thereby
125 +    implementing policies that belong to userspace.</para>
126 +    <para>The media controller API aims at solving those problems.</para>
127 +  </section>
128 +</chapter>
129 diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt
130 new file mode 100644
131 index 0000000..1844c3f
132 --- /dev/null
133 +++ b/Documentation/media-framework.txt
134 @@ -0,0 +1,67 @@
135 +Linux kernel media framework
136 +============================
138 +This document describes the Linux kernel media framework, its data structures,
139 +functions and their usage.
142 +Introduction
143 +------------
145 +The media controller API is documented in DocBook format in
146 +Documentation/DocBook/v4l/media-controller.xml. This document will focus on
147 +the kernel-side implementation of the media framework.
150 +Media device
151 +------------
153 +A media device is represented by a struct media_device instance, defined in
154 +include/media/media-device.h. Allocation of the structure is handled by the
155 +media device driver, usually by embedding the media_device instance in a
156 +larger driver-specific structure.
158 +Drivers register media device instances by calling
160 +       media_device_register(struct media_device *mdev);
162 +The caller is responsible for initializing the media_device structure before
163 +registration. The following fields must be set:
165 + - dev must point to the parent device (usually a pci_dev, usb_interface or
166 +   platform_device instance).
168 + - model must be filled with the device model name as a NUL-terminated UTF-8
169 +   string. The device/model revision must not be stored in this field.
171 +The following fields are optional:
173 + - serial is a unique serial number stored as a NUL-terminated ASCII string.
174 +   The field is big enough to store a GUID in text form. If the hardware
175 +   doesn't provide a unique serial number this field must be left empty.
177 + - bus_info represents the location of the device in the system as a
178 +   NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to
179 +   "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices,
180 +   the usb_make_path() function must be used. This field is used by
181 +   applications to distinguish between otherwise identical devices that don't
182 +   provide a serial number.
184 + - hw_revision is the hardware device revision in a driver-specific format.
185 +   When possible the revision should be formatted with the KERNEL_VERSION
186 +   macro.
188 + - driver_version is formatted with the KERNEL_VERSION macro. The version
189 +   minor must be incremented when new features are added to the userspace API
190 +   without breaking binary compatibility. The version major must be
191 +   incremented when binary compatibility is broken.
193 +Upon successful registration a character device named media[0-9]+ is created.
194 +The device major and minor numbers are dynamic. The model name is exported as
195 +a sysfs attribute.
197 +Drivers unregister media device instances by calling
199 +       media_device_unregister(struct media_device *mdev);
201 +Unregistering a media device that hasn't been registered is *NOT* safe.
202 diff --git a/drivers/media/Makefile b/drivers/media/Makefile
203 index 3a08991..019d3e0 100644
204 --- a/drivers/media/Makefile
205 +++ b/drivers/media/Makefile
206 @@ -2,7 +2,7 @@
207  # Makefile for the kernel multimedia device drivers.
208  #
209  
210 -media-objs     := media-devnode.o
211 +media-objs     := media-device.o media-devnode.o
212  
213  ifeq ($(CONFIG_MEDIA_CONTROLLER),y)
214    obj-$(CONFIG_MEDIA_SUPPORT) += media.o
215 diff --git a/drivers/media/media-device.c b/drivers/media/media-device.c
216 new file mode 100644
217 index 0000000..57a9c6b
218 --- /dev/null
219 +++ b/drivers/media/media-device.c
220 @@ -0,0 +1,100 @@
221 +/*
222 + * Media device
223 + *
224 + * Copyright (C) 2010 Nokia Corporation
225 + *
226 + * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
227 + *          Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
228 + *
229 + * This program is free software; you can redistribute it and/or modify
230 + * it under the terms of the GNU General Public License version 2 as
231 + * published by the Free Software Foundation.
232 + *
233 + * This program is distributed in the hope that it will be useful,
234 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
235 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
236 + * GNU General Public License for more details.
237 + *
238 + * You should have received a copy of the GNU General Public License
239 + * along with this program; if not, write to the Free Software
240 + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
241 + */
243 +#include <linux/types.h>
244 +#include <linux/ioctl.h>
246 +#include <media/media-device.h>
247 +#include <media/media-devnode.h>
249 +static const struct media_file_operations media_device_fops = {
250 +       .owner = THIS_MODULE,
251 +};
253 +/* -----------------------------------------------------------------------------
254 + * sysfs
255 + */
257 +static ssize_t show_model(struct device *cd,
258 +                         struct device_attribute *attr, char *buf)
259 +{
260 +       struct media_device *mdev = to_media_device(to_media_devnode(cd));
262 +       return sprintf(buf, "%.*s\n", (int)sizeof(mdev->model), mdev->model);
263 +}
265 +static DEVICE_ATTR(model, S_IRUGO, show_model, NULL);
267 +/* -----------------------------------------------------------------------------
268 + * Registration/unregistration
269 + */
271 +static void media_device_release(struct media_devnode *mdev)
272 +{
273 +}
275 +/**
276 + * media_device_register - register a media device
277 + * @mdev:      The media device
278 + *
279 + * The caller is responsible for initializing the media device before
280 + * registration. The following fields must be set:
281 + *
282 + * - dev must point to the parent device
283 + * - model must be filled with the device model name
284 + */
285 +int __must_check media_device_register(struct media_device *mdev)
286 +{
287 +       int ret;
289 +       if (WARN_ON(mdev->dev == NULL || mdev->model[0] == 0))
290 +               return -EINVAL;
292 +       /* Register the device node. */
293 +       mdev->devnode.fops = &media_device_fops;
294 +       mdev->devnode.parent = mdev->dev;
295 +       mdev->devnode.release = media_device_release;
296 +       ret = media_devnode_register(&mdev->devnode);
297 +       if (ret < 0)
298 +               return ret;
300 +       ret = device_create_file(&mdev->devnode.dev, &dev_attr_model);
301 +       if (ret < 0) {
302 +               media_devnode_unregister(&mdev->devnode);
303 +               return ret;
304 +       }
306 +       return 0;
307 +}
308 +EXPORT_SYMBOL_GPL(media_device_register);
310 +/**
311 + * media_device_unregister - unregister a media device
312 + * @mdev:      The media device
313 + *
314 + */
315 +void media_device_unregister(struct media_device *mdev)
316 +{
317 +       device_remove_file(&mdev->devnode.dev, &dev_attr_model);
318 +       media_devnode_unregister(&mdev->devnode);
319 +}
320 +EXPORT_SYMBOL_GPL(media_device_unregister);
321 diff --git a/include/media/media-device.h b/include/media/media-device.h
322 new file mode 100644
323 index 0000000..e11f01a
324 --- /dev/null
325 +++ b/include/media/media-device.h
326 @@ -0,0 +1,69 @@
327 +/*
328 + * Media device
329 + *
330 + * Copyright (C) 2010 Nokia Corporation
331 + *
332 + * Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
333 + *          Sakari Ailus <sakari.ailus@maxwell.research.nokia.com>
334 + *
335 + * This program is free software; you can redistribute it and/or modify
336 + * it under the terms of the GNU General Public License version 2 as
337 + * published by the Free Software Foundation.
338 + *
339 + * This program is distributed in the hope that it will be useful,
340 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
341 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
342 + * GNU General Public License for more details.
343 + *
344 + * You should have received a copy of the GNU General Public License
345 + * along with this program; if not, write to the Free Software
346 + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
347 + */
349 +#ifndef _MEDIA_DEVICE_H
350 +#define _MEDIA_DEVICE_H
352 +#include <linux/device.h>
353 +#include <linux/list.h>
355 +#include <media/media-devnode.h>
357 +/**
358 + * struct media_device - Media device
359 + * @dev:       Parent device
360 + * @devnode:   Media device node
361 + * @model:     Device model name
362 + * @serial:    Device serial number (optional)
363 + * @bus_info:  Unique and stable device location identifier
364 + * @hw_revision: Hardware device revision
365 + * @driver_version: Device driver version
366 + *
367 + * This structure represents an abstract high-level media device. It allows easy
368 + * access to entities and provides basic media device-level support. The
369 + * structure can be allocated directly or embedded in a larger structure.
370 + *
371 + * The parent @dev is a physical device. It must be set before registering the
372 + * media device.
373 + *
374 + * @model is a descriptive model name exported through sysfs. It doesn't have to
375 + * be unique.
376 + */
377 +struct media_device {
378 +       /* dev->driver_data points to this struct. */
379 +       struct device *dev;
380 +       struct media_devnode devnode;
382 +       char model[32];
383 +       char serial[40];
384 +       char bus_info[32];
385 +       u32 hw_revision;
386 +       u32 driver_version;
387 +};
389 +/* media_devnode to media_device */
390 +#define to_media_device(node) container_of(node, struct media_device, devnode)
392 +int __must_check media_device_register(struct media_device *mdev);
393 +void media_device_unregister(struct media_device *mdev);
395 +#endif
396 -- 
397 1.6.6.1