summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/dvb/dvbapi.xml19
-rw-r--r--Documentation/DocBook/dvb/frontend.h.xml1
-rw-r--r--Documentation/DocBook/dvb/frontend.xml10
-rw-r--r--Documentation/DocBook/media-entities.tmpl1
-rw-r--r--Documentation/DocBook/media.tmpl8
-rw-r--r--Documentation/DocBook/v4l/lirc_device_interface.xml235
-rw-r--r--Documentation/DocBook/v4l/remote_controllers.xml2
7 files changed, 267 insertions, 9 deletions
diff --git a/Documentation/DocBook/dvb/dvbapi.xml b/Documentation/DocBook/dvb/dvbapi.xml
index 63c528fee624..e3a97fdd62a6 100644
--- a/Documentation/DocBook/dvb/dvbapi.xml
+++ b/Documentation/DocBook/dvb/dvbapi.xml
@@ -12,10 +12,12 @@
<othername role="mi">O. C.</othername>
<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
</author>
+</authorgroup>
+<authorgroup>
<author>
<firstname>Mauro</firstname>
-<surname>Chehab</surname>
<othername role="mi">Carvalho</othername>
+<surname>Chehab</surname>
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
<contrib>Ported document to Docbook XML.</contrib>
</author>
@@ -23,13 +25,24 @@
<copyright>
<year>2002</year>
<year>2003</year>
- <year>2009</year>
<holder>Convergence GmbH</holder>
</copyright>
+<copyright>
+ <year>2009-2010</year>
+ <holder>Mauro Carvalho Chehab</holder>
+</copyright>
<revhistory>
<!-- Put document revisions here, newest first. -->
<revision>
+ <revnumber>2.0.3</revnumber>
+ <date>2010-07-03</date>
+ <authorinitials>mcc</authorinitials>
+ <revremark>
+ Add some frontend capabilities flags, present on kernel, but missing at the specs.
+ </revremark>
+</revision>
+<revision>
<revnumber>2.0.2</revnumber>
<date>2009-10-25</date>
<authorinitials>mcc</authorinitials>
@@ -63,7 +76,7 @@ Added ISDB-T test originally written by Patrick Boettcher
<title>LINUX DVB API</title>
-<subtitle>Version 3</subtitle>
+<subtitle>Version 5.2</subtitle>
<!-- ADD THE CHAPTERS HERE -->
<chapter id="dvb_introdution">
&sub-intro;
diff --git a/Documentation/DocBook/dvb/frontend.h.xml b/Documentation/DocBook/dvb/frontend.h.xml
index b99644f5340a..d08e0d401418 100644
--- a/Documentation/DocBook/dvb/frontend.h.xml
+++ b/Documentation/DocBook/dvb/frontend.h.xml
@@ -63,6 +63,7 @@ typedef enum fe_caps {
FE_CAN_8VSB = 0x200000,
FE_CAN_16VSB = 0x400000,
FE_HAS_EXTENDED_CAPS = 0x800000, /* We need more bitspace for newer APIs, indicate this. */
+ FE_CAN_TURBO_FEC = 0x8000000, /* frontend supports "turbo fec modulation" */
FE_CAN_2G_MODULATION = 0x10000000, /* frontend supports "2nd generation modulation" (DVB-S2) */
FE_NEEDS_BENDING = 0x20000000, /* not supported anymore, don't use (frontend requires frequency bending) */
FE_CAN_RECOVER = 0x40000000, /* frontend can recover from a cable unplug automatically */
diff --git a/Documentation/DocBook/dvb/frontend.xml b/Documentation/DocBook/dvb/frontend.xml
index 300ba1f04177..78d756de5906 100644
--- a/Documentation/DocBook/dvb/frontend.xml
+++ b/Documentation/DocBook/dvb/frontend.xml
@@ -64,8 +64,14 @@ a specific frontend type.</para>
FE_CAN_BANDWIDTH_AUTO = 0x40000,
FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
FE_CAN_HIERARCHY_AUTO = 0x100000,
- FE_CAN_MUTE_TS = 0x80000000,
- FE_CAN_CLEAN_SETUP = 0x40000000
+ FE_CAN_8VSB = 0x200000,
+ FE_CAN_16VSB = 0x400000,
+ FE_HAS_EXTENDED_CAPS = 0x800000,
+ FE_CAN_TURBO_FEC = 0x8000000,
+ FE_CAN_2G_MODULATION = 0x10000000,
+ FE_NEEDS_BENDING = 0x20000000,
+ FE_CAN_RECOVER = 0x40000000,
+ FE_CAN_MUTE_TS = 0x80000000
} fe_caps_t;
</programlisting>
</section>
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index 5d4d40f429a5..6ae97157b1c7 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -218,6 +218,7 @@
<!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml">
<!ENTITY sub-driver SYSTEM "v4l/driver.xml">
<!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml">
+<!ENTITY sub-lirc_device_interface SYSTEM "v4l/lirc_device_interface.xml">
<!ENTITY sub-remote_controllers SYSTEM "v4l/remote_controllers.xml">
<!ENTITY sub-fdl-appendix SYSTEM "v4l/fdl-appendix.xml">
<!ENTITY sub-close SYSTEM "v4l/func-close.xml">
diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl
index eea564bb12cb..f11048d4053f 100644
--- a/Documentation/DocBook/media.tmpl
+++ b/Documentation/DocBook/media.tmpl
@@ -28,7 +28,7 @@
<title>LINUX MEDIA INFRASTRUCTURE API</title>
<copyright>
- <year>2009</year>
+ <year>2009-2010</year>
<holder>LinuxTV Developers</holder>
</copyright>
@@ -61,7 +61,7 @@ Foundation. A copy of the license is included in the chapter entitled
in fact it covers several different video standards including
DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated
to documment support also for DVB-S2, ISDB-T and ISDB-S.</para>
- <para>The third part covers other API's used by all media infrastructure devices</para>
+ <para>The third part covers Remote Controller API</para>
<para>For additional information and for the latest development code,
see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
<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>
@@ -86,7 +86,7 @@ Foundation. A copy of the license is included in the chapter entitled
</author>
</authorgroup>
<copyright>
- <year>2009</year>
+ <year>2009-2010</year>
<holder>Mauro Carvalho Chehab</holder>
</copyright>
@@ -101,7 +101,7 @@ Foundation. A copy of the license is included in the chapter entitled
</revhistory>
</partinfo>
-<title>Other API's used by media infrastructure drivers</title>
+<title>Remote Controller API</title>
<chapter id="remote_controllers">
&sub-remote_controllers;
</chapter>
diff --git a/Documentation/DocBook/v4l/lirc_device_interface.xml b/Documentation/DocBook/v4l/lirc_device_interface.xml
new file mode 100644
index 000000000000..0413234023d4
--- /dev/null
+++ b/Documentation/DocBook/v4l/lirc_device_interface.xml
@@ -0,0 +1,235 @@
+<section id="lirc_dev">
+<title>LIRC Device Interface</title>
+
+
+<section id="lirc_dev_intro">
+<title>Introduction</title>
+
+<para>The LIRC device interface is a bi-directional interface for
+transporting raw IR data between userspace and kernelspace. Fundamentally,
+it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number
+of standard struct file_operations defined on it. With respect to
+transporting raw IR data to and fro, the essential fops are read, write
+and ioctl.</para>
+
+<para>Example dmesg output upon a driver registering w/LIRC:</para>
+ <blockquote>
+ <para>$ dmesg |grep lirc_dev</para>
+ <para>lirc_dev: IR Remote Control driver registered, major 248</para>
+ <para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para>
+ </blockquote>
+
+<para>What you should see for a chardev:</para>
+ <blockquote>
+ <para>$ ls -l /dev/lirc*</para>
+ <para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para>
+ </blockquote>
+</section>
+
+<section id="lirc_read">
+<title>LIRC read fop</title>
+
+<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The
+exact format of the data depends on what modes a driver supports, and what
+mode has been selected. lircd obtains supported modes and sets the active mode
+via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally
+preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
+describing an IR signal are read from the chardev.</para>
+
+<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para>
+</section>
+
+<section id="lirc_write">
+<title>LIRC write fop</title>
+
+<para>The data written to the chardev is a pulse/space sequence of integer
+values. Pulses and spaces are only marked implicitly by their position. The
+data must start and end with a pulse, therefore, the data must always include
+an unevent number of samples. The write function must block until the data has
+been transmitted by the hardware.</para>
+</section>
+
+<section id="lirc_ioctl">
+<title>LIRC ioctl fop</title>
+
+<para>The LIRC device's ioctl definition is bound by the ioctl function
+definition of struct file_operations, leaving us with an unsigned int
+for the ioctl command and an unsigned long for the arg. For the purposes
+of ioctl portability across 32-bit and 64-bit, these values are capped
+to their 32-bit sizes.</para>
+
+<para>The following ioctls can be used to change specific hardware settings.
+In general each driver should have a default set of settings. The driver
+implementation is expected to re-apply the default settings when the device
+is closed by user-space, so that every application opening the device can rely
+on working with the default settings initially.</para>
+
+<variablelist>
+ <varlistentry>
+ <term>LIRC_GET_FEATURES</term>
+ <listitem>
+ <para>Obviously, get the underlying hardware device's features. If a driver
+ does not announce support of certain features, calling of the corresponding
+ ioctls is undefined.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_SEND_MODE</term>
+ <listitem>
+ <para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_REC_MODE</term>
+ <listitem>
+ <para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE
+ are supported by lircd.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_SEND_CARRIER</term>
+ <listitem>
+ <para>Get carrier frequency (in Hz) currently used for transmit.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_REC_CARRIER</term>
+ <listitem>
+ <para>Get carrier frequency (in Hz) currently used for IR reception.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term>
+ <listitem>
+ <para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently,
+ no special meaning is defined for 0 or 100, but this could be used to switch
+ off carrier generation in the future, so these values should be reserved.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_REC_RESOLUTION</term>
+ <listitem>
+ <para>Some receiver have maximum resolution which is defined by internal
+ sample rate or data format limitations. E.g. it's common that signals can
+ only be reported in 50 microsecond steps. This integer value is used by
+ lircd to automatically adjust the aeps tolerance value in the lircd
+ config file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_M{IN,AX}_TIMEOUT</term>
+ <listitem>
+ <para>Some devices have internal timers that can be used to detect when
+ there's no IR activity for a long time. This can help lircd in detecting
+ that a IR signal is finished and can speed up the decoding process.
+ Returns an integer value with the minimum/maximum timeout that can be
+ set. Some devices have a fixed timeout, in that case both ioctls will
+ return the same value even though the timeout cannot be changed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term>
+ <listitem>
+ <para>Some devices are able to filter out spikes in the incoming signal
+ using given filter rules. These ioctls return the hardware capabilities
+ that describe the bounds of the possible filters. Filter settings depend
+ on the IR protocols that are expected. lircd derives the settings from
+ all protocols definitions found in its config file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_GET_LENGTH</term>
+ <listitem>
+ <para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
+ Reads on the device must be done in blocks matching the bit count.
+ The bit could should be rounded up so that it matches full bytes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_{SEND,REC}_MODE</term>
+ <listitem>
+ <para>Set send/receive mode. Largely obsolete for send, as only
+ LIRC_MODE_PULSE is supported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_{SEND,REC}_CARRIER</term>
+ <listitem>
+ <para>Set send/receive carrier (in Hz).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_TRANSMITTER_MASK</term>
+ <listitem>
+ <para>This enables the given set of transmitters. The first transmitter
+ is encoded by the least significant bit, etc. When an invalid bit mask
+ is given, i.e. a bit is set, even though the device does not have so many
+ transitters, then this ioctl returns the number of available transitters
+ and does nothing otherwise.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_REC_TIMEOUT</term>
+ <listitem>
+ <para>Sets the integer value for IR inactivity timeout (cf.
+ LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if
+ supported by the hardware) disables all hardware timeouts and data should
+ be reported as soon as possible. If the exact value cannot be set, then
+ the next possible value _greater_ than the given value should be set.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_REC_TIMEOUT_REPORTS</term>
+ <listitem>
+ <para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
+ default, timeout reports should be turned off.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term>
+ <listitem>
+ <para>Pulses/spaces shorter than this are filtered out by hardware. If
+ filters cannot be set independently for pulse/space, the corresponding
+ ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_MEASURE_CARRIER_MODE</term>
+ <listitem>
+ <para>Enable (1)/disable (0) measure mode. If enabled, from the next key
+ press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default
+ this should be turned off.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term>
+ <listitem>
+ <para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
+ with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER
+ with the upper bound.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_NOTIFY_DECODE</term>
+ <listitem>
+ <para>This ioctl is called by lircd whenever a successful decoding of an
+ incoming IR signal could be done. This can be used by supporting hardware
+ to give visual feedback to the user e.g. by flashing a LED.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LIRC_SETUP_{START,END}</term>
+ <listitem>
+ <para>Setting of several driver parameters can be optimized by encapsulating
+ the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a
+ driver receives a LIRC_SETUP_START ioctl it can choose to not commit
+ further setting changes to the hardware until a LIRC_SETUP_END is received.
+ But this is open to the driver implementation and every driver must also
+ handle parameter changes which are not encapsulated by LIRC_SETUP_START
+ and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</section>
+</section>
diff --git a/Documentation/DocBook/v4l/remote_controllers.xml b/Documentation/DocBook/v4l/remote_controllers.xml
index 73f5eab091f4..3c3b667b28e7 100644
--- a/Documentation/DocBook/v4l/remote_controllers.xml
+++ b/Documentation/DocBook/v4l/remote_controllers.xml
@@ -173,3 +173,5 @@ keymapping.</para>
<para>This program demonstrates how to replace the keymap tables.</para>
&sub-keytable-c;
</section>
+
+&sub-lirc_device_interface;
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-18 17:25:39 +0100