Laurent Pinchart | 176fb0d | 2009-12-09 08:39:58 -0300 | [diff] [blame] | 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> |
Laurent Pinchart | 53e269c | 2009-12-09 08:40:00 -0300 | [diff] [blame] | 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> |
Laurent Pinchart | 176fb0d | 2009-12-09 08:39:58 -0300 | [diff] [blame] | 76 | </chapter> |
Laurent Pinchart | 140d881 | 2010-08-18 11:41:22 -0300 | [diff] [blame] | 77 | |
| 78 | <appendix id="media-user-func"> |
| 79 | <title>Function Reference</title> |
| 80 | <!-- Keep this alphabetically sorted. --> |
Mauro Carvalho Chehab | cca4acc | 2011-05-25 10:56:58 -0300 | [diff] [blame] | 81 | &sub-media-func-open; |
| 82 | &sub-media-func-close; |
| 83 | &sub-media-func-ioctl; |
Laurent Pinchart | 140d881 | 2010-08-18 11:41:22 -0300 | [diff] [blame] | 84 | <!-- All ioctls go here. --> |
| 85 | &sub-media-ioc-device-info; |
Laurent Pinchart | 1651333 | 2009-12-09 08:40:01 -0300 | [diff] [blame] | 86 | &sub-media-ioc-enum-entities; |
| 87 | &sub-media-ioc-enum-links; |
Laurent Pinchart | 97548ed | 2009-12-09 08:40:03 -0300 | [diff] [blame] | 88 | &sub-media-ioc-setup-link; |
Laurent Pinchart | 140d881 | 2010-08-18 11:41:22 -0300 | [diff] [blame] | 89 | </appendix> |