1.. SPDX-License-Identifier: 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******************** 140BPF based IR decoder 141******************** 142 143The kernel has support for decoding the most common 144:ref:`IR protocols <Remote_controllers_Protocols>`, but there 145are many protocols which are not supported. To support these, it is possible 146to load an BPF program which does the decoding. This can only be done on 147LIRC devices which support reading raw IR. 148 149First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument, 150program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached 151to the LIRC device, this program will be called for each pulse, space or 152timeout event on the LIRC device. The context for the BPF program is a 153pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` 154value. When the program has decoded the scancode, it can be submitted using 155the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer 156movements can be reported using ``bpf_rc_pointer_rel()``. 157 158Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF 159program, it can be attached to the LIRC device using the `bpf(2)`_ syscall. 160The target must be the file descriptor for the LIRC device, and the 161attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be 162attached to a single LIRC device at a time. 163 164.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html 165