mirror of
https://github.com/torvalds/linux.git
synced 2024-11-16 17:12:06 +00:00
ff768f596f
All those documents describe the media driver API. So, move them to the right place within the Kernel documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
89 lines
3.9 KiB
ReStructuredText
89 lines
3.9 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
Remote Controller devices
|
|
-------------------------
|
|
|
|
Remote Controller core
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The remote controller core implements infrastructure to receive and send
|
|
remote controller keyboard keystrokes and mouse events.
|
|
|
|
Every time a key is pressed on a remote controller, a scan code is produced.
|
|
Also, on most hardware, keeping a key pressed for more than a few dozens of
|
|
milliseconds produce a repeat key event. That's somewhat similar to what
|
|
a normal keyboard or mouse is handled internally on Linux\ [#f1]_. So, the
|
|
remote controller core is implemented on the top of the linux input/evdev
|
|
interface.
|
|
|
|
.. [#f1]
|
|
|
|
The main difference is that, on keyboard events, the keyboard controller
|
|
produces one event for a key press and another one for key release. On
|
|
infrared-based remote controllers, there's no key release event. Instead,
|
|
an extra code is produced to indicate key repeats.
|
|
|
|
However, most of the remote controllers use infrared (IR) to transmit signals.
|
|
As there are several protocols used to modulate infrared signals, one
|
|
important part of the core is dedicated to adjust the driver and the core
|
|
system to support the infrared protocol used by the emitter.
|
|
|
|
The infrared transmission is done by blinking a infrared emitter using a
|
|
carrier. The carrier can be switched on or off by the IR transmitter
|
|
hardware. When the carrier is switched on, it is called *PULSE*.
|
|
When the carrier is switched off, it is called *SPACE*.
|
|
|
|
In other words, a typical IR transmission can be viewed as a sequence of
|
|
*PULSE* and *SPACE* events, each with a given duration.
|
|
|
|
The carrier parameters (frequency, duty cycle) and the intervals for
|
|
*PULSE* and *SPACE* events depend on the protocol.
|
|
For example, the NEC protocol uses a carrier of 38kHz, and transmissions
|
|
start with a 9ms *PULSE* and a 4.5ms SPACE. It then transmits 16 bits of
|
|
scan code, being 8 bits for address (usually it is a fixed number for a
|
|
given remote controller), followed by 8 bits of code. A bit "1" is modulated
|
|
with 560µs *PULSE* followed by 1690µs *SPACE* and a bit "0" is modulated
|
|
with 560µs *PULSE* followed by 560µs *SPACE*.
|
|
|
|
At receiver, a simple low-pass filter can be used to convert the received
|
|
signal in a sequence of *PULSE/SPACE* events, filtering out the carrier
|
|
frequency. Due to that, the receiver doesn't care about the carrier's
|
|
actual frequency parameters: all it has to do is to measure the amount
|
|
of time it receives *PULSE/SPACE* events.
|
|
So, a simple IR receiver hardware will just provide a sequence of timings
|
|
for those events to the Kernel. The drivers for hardware with such kind of
|
|
receivers are identified by ``RC_DRIVER_IR_RAW``, as defined by
|
|
:c:type:`rc_driver_type`\ [#f2]_. Other hardware come with a
|
|
microcontroller that decode the *PULSE/SPACE* sequence and return scan
|
|
codes to the Kernel. Such kind of receivers are identified
|
|
by ``RC_DRIVER_SCANCODE``.
|
|
|
|
.. [#f2]
|
|
|
|
The RC core also supports devices that have just IR emitters,
|
|
without any receivers. Right now, all such devices work only in
|
|
raw TX mode. Such kind of hardware is identified as
|
|
``RC_DRIVER_IR_RAW_TX``.
|
|
|
|
When the RC core receives events produced by ``RC_DRIVER_IR_RAW`` IR
|
|
receivers, it needs to decode the IR protocol, in order to obtain the
|
|
corresponding scan code. The protocols supported by the RC core are
|
|
defined at enum :c:type:`rc_proto`.
|
|
|
|
When the RC code receives a scan code (either directly, by a driver
|
|
of the type ``RC_DRIVER_SCANCODE``, or via its IR decoders), it needs
|
|
to convert into a Linux input event code. This is done via a mapping
|
|
table.
|
|
|
|
The Kernel has support for mapping tables available on most media
|
|
devices. It also supports loading a table in runtime, via some
|
|
sysfs nodes. See the :ref:`RC userspace API <Remote_controllers_Intro>`
|
|
for more details.
|
|
|
|
Remote controller data structures and functions
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. kernel-doc:: include/media/rc-core.h
|
|
|
|
.. kernel-doc:: include/media/rc-map.h
|