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