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