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        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-mode-pulse:
125
126``LIRC_MODE_PULSE``
127
128    In pulse mode, a sequence of pulse/space integer values are written to the
129    lirc device using :ref:`lirc-write`.
130
131    The values are alternating pulse and space lengths, in microseconds. The
132    first and last entry must be a pulse, so there must be an odd number
133    of entries.
134
135    This mode is used only for IR send.
136
137*************************************
138Data types used by LIRC_MODE_SCANCODE
139*************************************
140
141.. kernel-doc:: include/uapi/linux/lirc.h
142    :identifiers: lirc_scancode rc_proto
143
144********************
145BPF based IR decoder
146********************
147
148The kernel has support for decoding the most common
149:ref:`IR protocols <Remote_controllers_Protocols>`, but there
150are many protocols which are not supported. To support these, it is possible
151to load an BPF program which does the decoding. This can only be done on
152LIRC devices which support reading raw IR.
153
154First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
155program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
156to the LIRC device, this program will be called for each pulse, space or
157timeout event on the LIRC device. The context for the BPF program is a
158pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
159value. When the program has decoded the scancode, it can be submitted using
160the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
161movements can be reported using ``bpf_rc_pointer_rel()``.
162
163Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
164program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
165The target must be the file descriptor for the LIRC device, and the
166attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
167attached to a single LIRC device at a time.
168
169.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
170