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.
107
108    ``LIRC_MODE2_SPACE``
109
110        Signifies absence of IR in microseconds.
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        If timeout reports are enabled with
121        :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
122        :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
123        this packet will be sent, with the number of microseconds with
124        no IR.
125
126.. _lirc-mode-pulse:
127
128``LIRC_MODE_PULSE``
129
130    In pulse mode, a sequence of pulse/space integer values are written to the
131    lirc device using :ref:`lirc-write`.
132
133    The values are alternating pulse and space lengths, in microseconds. The
134    first and last entry must be a pulse, so there must be an odd number
135    of entries.
136
137    This mode is used only for IR send.
138
139*************************************
140Data types used by LIRC_MODE_SCANCODE
141*************************************
142
143.. kernel-doc:: include/uapi/linux/lirc.h
144    :identifiers: lirc_scancode rc_proto
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