177 lines · plain
1.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later2 3.. _lirc_dev_intro:4 5************6Introduction7************8 9LIRC stands for Linux Infrared Remote Control. The LIRC device interface is10a bi-directional interface for transporting raw IR and decoded scancodes11data between userspace and kernelspace. Fundamentally, it is just a chardev12(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct13file_operations defined on it. With respect to transporting raw IR and14decoded 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 decoding17raw IR into scancodes.18 19Example dmesg output upon a driver registering w/LIRC:20 21.. code-block:: none22 23 $ dmesg |grep lirc_dev24 rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter25 26What you should see for a chardev:27 28.. code-block:: none29 30 $ ls -l /dev/lirc*31 crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc032 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 LIRC37 device features.38 39 - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load40 BPF IR decoders and test IR decoding. Some BPF IR decoders are also41 provided.42 43.. _lirc_modes:44 45**********46LIRC modes47**********48 49LIRC supports some modes of receiving and sending IR codes, as shown50on 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 with61 the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`62 set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other63 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 the67 :ref:`IR protocol <Remote_controllers_Protocols>` is set in68 :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set69 in the ``keycode`` field, else it is set to ``KEY_RESERVED``.70 71 The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle72 bit is set in protocols that support it (e.g. rc-5 and rc-6), or73 ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols74 that support it (e.g. nec).75 76 In the Sanyo and NEC protocol, if you hold a button on remote, rather than77 repeating the entire scancode, the remote sends a shorter message with78 no scancode, which just means button is held, a "repeat". When this is79 received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and80 keycode is repeated.81 82 With nec, there is no way to distinguish "button hold" from "repeatedly83 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 nanoseconds88 (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 bits100 the payload. Use ``LIRC_VALUE()`` macro to get the payload, and101 the macro ``LIRC_MODE2()`` will give you the type, which102 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 with115 :ref:`lirc_set_measure_carrier_mode` then this packet gives you116 the carrier frequency in Hertz.117 118 ``LIRC_MODE2_TIMEOUT``119 120 When the timeout set with :ref:`lirc_set_rec_timeout` expires due121 to no IR being detected, this packet will be sent, with the number122 of microseconds with no IR.123 124 ``LIRC_MODE2_OVERFLOW``125 126 Signifies that the IR receiver encounter an overflow, and some IR127 is missing. The IR data after this should be correct again. The128 actual value is not important, but this is set to 0xffffff by the129 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 the136 lirc device using :ref:`lirc-write`.137 138 The values are alternating pulse and space lengths, in microseconds. The139 first and last entry must be a pulse, so there must be an odd number140 of entries.141 142 This mode is used only for IR send.143 144*************************************145Data types used by LIRC_MODE_SCANCODE146*************************************147 148.. kernel-doc:: include/uapi/linux/lirc.h149 :identifiers: lirc_scancode rc_proto150 151********************152BPF based IR decoder153********************154 155The kernel has support for decoding the most common156:ref:`IR protocols <Remote_controllers_Protocols>`, but there157are many protocols which are not supported. To support these, it is possible158to load an BPF program which does the decoding. This can only be done on159LIRC 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 attached163to the LIRC device, this program will be called for each pulse, space or164timeout event on the LIRC device. The context for the BPF program is a165pointer 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 using167the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer168movements can be reported using ``bpf_rc_pointer_rel()``.169 170Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF171program, 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 the173attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be174attached to a single LIRC device at a time.175 176.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html177