rc-core: proposed changes

By far, the most common kind of remote control hardware (receivers and transmitters for receiving/generating the kind of signals used by handheld remote controls - like the kind you would normally expect to use to control e.g. your TV set) is based on InfraRed, IR, technology. This kind of hardware is often referred to as Consumer InfraRed, CIR, in order to distinguish it from other types of IR hardware, such as the wireless data transfer technology standardized by the Infrared Data Association, IrDA.

There are, however, other solutions based on e.g. radio-frequency (RF), HDMI, etc. One such example that is supported by the Linux kernel is the ATI Remote Wonder which uses RF rather than IR to transmit commands. For that reason, this document will use the terminology “remote control”, RC, rather than e.g. IR. This is also the approach adopted in the kernel, as evidenced by the drivers/media/rc directory and rc-core module in the kernel sources.

The granddaddy of RC drivers in the Linux ecosystem is the LIRC project. LIRC was developed out-of-kernel and contained drivers as well as software tools to receive/send IR signals. The focus was traditionally on hardware which measured and generated pulse-space timings from IR signals. Such hardware, which will be referred to as raw IR hardware, has the advantage that it will (in theory) work with more or less any kind of remote, no matter which specific IR protocol it uses - as long as there is an appropriate decoder written for that protocol. In LIRC, such decoders were implemented in a userspace daemon which received captured pulse-space values from the in-kernel hardware driver.

In addition to special-purpose IR hardware, many digital and analog TV/video capture cards included hardware to receive IR signals. These cards often come bundled with a remote and typically do not support IR transmission. Many of the cards also have on-board decoders for received IR signals, meaning that rather than delivering raw pulse-space timings, the cards only provide already decoded commands. The advantage is that no further decoding of the signal is necessary, but the hardware is typically limited to supporting one, or at most a few, IR protocols. Some hardware decoders do not even return the full decoded signal, but only parts of it (e.g. only the command bits and not the address bits), making it impossible to know the full signal. Hardware which does some kind of hardware decoding will be referred to as cooked in this article.

As cooked hardware was typically found on digital and analog video cards, the IR support for this kind of hardware developed in the linux kernel (via the linux-media/linux-tv projects) independently from LIRC. As a result of discussions on how to merge the LIRC tree into the kernel, rc-core was created in order to merge the two approaches into a consistant API. The legacy of the two code-bases is, however, still very evident today if one looks at the rc-core code (i.e. everything under drivers/media/rc/) in detail (example: the in-kernel keymaps were traditionally associated with cooked hardware while the in-kernel decoders and lirc kernel module are examples of code specifially for raw hardware).

The following picture provides an overview of how rc-core works today. Note that dashed lines denote optional parts.

Figure 1. rc-core current situation

As part of its initialization, a kernel hardware driver calls rc_register_device() which returns a struct rc_dev. This struct holds all the relevant state of the rc device (similar to the role played by struct input_dev in the input subsystem). All further interaction with rc-core (via the functions defined in include/media/rc-core.h) uses the struct rc_dev to keep track of the relevant device.

For each registered struct rc_dev, rc-core maintains a keytable, which is simply an array with scancode-keycode mappings. Scancodes are protocol specific, but most IR protocols divide the transmitted message into system and command bits (though the terminology varies). Roughly, the system bits define the device that is the intended recipient (which is why the remote control for the stereo will, hopefully, not have any effect on the TV and vice versa, even if they use the same protocol).

For example, an IR in the RC5 protocol has 5 system bits and 7 (originally 6) command bits as well as one toggle bit (to distinguish between a long keypress and several short ones, not used in the scancode). The command bits are stored in the lowest 8 bits and the system bits are stored in the next 8 bits. Given a scancode of 0x0000031F, we can therefore deduce that the system was 0x03 and the command was 0x1F (assuming the scancode is an RC5 scancode).

Keycodes are defined in input/uapi/linux/input.h as integer constants like KEY_A, KEY_ESC, etc. The keytable is typically populated at module load by the rc hardware driver setting the map_name of the struct rc_dev to the name of a keymap. Default keymaps are implemented as loadable kernel modules (see drivers/media/rc/keymaps/ for a long list) and rc-core will make sure that the corresponding keymap kernel module is loaded and used to populate the keytable.

For raw hardware, rc-core will also load various decoding modules (per default all known modules are loaded) which are used to decode the pulse-space timings produced by this kind of hardware into the scancodes explained above.

rc-core also exposes a sysfs API (see /sys/class/rc/rcX/) which can be used to, inter alia, enable/disable various protocols during runtime for raw as well as cooked hardware (the former simply enabling/disabling the use of the software decoder while latter usually means that the underlying hardware is reconfigured).

rc-core also maintains an input device (struct input_dev) per struct rc_dev. As rc messages are received and, optionally, decoded, the keytable is consulted. If a matching scancode-keycode entry is found, the event (e.g. KEY_A is pressed) is reported to the input subsystem. In any case, the scancode is reported to the input subsystem (as a EV_MSC/MSC_SCAN event), allowing keymaps to be constructed in userspace for new remotes.

The input subsystem, in turn, maintains a chardev per input device (e.g. /dev/input/event12) which allows interested userspace applications to be notified of input events on the relevant device(s) by open():ing the chardev and read():ing struct input_event events from it (this is how e.g. the X server and libinput library receive events. The input device that rc-core creates looks just like a keyboard to a userspace application, allowing it to be blissfully unaware of any rc related details.

The input subsystem also contains functionality to allow userspace to manipulate the keytable via ioctl():s on the event chardev. The traditional ioctl():s (EVIOCGETKEYCODE and EVIOCSKEYCODE) only took a pair of integers (scancode/keycode) as arguments. Since scancodes could be larger than an integer, the EVIOCGKEYCODE_V2 and EVIOCSKEYCODE_V2 ioctl():s, which are able to take much larger scancodes, were introduced. The new functions also allow scancode/keycode mappings to be looked up by index rather than by scancode, which allows the whole keytable to be dumped in a simple fashion.

Finally, the rc subsystem includes the optional lirc module, which acts like a bridge between rc-core and userspace applications which expect the LIRC API. For implementational reasons, the lirc module is implemented as a codec, meaning that it will receive the raw pulse/space events for raw hardware. If lirc is loaded, rc-core maintains a struct lirc_codec per struct rc_dev, which maintains the relevant state.

The lirc module maintains a per-device /dev/lircX chardev which a userspace application can open() and then perform read(), write(), and ioctl() on in order to receive and send data in the form of pulse-space timing integers and to control various parameters of the hardware (such as carrier, duty cycle, timeout, etc). The lirc API is IR specific.