summaryrefslogtreecommitdiffstats
path: root/Documentation/media
diff options
context:
space:
mode:
authorSean Young <sean@mess.org>2017-02-08 15:10:30 -0200
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2017-03-24 07:43:26 -0300
commita8b875a54990415603d180e0c4bf31ce7d876c3a (patch)
treee6b16f3599365e27af8ed8d33eca973baaea3285 /Documentation/media
parent5cd6522c5b1df51f22f3b83f5548989a64ab44f5 (diff)
downloadlinux-a8b875a54990415603d180e0c4bf31ce7d876c3a.tar.bz2
[media] lirc: document lirc modes better
LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE were not covered at all. Signed-off-by: Sean Young <sean@mess.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media')
-rw-r--r--Documentation/media/lirc.h.rst.exceptions1
-rw-r--r--Documentation/media/uapi/rc/lirc-dev-intro.rst53
-rw-r--r--Documentation/media/uapi/rc/lirc-get-features.rst13
-rw-r--r--Documentation/media/uapi/rc/lirc-get-length.rst3
-rw-r--r--Documentation/media/uapi/rc/lirc-get-rec-mode.rst4
-rw-r--r--Documentation/media/uapi/rc/lirc-get-send-mode.rst7
-rw-r--r--Documentation/media/uapi/rc/lirc-read.rst16
-rw-r--r--Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst2
-rw-r--r--Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst2
-rw-r--r--Documentation/media/uapi/rc/lirc-write.rst17
10 files changed, 82 insertions, 36 deletions
diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions
index 246c850151d7..c130617a9986 100644
--- a/Documentation/media/lirc.h.rst.exceptions
+++ b/Documentation/media/lirc.h.rst.exceptions
@@ -35,7 +35,6 @@ ignore define PULSE_MASK
ignore define LIRC_MODE2_SPACE
ignore define LIRC_MODE2_PULSE
-ignore define LIRC_MODE2_TIMEOUT
ignore define LIRC_VALUE_MASK
ignore define LIRC_MODE2_MASK
diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst
index ef97e40f2fd8..d1936eeb9ce0 100644
--- a/Documentation/media/uapi/rc/lirc-dev-intro.rst
+++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst
@@ -27,6 +27,8 @@ What you should see for a chardev:
$ ls -l /dev/lirc*
crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
+.. _lirc_modes:
+
**********
LIRC modes
**********
@@ -38,25 +40,62 @@ on the following table.
``LIRC_MODE_MODE2``
- The driver returns a sequence of pulse and space codes to userspace.
+ The driver returns a sequence of pulse and space codes to userspace,
+ as a series of u32 values.
This mode is used only for IR receive.
+ The upper 8 bits determine the packet type, and the lower 24 bits
+ the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
+ the macro ``LIRC_MODE2()`` will give you the type, which
+ is one of:
+
+ ``LIRC_MODE2_PULSE``
+
+ Signifies the presence of IR in microseconds.
+
+ ``LIRC_MODE2_SPACE``
+
+ Signifies absence of IR in microseconds.
+
+ ``LIRC_MODE2_FREQUENCY``
+
+ If measurement of the carrier frequency was enabled with
+ :ref:`lirc_set_measure_carrier_mode` then this packet gives you
+ the carrier frequency in Hertz.
+
+ ``LIRC_MODE2_TIMEOUT``
+
+ If timeout reports are enabled with
+ :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
+ :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
+ this packet will be sent, with the number of microseconds with
+ no IR.
+
.. _lirc-mode-lirccode:
``LIRC_MODE_LIRCCODE``
- The IR signal is decoded internally by the receiver. The LIRC interface
- returns the scancode as an integer value. This is the usual mode used
- by several TV media cards.
+ This mode can be used for IR receive and send.
- This mode is used only for IR receive.
+ The IR signal is decoded internally by the receiver, or encoded by the
+ transmitter. The LIRC interface represents the scancode as byte string,
+ which might not be a u32, it can be any length. The value is entirely
+ driver dependent. This mode is used by some older lirc drivers.
+
+ The length of each code depends on the driver, which can be retrieved
+ with :ref:`lirc_get_length`. This length is used both
+ for transmitting and receiving IR.
.. _lirc-mode-pulse:
``LIRC_MODE_PULSE``
- On puse mode, a sequence of pulse/space integer values are written to the
- lirc device using :Ref:`lirc-write`.
+ In pulse mode, a sequence of pulse/space integer values are written to the
+ lirc device using :ref:`lirc-write`.
+
+ The values are alternating pulse and space lengths, in microseconds. The
+ first and last entry must be a pulse, so there must be an odd number
+ of entries.
This mode is used only for IR send.
diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst
index 79e07b4d44d6..64f89a4f9d9c 100644
--- a/Documentation/media/uapi/rc/lirc-get-features.rst
+++ b/Documentation/media/uapi/rc/lirc-get-features.rst
@@ -48,8 +48,8 @@ LIRC features
``LIRC_CAN_REC_PULSE``
- The driver is capable of receiving using
- :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`.
+ Unused. Kept just to avoid breaking uAPI.
+ :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` can only be used for transmitting.
.. _LIRC-CAN-REC-MODE2:
@@ -156,19 +156,22 @@ LIRC features
``LIRC_CAN_SEND_PULSE``
- The driver supports sending using :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`.
+ The driver supports sending (also called as IR blasting or IR TX) using
+ :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`.
.. _LIRC-CAN-SEND-MODE2:
``LIRC_CAN_SEND_MODE2``
- The driver supports sending using :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`.
+ Unused. Kept just to avoid breaking uAPI.
+ :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` can only be used for receiving.
.. _LIRC-CAN-SEND-LIRCCODE:
``LIRC_CAN_SEND_LIRCCODE``
- The driver supports sending codes (also called as IR blasting or IR TX).
+ The driver supports sending (also called as IR blasting or IR TX) using
+ :ref:`LIRC_MODE_LIRCCODE <lirc-mode-LIRCCODE>`.
Return Value
diff --git a/Documentation/media/uapi/rc/lirc-get-length.rst b/Documentation/media/uapi/rc/lirc-get-length.rst
index 8c2747c8d2c9..3990af5de0e9 100644
--- a/Documentation/media/uapi/rc/lirc-get-length.rst
+++ b/Documentation/media/uapi/rc/lirc-get-length.rst
@@ -30,7 +30,8 @@ Arguments
Description
===========
-Retrieves the code length in bits (only for ``LIRC-MODE-LIRCCODE``).
+Retrieves the code length in bits (only for
+:ref:`LIRC_MODE_LIRCCODE <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.
diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst
index a5023e0194c1..a4eb6c0a26e9 100644
--- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst
+++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst
@@ -35,8 +35,8 @@ Description
Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
and :ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` are supported for IR
-receive.
-
+receive. Use :ref:`lirc_get_features` to find out which modes the driver
+supports.
Return Value
============
diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst
index 51ac13428969..a169b234290e 100644
--- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst
+++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst
@@ -34,9 +34,12 @@ Arguments
Description
===========
-Get/set supported transmit mode.
+Get/set current transmit mode.
-Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` is supported by for IR send.
+Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` and
+:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` is supported by for IR send,
+depending on the driver. Use :ref:`lirc_get_features` to find out which
+modes the driver supports.
Return Value
============
diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst
index 4c678f60e872..ff14a69104e5 100644
--- a/Documentation/media/uapi/rc/lirc-read.rst
+++ b/Documentation/media/uapi/rc/lirc-read.rst
@@ -44,17 +44,13 @@ descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero,
:ref:`read() <lirc-read>` returns zero and has no other results. If ``count``
is greater than ``SSIZE_MAX``, the result is unspecified.
-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 :ref:`lirc_func`.
-The generally preferred mode for receive is
-:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`, in which packets containing an
-int value describing an IR signal are read from the chardev.
+The exact format of the data depends on what :ref:`lirc_modes` a driver
+uses. Use :ref:`lirc_get_features` to get the supported mode.
-See also
-`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__
-for more info.
+The generally preferred mode for receive is
+:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`,
+in which packets containing an int value describing an IR signal are
+read from the chardev.
Return Value
============
diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst
index a83fbbfa0d3b..a89246806c4b 100644
--- a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst
+++ b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst
@@ -9,7 +9,7 @@ ioctl LIRC_SET_REC_CARRIER_RANGE
Name
====
-LIRC_SET_REC_CARRIER_RANGE - Set lower bond of the carrier used to modulate
+LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate
IR receive.
Synopsis
diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst
index 9c501bbf4c62..86353e602695 100644
--- a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst
+++ b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst
@@ -31,6 +31,8 @@ Arguments
Description
===========
+.. _lirc-mode2-timeout:
+
Enable or disable timeout reports for IR receive. By default, timeout reports
should be turned off.
diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst
index 3b035c6613b1..2aad0fef4a5b 100644
--- a/Documentation/media/uapi/rc/lirc-write.rst
+++ b/Documentation/media/uapi/rc/lirc-write.rst
@@ -42,13 +42,16 @@ Description
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``.
-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 uneven number of samples. The write function must
-block until the data has been transmitted by the hardware. If more data
-is provided than the hardware can send, the driver returns ``EINVAL``.
-
+The exact format of the data depends on what mode a driver uses, use
+:ref:`lirc_get_features` to get the supported mode.
+
+When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, 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 uneven number of
+samples. The write function must block until the data has been transmitted
+by the hardware. If more data is provided than the hardware can send, the
+driver returns ``EINVAL``.
Return Value
============