diff options
author | Mauro Carvalho Chehab <mchehab@redhat.com> | 2010-07-04 15:57:50 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2010-07-04 15:57:50 -0300 |
commit | 011906dc794530a0f2a86dd5a6e4caff19200a3d (patch) | |
tree | dc793a474209e95049c2408fd657a6cccaa3fdc6 /Documentation/DocBook | |
parent | 432aa033bda81fbc11d623dd42db9fe51204279b (diff) | |
parent | 056f405ac124849ddf488ccda62695bd257fea59 (diff) |
Merge branch 'staging/rc' into staging/all
* staging/rc: (23 commits)
DocBook/media: Add LIRC DocBook to media.html
V4L/DVB: IR/lirc: add docbook info covering lirc device interface
V4L/DVB: IR: add empty lirc pseudo-keymap
V4L/DVB: IR: add ir-core to lirc userspace decoder bridge driver
V4L/DVB: IR: add lirc device interface
V4L/DVB: IR/mceusb: add tx callback functions and wire up
V4L/DVB: IR: add tx callbacks to ir-core
V4L/DVB: IR/mceusb: kill pinnacle-device-specific nonsense
V4L/DVB: IR/mceusb: misc cleanups and init fixes
V4L/DVB: IR/mceusb: use the proper ir-core device unregister function
V4L/DVB: IR/imon: use the proper ir-core device unregister function
V4L/DVB: [-next] media/IR: nec-decoder needs to select BITREV
V4L/DVB: ir-core: move decoding state to ir_raw_event_ctrl
ir-core: allow specifying multiple protocols at one open/write
ir-core: Add support for disabling all protocols
ir-core: Rename sysfs protocols nomenclature to rc-5 and rc-6
ir-core: Remove magic numbers at the sysfs logic
V4L/DVB: ir-core: centralize sysfs raw decoder enabling/disabling
V4L/DVB: ir-core: partially convert ir-kbd-i2c.c to not use ir-functions.c
V4L/DVB: ir-core: partially convert cx88 to not use ir-functions.c
...
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/media-entities.tmpl | 1 | ||||
-rw-r--r-- | Documentation/DocBook/media.tmpl | 4 | ||||
-rw-r--r-- | Documentation/DocBook/v4l/lirc_device_interface.xml | 235 | ||||
-rw-r--r-- | Documentation/DocBook/v4l/remote_controllers.xml | 2 |
4 files changed, 240 insertions, 2 deletions
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 fe10bd7721f2..f11048d4053f 100644 --- a/Documentation/DocBook/media.tmpl +++ b/Documentation/DocBook/media.tmpl @@ -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> @@ -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; |