^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. _lirc_dev_intro:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) a bi-directional interface for transporting raw IR and decoded scancodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) data between userspace and kernelspace. Fundamentally, it is just a chardev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) file_operations defined on it. With respect to transporting raw IR and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) decoded scancodes to and fro, the essential fops are read, write and ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) It is also possible to attach a BPF program to a LIRC device for decoding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) raw IR into scancodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Example dmesg output upon a driver registering w/LIRC:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) $ dmesg |grep lirc_dev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) What you should see for a chardev:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) $ ls -l /dev/lirc*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) contains tools for working with LIRC devices:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) device features.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) BPF IR decoders and test IR decoding. Some BPF IR decoders are also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) provided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) .. _lirc_modes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) **********
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) LIRC modes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) **********
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) LIRC supports some modes of receiving and sending IR codes, as shown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) on the following table.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) .. _lirc-mode-scancode:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) .. _lirc-scancode-flag-toggle:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) .. _lirc-scancode-flag-repeat:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) ``LIRC_MODE_SCANCODE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) This mode is for both sending and receiving IR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) For transmitting (aka sending), create a ``struct lirc_scancode`` with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) members set to 0. Write this struct to the lirc device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) For receiving, you read ``struct lirc_scancode`` from the LIRC device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) The ``scancode`` field is set to the received scancode and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) :ref:`IR protocol <Remote_controllers_Protocols>` is set in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) bit is set in protocols that support it (e.g. rc-5 and rc-6), or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) that support it (e.g. nec).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) In the Sanyo and NEC protocol, if you hold a button on remote, rather than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) repeating the entire scancode, the remote sends a shorter message with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) no scancode, which just means button is held, a "repeat". When this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) keycode is repeated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) With nec, there is no way to distinguish "button hold" from "repeatedly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) pressing the same button". The rc-5 and rc-6 protocols have a toggle bit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) When a button is released and pressed again, the toggle bit is inverted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) The ``timestamp`` field is filled with the time nanoseconds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) (in ``CLOCK_MONOTONIC``) when the scancode was decoded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) .. _lirc-mode-mode2:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) ``LIRC_MODE_MODE2``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) The driver returns a sequence of pulse and space codes to userspace,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) as a series of u32 values.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) This mode is used only for IR receive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) The upper 8 bits determine the packet type, and the lower 24 bits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) the macro ``LIRC_MODE2()`` will give you the type, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) is one of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) ``LIRC_MODE2_PULSE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Signifies the presence of IR in microseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) ``LIRC_MODE2_SPACE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Signifies absence of IR in microseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) ``LIRC_MODE2_FREQUENCY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) If measurement of the carrier frequency was enabled with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) :ref:`lirc_set_measure_carrier_mode` then this packet gives you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) the carrier frequency in Hertz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) ``LIRC_MODE2_TIMEOUT``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) If timeout reports are enabled with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) this packet will be sent, with the number of microseconds with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) no IR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) .. _lirc-mode-pulse:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) ``LIRC_MODE_PULSE``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) In pulse mode, a sequence of pulse/space integer values are written to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) lirc device using :ref:`lirc-write`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) The values are alternating pulse and space lengths, in microseconds. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) first and last entry must be a pulse, so there must be an odd number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) of entries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) This mode is used only for IR send.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) BPF based IR decoder
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) ********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) The kernel has support for decoding the most common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) :ref:`IR protocols <Remote_controllers_Protocols>`, but there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) are many protocols which are not supported. To support these, it is possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) to load an BPF program which does the decoding. This can only be done on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) LIRC devices which support reading raw IR.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) to the LIRC device, this program will be called for each pulse, space or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) timeout event on the LIRC device. The context for the BPF program is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) value. When the program has decoded the scancode, it can be submitted using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) movements can be reported using ``bpf_rc_pointer_rel()``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) The target must be the file descriptor for the LIRC device, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) attached to a single LIRC device at a time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags