Documentation/userspace-api/media/rc/lirc-dev-intro.rst

   1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
   2
   3 .. _lirc_dev_intro:
   4
   5 ************
   6 Introduction
   7 ************
   8
   9 LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
  10 a bi-directional interface for transporting raw IR and decoded scancodes
  11 data between userspace and kernelspace. Fundamentally, it is just a chardev
  12 (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct
  13 file_operations defined on it. With respect to transporting raw IR and
  14 decoded scancodes to and fro, the essential fops are read, write and ioctl.
  15
  16 It is also possible to attach a BPF program to a LIRC device for decoding
  17 raw IR into scancodes.
  18
  19 Example 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
  26 What 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
  33 Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
  34 contains 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 **********
  46 LIRC modes
  47 **********
  48
  49 LIRC supports some modes of receiving and sending IR codes, as shown
  50 on 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 *************************************
 145 Data types used by LIRC_MODE_SCANCODE
 146 *************************************
 147
 148 .. kernel-doc:: include/uapi/linux/lirc.h
 149     :identifiers: lirc_scancode rc_proto
 150
 151 ********************
 152 BPF based IR decoder
 153 ********************
 154
 155 The kernel has support for decoding the most common
 156 :ref:`IR protocols <Remote_controllers_Protocols>`, but there
 157 are many protocols which are not supported. To support these, it is possible
 158 to load an BPF program which does the decoding. This can only be done on
 159 LIRC devices which support reading raw IR.
 160
 161 First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
 162 program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
 163 to the LIRC device, this program will be called for each pulse, space or
 164 timeout event on the LIRC device. The context for the BPF program is a
 165 pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
 166 value. When the program has decoded the scancode, it can be submitted using
 167 the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
 168 movements can be reported using ``bpf_rc_pointer_rel()``.
 169
 170 Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
 171 program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
 172 The target must be the file descriptor for the LIRC device, and the
 173 attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
 174 attached to a single LIRC device at a time.
 175
 176 .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html