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