Commit | Line | Data |
---|---|---|
176fb0d1 LP |
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> | |
53e269c1 LP |
56 | |
57 | <section id="media-controller-model"> | |
58 | <title>Media device model</title> | |
59 | <para>Discovering a device internal topology, and configuring it at runtime, | |
60 | is one of the goals of the media controller API. To achieve this, hardware | |
61 | devices are modelled as an oriented graph of building blocks called entities | |
62 | connected through pads.</para> | |
63 | <para>An entity is a basic media hardware or software building block. It can | |
64 | correspond to a large variety of logical blocks such as physical hardware | |
65 | devices (CMOS sensor for instance), logical hardware devices (a building | |
66 | block in a System-on-Chip image processing pipeline), DMA channels or | |
67 | physical connectors.</para> | |
68 | <para>A pad is a connection endpoint through which an entity can interact | |
69 | with other entities. Data (not restricted to video) produced by an entity | |
70 | flows from the entity's output to one or more entity inputs. Pads should not | |
71 | be confused with physical pins at chip boundaries.</para> | |
72 | <para>A link is a point-to-point oriented connection between two pads, | |
73 | either on the same entity or on different entities. Data flows from a source | |
74 | pad to a sink pad.</para> | |
75 | </section> | |
176fb0d1 | 76 | </chapter> |
140d8816 LP |
77 | |
78 | <appendix id="media-user-func"> | |
79 | <title>Function Reference</title> | |
80 | <!-- Keep this alphabetically sorted. --> | |
81 | &sub-media-open; | |
82 | &sub-media-close; | |
83 | &sub-media-ioctl; | |
84 | <!-- All ioctls go here. --> | |
85 | &sub-media-ioc-device-info; | |
86 | </appendix> |