tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
media: rc-core.rst: add an introduction for RC core
The RC core does several assumptions, but those aren't documented
anywhere, with could make harder for ones that want to understand
what's there.
So, add an introduction explaining the basic concepts of RC and
how they're related to the RC core implementation.
Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: Sean Young <sean@mess.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
+77
+77
Documentation/media/kapi/rc-core.rst
+77
Documentation/media/kapi/rc-core.rst
···
4
4
Remote Controller core
5
5
~~~~~~~~~~~~~~~~~~~~~~
6
6
7
+
The remote controller core implements infrastructure to receive and send
8
+
remote controller keyboard keystrokes and mouse events.
9
+
10
+
Every time a key is pressed on a remote controller, a scan code is produced.
11
+
Also, on most hardware, keeping a key pressed for more than a few dozens of
12
+
milliseconds produce a repeat key event. That's somewhat similar to what
13
+
a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
14
+
remote controller core is implemented on the top of the linux input/evdev
15
+
interface.
16
+
17
+
.. [#f1]
18
+
19
+
The main difference is that, on keyboard events, the keyboard controller
20
+
produces one event for a key press and another one for key release. On
21
+
infrared-based remote controllers, there's no key release event. Instead,
22
+
an extra code is produced to indicate key repeats.
23
+
24
+
However, most of the remote controllers use infrared (IR) to transmit signals.
25
+
As there are several protocols used to modulate infrared signals, one
26
+
important part of the core is dedicated to adjust the driver and the core
27
+
system to support the infrared protocol used by the emitter.
28
+
29
+
The infrared transmission is done by blinking a infrared emitter using a
30
+
carrier. The carrier can be switched on or off by the IR transmitter
31
+
hardware. When the carrier is switched on, it is called *PULSE*.
32
+
When the carrier is switched off, it is called *SPACE*.
33
+
34
+
In other words, a typical IR transmission can be viewed as a sequence of
35
+
*PULSE* and *SPACE* events, each with a given duration.
36
+
37
+
The carrier parameters (frequency, duty cycle) and the intervals for
38
+
*PULSE* and *SPACE* events depend on the protocol.
39
+
For example, the NEC protocol uses a carrier of 38kHz, and transmissions
40
+
start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
41
+
scan code, being 8 bits for address (usually it is a fixed number for a
42
+
given remote controller), followed by 8 bits of code. A bit "1" is modulated
43
+
with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0" is modulated
44
+
with 560µs *PULSE* followed by 560µs *SPACE*.
45
+
46
+
At receiver, a simple low-pass filter can be used to convert the received
47
+
signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
48
+
frequency. Due to that, the receiver doesn't care about the carrier's
49
+
actual frequency parameters: all it has to do is to measure the amount
50
+
of time it receives *PULSE/SPACE* events.
51
+
So, a simple IR receiver hardware will just provide a sequence of timings
52
+
for those events to the Kernel. The drivers for hardware with such kind of
53
+
receivers are identified by ``RC_DRIVER_IR_RAW``, as defined by
54
+
:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
55
+
microcontroller that decode the *PULSE/SPACE* sequence and return scan
56
+
codes to the Kernel. Such kind of receivers are identified
57
+
by ``RC_DRIVER_SCANCODE``.
58
+
59
+
.. [#f2]
60
+
61
+
The RC core also supports devices that have just IR emitters,
62
+
without any receivers. Right now, all such devices work only in
63
+
raw TX mode. Such kind of hardware is identified as
64
+
``RC_DRIVER_IR_RAW_TX``.
65
+
66
+
When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
67
+
receivers, it needs to decode the IR protocol, in order to obtain the
68
+
corresponding scan code. The protocols supported by the RC core are
69
+
defined at enum :c:type:`rc_proto`.
70
+
71
+
When the RC code receives a scan code (either directly, by a driver
72
+
of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
73
+
to convert into a Linux input event code. This is done via a mapping
74
+
table.
75
+
76
+
The Kernel has support for mapping tables available on most media
77
+
devices. It also supports loading a table in runtime, via some
78
+
sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>`
79
+
for more details.
80
+
81
+
Remote controller data structures and functions
82
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
83
+
7
84
.. kernel-doc:: include/media/rc-core.h
8
85
9
86
.. kernel-doc:: include/media/rc-map.h