1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _lirc_dev_intro:
11
12************
13Introduction
14************
15
16LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
17a bi-directional interface for transporting raw IR and decoded scancodes
18data between userspace and kernelspace. Fundamentally, it is just a chardev
19(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct
20file_operations defined on it. With respect to transporting raw IR and
21decoded scancodes to and fro, the essential fops are read, write and ioctl.
22
23It is also possible to attach a BPF program to a LIRC device for decoding
24raw IR into scancodes.
25
26Example dmesg output upon a driver registering w/LIRC:
27
28.. code-block:: none
29
30    $ dmesg |grep lirc_dev
31    rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter
32
33What you should see for a chardev:
34
35.. code-block:: none
36
37    $ ls -l /dev/lirc*
38    crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
39
40Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
41contains tools for working with LIRC devices:
42
43 - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC
44   device features.
45
46 - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load
47   BPF IR decoders and test IR decoding. Some BPF IR decoders are also
48   provided.
49
50.. _lirc_modes:
51
52**********
53LIRC modes
54**********
55
56LIRC supports some modes of receiving and sending IR codes, as shown
57on the following table.
58
59.. _lirc-mode-scancode:
60.. _lirc-scancode-flag-toggle:
61.. _lirc-scancode-flag-repeat:
62
63``LIRC_MODE_SCANCODE``
64
65    This mode is for both sending and receiving IR.
66
67    For transmitting (aka sending), create a ``struct lirc_scancode`` with
68    the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
69    set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
70    members set to 0. Write this struct to the lirc device.
71
72    For receiving, you read ``struct lirc_scancode`` from the LIRC device.
73    The ``scancode`` field is set to the received scancode and the
74    :ref:`IR protocol <Remote_controllers_Protocols>` is set in
75    :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
76    in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
77
78    The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle
79    bit is set in protocols that support it (e.g. rc-5 and rc-6), or
80    ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols
81    that support it (e.g. nec).
82
83    In the Sanyo and NEC protocol, if you hold a button on remote, rather than
84    repeating the entire scancode, the remote sends a shorter message with
85    no scancode, which just means button is held, a "repeat". When this is
86    received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and
87    keycode is repeated.
88
89    With nec, there is no way to distinguish "button hold" from "repeatedly
90    pressing the same button". The rc-5 and rc-6 protocols have a toggle bit.
91    When a button is released and pressed again, the toggle bit is inverted.
92    If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set.
93
94    The ``timestamp`` field is filled with the time nanoseconds
95    (in ``CLOCK_MONOTONIC``) when the scancode was decoded.
96
97.. _lirc-mode-mode2:
98
99``LIRC_MODE_MODE2``
100
101    The driver returns a sequence of pulse and space codes to userspace,
102    as a series of u32 values.
103
104    This mode is used only for IR receive.
105
106    The upper 8 bits determine the packet type, and the lower 24 bits
107    the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
108    the macro ``LIRC_MODE2()`` will give you the type, which
109    is one of:
110
111    ``LIRC_MODE2_PULSE``
112
113        Signifies the presence of IR in microseconds.
114
115    ``LIRC_MODE2_SPACE``
116
117        Signifies absence of IR in microseconds.
118
119    ``LIRC_MODE2_FREQUENCY``
120
121        If measurement of the carrier frequency was enabled with
122        :ref:`lirc_set_measure_carrier_mode` then this packet gives you
123        the carrier frequency in Hertz.
124
125    ``LIRC_MODE2_TIMEOUT``
126
127        If timeout reports are enabled with
128        :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
129        :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
130        this packet will be sent, with the number of microseconds with
131        no IR.
132
133.. _lirc-mode-pulse:
134
135``LIRC_MODE_PULSE``
136
137    In pulse mode, a sequence of pulse/space integer values are written to the
138    lirc device using :ref:`lirc-write`.
139
140    The values are alternating pulse and space lengths, in microseconds. The
141    first and last entry must be a pulse, so there must be an odd number
142    of entries.
143
144    This mode is used only for IR send.
145
146********************
147BPF based IR decoder
148********************
149
150The kernel has support for decoding the most common
151:ref:`IR protocols <Remote_controllers_Protocols>`, but there
152are many protocols which are not supported. To support these, it is possible
153to load an BPF program which does the decoding. This can only be done on
154LIRC devices which support reading raw IR.
155
156First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
157program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
158to the LIRC device, this program will be called for each pulse, space or
159timeout event on the LIRC device. The context for the BPF program is a
160pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
161value. When the program has decoded the scancode, it can be submitted using
162the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
163movements can be reported using ``bpf_rc_pointer_rel()``.
164
165Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
166program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
167The target must be the file descriptor for the LIRC device, and the
168attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
169attached to a single LIRC device at a time.
170
171.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
172