aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/media-framework.txt
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart@ideasonboard.com>2009-12-09 06:39:58 -0500
committerMauro Carvalho Chehab <mchehab@redhat.com>2011-03-22 03:53:09 -0400
commit176fb0d108f7495ccf9aa127e1342a1a0d87e004 (patch)
treea1b54ad186dde663853d4d2d24f42cd7c0f94bfb /Documentation/media-framework.txt
parentcf4b9211b5680cd9ca004232e517fb7ec5bf5316 (diff)
[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>
Diffstat (limited to 'Documentation/media-framework.txt')
-rw-r--r--Documentation/media-framework.txt67
1 files changed, 67 insertions, 0 deletions
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.