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