1ac7f9d02SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _lirc_dev_intro: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab************ 654f38fcaSMauro Carvalho ChehabIntroduction 754f38fcaSMauro Carvalho Chehab************ 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabLIRC stands for Linux Infrared Remote Control. The LIRC device interface is 1054f38fcaSMauro Carvalho Chehaba bi-directional interface for transporting raw IR and decoded scancodes 1154f38fcaSMauro Carvalho Chehabdata between userspace and kernelspace. Fundamentally, it is just a chardev 1254f38fcaSMauro Carvalho Chehab(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct 1354f38fcaSMauro Carvalho Chehabfile_operations defined on it. With respect to transporting raw IR and 1454f38fcaSMauro Carvalho Chehabdecoded scancodes to and fro, the essential fops are read, write and ioctl. 1554f38fcaSMauro Carvalho Chehab 1654f38fcaSMauro Carvalho ChehabIt is also possible to attach a BPF program to a LIRC device for decoding 1754f38fcaSMauro Carvalho Chehabraw IR into scancodes. 1854f38fcaSMauro Carvalho Chehab 1954f38fcaSMauro Carvalho ChehabExample dmesg output upon a driver registering w/LIRC: 2054f38fcaSMauro Carvalho Chehab 2154f38fcaSMauro Carvalho Chehab.. code-block:: none 2254f38fcaSMauro Carvalho Chehab 2354f38fcaSMauro Carvalho Chehab $ dmesg |grep lirc_dev 2454f38fcaSMauro Carvalho Chehab rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter 2554f38fcaSMauro Carvalho Chehab 2654f38fcaSMauro Carvalho ChehabWhat you should see for a chardev: 2754f38fcaSMauro Carvalho Chehab 2854f38fcaSMauro Carvalho Chehab.. code-block:: none 2954f38fcaSMauro Carvalho Chehab 3054f38fcaSMauro Carvalho Chehab $ ls -l /dev/lirc* 3154f38fcaSMauro Carvalho Chehab crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 3254f38fcaSMauro Carvalho Chehab 3354f38fcaSMauro Carvalho ChehabNote that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ 3454f38fcaSMauro Carvalho Chehabcontains tools for working with LIRC devices: 3554f38fcaSMauro Carvalho Chehab 3654f38fcaSMauro Carvalho Chehab - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC 3754f38fcaSMauro Carvalho Chehab device features. 3854f38fcaSMauro Carvalho Chehab 3954f38fcaSMauro Carvalho Chehab - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load 4054f38fcaSMauro Carvalho Chehab BPF IR decoders and test IR decoding. Some BPF IR decoders are also 4154f38fcaSMauro Carvalho Chehab provided. 4254f38fcaSMauro Carvalho Chehab 4354f38fcaSMauro Carvalho Chehab.. _lirc_modes: 4454f38fcaSMauro Carvalho Chehab 4554f38fcaSMauro Carvalho Chehab********** 4654f38fcaSMauro Carvalho ChehabLIRC modes 4754f38fcaSMauro Carvalho Chehab********** 4854f38fcaSMauro Carvalho Chehab 4954f38fcaSMauro Carvalho ChehabLIRC supports some modes of receiving and sending IR codes, as shown 5054f38fcaSMauro Carvalho Chehabon the following table. 5154f38fcaSMauro Carvalho Chehab 5254f38fcaSMauro Carvalho Chehab.. _lirc-mode-scancode: 5354f38fcaSMauro Carvalho Chehab.. _lirc-scancode-flag-toggle: 5454f38fcaSMauro Carvalho Chehab.. _lirc-scancode-flag-repeat: 5554f38fcaSMauro Carvalho Chehab 5654f38fcaSMauro Carvalho Chehab``LIRC_MODE_SCANCODE`` 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho Chehab This mode is for both sending and receiving IR. 5954f38fcaSMauro Carvalho Chehab 604fe21decSMauro Carvalho Chehab For transmitting (aka sending), create a struct lirc_scancode with 6154f38fcaSMauro Carvalho Chehab the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` 6254f38fcaSMauro Carvalho Chehab set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other 6354f38fcaSMauro Carvalho Chehab members set to 0. Write this struct to the lirc device. 6454f38fcaSMauro Carvalho Chehab 654fe21decSMauro Carvalho Chehab For receiving, you read struct lirc_scancode from the LIRC device. 6654f38fcaSMauro Carvalho Chehab The ``scancode`` field is set to the received scancode and the 6754f38fcaSMauro Carvalho Chehab :ref:`IR protocol <Remote_controllers_Protocols>` is set in 6854f38fcaSMauro Carvalho Chehab :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set 6954f38fcaSMauro Carvalho Chehab in the ``keycode`` field, else it is set to ``KEY_RESERVED``. 7054f38fcaSMauro Carvalho Chehab 7154f38fcaSMauro Carvalho Chehab The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle 7254f38fcaSMauro Carvalho Chehab bit is set in protocols that support it (e.g. rc-5 and rc-6), or 7354f38fcaSMauro Carvalho Chehab ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols 7454f38fcaSMauro Carvalho Chehab that support it (e.g. nec). 7554f38fcaSMauro Carvalho Chehab 7654f38fcaSMauro Carvalho Chehab In the Sanyo and NEC protocol, if you hold a button on remote, rather than 7754f38fcaSMauro Carvalho Chehab repeating the entire scancode, the remote sends a shorter message with 7854f38fcaSMauro Carvalho Chehab no scancode, which just means button is held, a "repeat". When this is 7954f38fcaSMauro Carvalho Chehab received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and 8054f38fcaSMauro Carvalho Chehab keycode is repeated. 8154f38fcaSMauro Carvalho Chehab 8254f38fcaSMauro Carvalho Chehab With nec, there is no way to distinguish "button hold" from "repeatedly 8354f38fcaSMauro Carvalho Chehab pressing the same button". The rc-5 and rc-6 protocols have a toggle bit. 8454f38fcaSMauro Carvalho Chehab When a button is released and pressed again, the toggle bit is inverted. 8554f38fcaSMauro Carvalho Chehab If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set. 8654f38fcaSMauro Carvalho Chehab 8754f38fcaSMauro Carvalho Chehab The ``timestamp`` field is filled with the time nanoseconds 8854f38fcaSMauro Carvalho Chehab (in ``CLOCK_MONOTONIC``) when the scancode was decoded. 8954f38fcaSMauro Carvalho Chehab 9054f38fcaSMauro Carvalho Chehab.. _lirc-mode-mode2: 9154f38fcaSMauro Carvalho Chehab 9254f38fcaSMauro Carvalho Chehab``LIRC_MODE_MODE2`` 9354f38fcaSMauro Carvalho Chehab 9454f38fcaSMauro Carvalho Chehab The driver returns a sequence of pulse and space codes to userspace, 9554f38fcaSMauro Carvalho Chehab as a series of u32 values. 9654f38fcaSMauro Carvalho Chehab 9754f38fcaSMauro Carvalho Chehab This mode is used only for IR receive. 9854f38fcaSMauro Carvalho Chehab 9954f38fcaSMauro Carvalho Chehab The upper 8 bits determine the packet type, and the lower 24 bits 10054f38fcaSMauro Carvalho Chehab the payload. Use ``LIRC_VALUE()`` macro to get the payload, and 10154f38fcaSMauro Carvalho Chehab the macro ``LIRC_MODE2()`` will give you the type, which 10254f38fcaSMauro Carvalho Chehab is one of: 10354f38fcaSMauro Carvalho Chehab 10454f38fcaSMauro Carvalho Chehab ``LIRC_MODE2_PULSE`` 10554f38fcaSMauro Carvalho Chehab 106*68a99f6aSSean Young Signifies the presence of IR in microseconds, also known as *flash*. 10754f38fcaSMauro Carvalho Chehab 10854f38fcaSMauro Carvalho Chehab ``LIRC_MODE2_SPACE`` 10954f38fcaSMauro Carvalho Chehab 110*68a99f6aSSean Young Signifies absence of IR in microseconds, also known as *gap*. 11154f38fcaSMauro Carvalho Chehab 11254f38fcaSMauro Carvalho Chehab ``LIRC_MODE2_FREQUENCY`` 11354f38fcaSMauro Carvalho Chehab 11454f38fcaSMauro Carvalho Chehab If measurement of the carrier frequency was enabled with 11554f38fcaSMauro Carvalho Chehab :ref:`lirc_set_measure_carrier_mode` then this packet gives you 11654f38fcaSMauro Carvalho Chehab the carrier frequency in Hertz. 11754f38fcaSMauro Carvalho Chehab 11854f38fcaSMauro Carvalho Chehab ``LIRC_MODE2_TIMEOUT`` 11954f38fcaSMauro Carvalho Chehab 12074747ddaSSean Young When the timeout set with :ref:`lirc_set_rec_timeout` expires due 12174747ddaSSean Young to no IR being detected, this packet will be sent, with the number 12274747ddaSSean Young of microseconds with no IR. 12354f38fcaSMauro Carvalho Chehab 124*68a99f6aSSean Young ``LIRC_MODE2_OVERFLOW`` 125*68a99f6aSSean Young 126*68a99f6aSSean Young Signifies that the IR receiver encounter an overflow, and some IR 127*68a99f6aSSean Young is missing. The IR data after this should be correct again. The 128*68a99f6aSSean Young actual value is not important, but this is set to 0xffffff by the 129*68a99f6aSSean Young kernel for compatibility with lircd. 130*68a99f6aSSean Young 13154f38fcaSMauro Carvalho Chehab.. _lirc-mode-pulse: 13254f38fcaSMauro Carvalho Chehab 13354f38fcaSMauro Carvalho Chehab``LIRC_MODE_PULSE`` 13454f38fcaSMauro Carvalho Chehab 13554f38fcaSMauro Carvalho Chehab In pulse mode, a sequence of pulse/space integer values are written to the 13654f38fcaSMauro Carvalho Chehab lirc device using :ref:`lirc-write`. 13754f38fcaSMauro Carvalho Chehab 13854f38fcaSMauro Carvalho Chehab The values are alternating pulse and space lengths, in microseconds. The 13954f38fcaSMauro Carvalho Chehab first and last entry must be a pulse, so there must be an odd number 14054f38fcaSMauro Carvalho Chehab of entries. 14154f38fcaSMauro Carvalho Chehab 14254f38fcaSMauro Carvalho Chehab This mode is used only for IR send. 14354f38fcaSMauro Carvalho Chehab 1444fe21decSMauro Carvalho Chehab************************************* 1454fe21decSMauro Carvalho ChehabData types used by LIRC_MODE_SCANCODE 1464fe21decSMauro Carvalho Chehab************************************* 1474fe21decSMauro Carvalho Chehab 1484fe21decSMauro Carvalho Chehab.. kernel-doc:: include/uapi/linux/lirc.h 1494fe21decSMauro Carvalho Chehab :identifiers: lirc_scancode rc_proto 1504fe21decSMauro Carvalho Chehab 15154f38fcaSMauro Carvalho Chehab******************** 15254f38fcaSMauro Carvalho ChehabBPF based IR decoder 15354f38fcaSMauro Carvalho Chehab******************** 15454f38fcaSMauro Carvalho Chehab 15554f38fcaSMauro Carvalho ChehabThe kernel has support for decoding the most common 15654f38fcaSMauro Carvalho Chehab:ref:`IR protocols <Remote_controllers_Protocols>`, but there 15754f38fcaSMauro Carvalho Chehabare many protocols which are not supported. To support these, it is possible 15854f38fcaSMauro Carvalho Chehabto load an BPF program which does the decoding. This can only be done on 15954f38fcaSMauro Carvalho ChehabLIRC devices which support reading raw IR. 16054f38fcaSMauro Carvalho Chehab 16154f38fcaSMauro Carvalho ChehabFirst, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument, 16254f38fcaSMauro Carvalho Chehabprogram must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached 16354f38fcaSMauro Carvalho Chehabto the LIRC device, this program will be called for each pulse, space or 16454f38fcaSMauro Carvalho Chehabtimeout event on the LIRC device. The context for the BPF program is a 16554f38fcaSMauro Carvalho Chehabpointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` 16654f38fcaSMauro Carvalho Chehabvalue. When the program has decoded the scancode, it can be submitted using 16754f38fcaSMauro Carvalho Chehabthe BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer 16854f38fcaSMauro Carvalho Chehabmovements can be reported using ``bpf_rc_pointer_rel()``. 16954f38fcaSMauro Carvalho Chehab 17054f38fcaSMauro Carvalho ChehabOnce you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF 17154f38fcaSMauro Carvalho Chehabprogram, it can be attached to the LIRC device using the `bpf(2)`_ syscall. 17254f38fcaSMauro Carvalho ChehabThe target must be the file descriptor for the LIRC device, and the 17354f38fcaSMauro Carvalho Chehabattach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be 17454f38fcaSMauro Carvalho Chehabattached to a single LIRC device at a time. 17554f38fcaSMauro Carvalho Chehab 17654f38fcaSMauro Carvalho Chehab.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html 177