Mauro Carvalho Chehab | eda6bc2 | 2015-06-02 07:40:53 -0300 | [diff] [blame] | 1 | <?xml version="1.0" encoding="UTF-8"?> |
Mauro Carvalho Chehab | 96048dc | 2015-06-02 08:36:36 -0300 | [diff] [blame] | 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ |
Mauro Carvalho Chehab | d80bd70 | 2009-09-15 15:27:57 -0300 | [diff] [blame] | 4 | <!ENTITY % media-entities SYSTEM "./media-entities.tmpl"> %media-entities; |
| 5 | <!ENTITY media-indices SYSTEM "./media-indices.tmpl"> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 6 | |
| 7 | <!ENTITY eg "e. g."> |
| 8 | <!ENTITY ie "i. e."> |
| 9 | <!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>."> |
Mauro Carvalho Chehab | c130d88 | 2015-05-26 09:03:55 -0300 | [diff] [blame] | 10 | <!ENTITY fe_fd "File descriptor returned by <link linkend='frontend_f_open'><function>open()</function></link>."> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 11 | <!ENTITY i2c "I<superscript>2</superscript>C"> |
Mauro Carvalho Chehab | 6d17249 | 2011-07-05 10:07:37 -0300 | [diff] [blame] | 12 | <!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>"> |
Mauro Carvalho Chehab | 3de530f | 2011-07-05 12:36:01 -0300 | [diff] [blame] | 13 | <!ENTITY return-value-dvb "<para>RETURN VALUE</para><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately. The generic error codes are described at the <link linkend='gen-errors'>Generic Error Codes</link> chapter.</para>"> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 14 | <!ENTITY manvol "<manvolnum>2</manvolnum>"> |
| 15 | |
| 16 | <!-- Table templates: structs, structs w/union, defines. --> |
| 17 | <!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> |
| 18 | <!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />"> |
| 19 | <!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> |
| 20 | |
| 21 | <!-- Video for Linux mailing list address. --> |
| 22 | <!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>"> |
| 23 | |
| 24 | <!-- LinuxTV v4l-dvb repository. --> |
| 25 | <!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>"> |
Laurent Pinchart | f57fa21 | 2013-06-05 04:19:53 -0300 | [diff] [blame] | 26 | <!ENTITY dash-ent-8 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
Sylwester Nawrocki | b01189b | 2012-11-28 14:40:32 -0300 | [diff] [blame] | 27 | <!ENTITY dash-ent-10 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
Laurent Pinchart | f57fa21 | 2013-06-05 04:19:53 -0300 | [diff] [blame] | 28 | <!ENTITY dash-ent-12 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
| 29 | <!ENTITY dash-ent-14 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
Phil Edworthy | 7b88fc0 | 2013-03-18 08:47:59 -0300 | [diff] [blame] | 30 | <!ENTITY dash-ent-16 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
Laurent Pinchart | f57fa21 | 2013-06-05 04:19:53 -0300 | [diff] [blame] | 31 | <!ENTITY dash-ent-20 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
| 32 | <!ENTITY dash-ent-22 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
| 33 | <!ENTITY dash-ent-24 "<entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry><entry>-</entry>"> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 34 | ]> |
| 35 | |
Mauro Carvalho Chehab | eda6bc2 | 2015-06-02 07:40:53 -0300 | [diff] [blame] | 36 | <book id="media_api" lang="en"> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 37 | <bookinfo> |
Mauro Carvalho Chehab | 90f745c | 2014-02-06 10:55:28 -0200 | [diff] [blame] | 38 | <title>LINUX MEDIA INFRASTRUCTURE API</title> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 39 | |
Mauro Carvalho Chehab | 90f745c | 2014-02-06 10:55:28 -0200 | [diff] [blame] | 40 | <copyright> |
Hans Verkuil | eab2b76 | 2015-10-16 06:13:01 -0300 | [diff] [blame^] | 41 | <year>2009-2015</year> |
Mauro Carvalho Chehab | 90f745c | 2014-02-06 10:55:28 -0200 | [diff] [blame] | 42 | <holder>LinuxTV Developers</holder> |
| 43 | </copyright> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 44 | |
Mauro Carvalho Chehab | 90f745c | 2014-02-06 10:55:28 -0200 | [diff] [blame] | 45 | <legalnotice> |
| 46 | <para>Permission is granted to copy, distribute and/or modify |
| 47 | this document under the terms of the GNU Free Documentation License, |
| 48 | Version 1.1 or any later version published by the Free Software |
| 49 | Foundation. A copy of the license is included in the chapter entitled |
| 50 | "GNU Free Documentation License"</para> |
| 51 | </legalnotice> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 52 | </bookinfo> |
| 53 | |
| 54 | <toc></toc> <!-- autogenerated --> |
| 55 | |
| 56 | <preface> |
| 57 | <title>Introduction</title> |
| 58 | |
| 59 | <para>This document covers the Linux Kernel to Userspace API's used by |
Hans Verkuil | 1b96208 | 2014-01-07 06:46:37 -0300 | [diff] [blame] | 60 | video and radio streaming devices, including video cameras, |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 61 | analog and digital TV receiver cards, AM/FM receiver cards, |
Hans Verkuil | 1b96208 | 2014-01-07 06:46:37 -0300 | [diff] [blame] | 62 | streaming capture and output devices, codec devices and remote |
| 63 | controllers.</para> |
Mauro Carvalho Chehab | a1ef3ee | 2015-05-25 13:40:28 -0300 | [diff] [blame] | 64 | <para>A typical media device hardware is shown at |
| 65 | <xref linkend="typical_media_device" />.</para> |
| 66 | <figure id="typical_media_device"> |
| 67 | <title>Typical Media Device</title> |
| 68 | <mediaobject> |
| 69 | <imageobject> |
| 70 | <imagedata fileref="typical_media_device.svg" format="SVG" /> |
| 71 | </imageobject> |
| 72 | <textobject> |
| 73 | <phrase>Typical Media Device Block Diagram</phrase> |
| 74 | </textobject> |
| 75 | </mediaobject> |
| 76 | </figure> |
| 77 | <para>The media infrastructure API was designed to control such |
| 78 | devices. It is divided into four parts.</para> |
Hans Verkuil | 1b96208 | 2014-01-07 06:46:37 -0300 | [diff] [blame] | 79 | <para>The first part covers radio, video capture and output, |
| 80 | cameras, analog TV devices and codecs.</para> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 81 | <para>The second part covers the |
| 82 | API used for digital TV and Internet reception via one of the |
| 83 | several digital tv standards. While it is called as DVB API, |
| 84 | in fact it covers several different video standards including |
Mauro Carvalho Chehab | 39b9ce2 | 2015-05-25 13:38:01 -0300 | [diff] [blame] | 85 | DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S,etc. The complete |
| 86 | list of supported standards can be found at |
| 87 | <xref linkend="fe-delivery-system-t" />.</para> |
Hans Verkuil | 571d19c | 2012-08-09 06:04:43 -0300 | [diff] [blame] | 88 | <para>The third part covers the Remote Controller API.</para> |
| 89 | <para>The fourth part covers the Media Controller API.</para> |
Mauro Carvalho Chehab | 7832a91 | 2015-06-02 14:59:07 -0300 | [diff] [blame] | 90 | <para>It should also be noted that a media device may also have audio |
| 91 | components, like mixers, PCM capture, PCM playback, etc, which |
Mauro Carvalho Chehab | 9f67bc5 | 2015-05-25 13:39:48 -0300 | [diff] [blame] | 92 | are controlled via ALSA API.</para> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 93 | <para>For additional information and for the latest development code, |
| 94 | see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> |
| 95 | <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 96 | </preface> |
| 97 | |
Mauro Carvalho Chehab | 315d27a | 2015-06-01 08:56:49 -0300 | [diff] [blame] | 98 | <part id="v4l2spec"> |
| 99 | &sub-v4l2; |
| 100 | </part> |
| 101 | <part id="dvbapi"> |
| 102 | &sub-dvbapi; |
| 103 | </part> |
| 104 | <part id="remotes"> |
| 105 | &sub-remote_controllers; |
| 106 | </part> |
| 107 | <part id="media_common"> |
| 108 | &sub-media-controller; |
| 109 | </part> |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 110 | |
Mauro Carvalho Chehab | 315d27a | 2015-06-01 08:56:49 -0300 | [diff] [blame] | 111 | <chapter id="gen_errors"> |
| 112 | &sub-gen-errors; |
| 113 | </chapter> |
Mauro Carvalho Chehab | 6d17249 | 2011-07-05 10:07:37 -0300 | [diff] [blame] | 114 | |
Mauro Carvalho Chehab | 8e080c2 | 2009-09-13 22:16:04 -0300 | [diff] [blame] | 115 | &sub-fdl-appendix; |
| 116 | |
| 117 | </book> |