summaryrefslogtreecommitdiffstats
path: root/Documentation/media/uapi/rc
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-07-08 11:40:06 -0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-07-08 11:59:40 -0300
commit60c2820d0f6d3497975b6488e2599f8f611d8b95 (patch)
treeb3b03707c6438ea9b99cc57e847ebf517f968ab1 /Documentation/media/uapi/rc
parenta97369b5e21ea9b8b5fef7c0f4f48bbe60c07ca3 (diff)
downloadlinux-60c2820d0f6d3497975b6488e2599f8f611d8b95.tar.bz2
doc_rst: rename the media Sphinx suff to Documentation/media
The name of the subsystem is "media", and not "linux_tv". Also, as we plan to add other stuff there in the future, let's rename also the media uAPI book to media_uapi, to make it clearer. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/media/uapi/rc')
-rw-r--r--Documentation/media/uapi/rc/Remote_controllers_Intro.rst24
-rw-r--r--Documentation/media/uapi/rc/Remote_controllers_table_change.rst18
-rw-r--r--Documentation/media/uapi/rc/Remote_controllers_tables.rst757
-rw-r--r--Documentation/media/uapi/rc/keytable.c.rst176
-rw-r--r--Documentation/media/uapi/rc/lirc_dev_intro.rst28
-rw-r--r--Documentation/media/uapi/rc/lirc_device_interface.rst15
-rw-r--r--Documentation/media/uapi/rc/lirc_ioctl.rst156
-rw-r--r--Documentation/media/uapi/rc/lirc_read.rst19
-rw-r--r--Documentation/media/uapi/rc/lirc_write.rst14
-rw-r--r--Documentation/media/uapi/rc/remote_controllers.rst52
-rw-r--r--Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst143
11 files changed, 1402 insertions, 0 deletions
diff --git a/Documentation/media/uapi/rc/Remote_controllers_Intro.rst b/Documentation/media/uapi/rc/Remote_controllers_Intro.rst
new file mode 100644
index 000000000000..3707c29d37ed
--- /dev/null
+++ b/Documentation/media/uapi/rc/Remote_controllers_Intro.rst
@@ -0,0 +1,24 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_Intro:
+
+************
+Introduction
+************
+
+Currently, most analog and digital devices have a Infrared input for
+remote controllers. Each manufacturer has their own type of control. It
+is not rare for the same manufacturer to ship different types of
+controls, depending on the device.
+
+A Remote Controller interface is mapped as a normal evdev/input
+interface, just like a keyboard or a mouse. So, it uses all ioctls
+already defined for any other input devices.
+
+However, remove controllers are more flexible than a normal input
+device, as the IR receiver (and/or transmitter) can be used in
+conjunction with a wide variety of different IR remotes.
+
+In order to allow flexibility, the Remote Controller subsystem allows
+controlling the RC-specific attributes via
+:ref:`the sysfs class nodes <remote_controllers_sysfs_nodes>`.
diff --git a/Documentation/media/uapi/rc/Remote_controllers_table_change.rst b/Documentation/media/uapi/rc/Remote_controllers_table_change.rst
new file mode 100644
index 000000000000..d604896bca87
--- /dev/null
+++ b/Documentation/media/uapi/rc/Remote_controllers_table_change.rst
@@ -0,0 +1,18 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_table_change:
+
+*******************************************
+Changing default Remote Controller mappings
+*******************************************
+
+The event interface provides two ioctls to be used against the
+/dev/input/event device, to allow changing the default keymapping.
+
+This program demonstrates how to replace the keymap tables.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ keytable.c
diff --git a/Documentation/media/uapi/rc/Remote_controllers_tables.rst b/Documentation/media/uapi/rc/Remote_controllers_tables.rst
new file mode 100644
index 000000000000..0bb16c4af27d
--- /dev/null
+++ b/Documentation/media/uapi/rc/Remote_controllers_tables.rst
@@ -0,0 +1,757 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_tables:
+
+************************
+Remote controller tables
+************************
+
+Unfortunately, for several years, there was no effort to create uniform
+IR keycodes for different devices. This caused the same IR keyname to be
+mapped completely differently on different IR devices. This resulted
+that the same IR keyname to be mapped completely different on different
+IR's. Due to that, V4L2 API now specifies a standard for mapping Media
+keys on IR.
+
+This standard should be used by both V4L/DVB drivers and userspace
+applications
+
+The modules register the remote as keyboard within the linux input
+layer. This means that the IR key strokes will look like normal keyboard
+key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event
+devices (CONFIG_INPUT_EVDEV) it is possible for applications to access
+the remote via /dev/input/event devices.
+
+
+.. _rc_standard_keymap:
+
+.. flat-table:: IR default keymapping
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Key code
+
+ - Meaning
+
+ - Key examples on IR
+
+ - .. row 2
+
+ - **Numeric keys**
+
+ - .. row 3
+
+ - ``KEY_0``
+
+ - Keyboard digit 0
+
+ - 0
+
+ - .. row 4
+
+ - ``KEY_1``
+
+ - Keyboard digit 1
+
+ - 1
+
+ - .. row 5
+
+ - ``KEY_2``
+
+ - Keyboard digit 2
+
+ - 2
+
+ - .. row 6
+
+ - ``KEY_3``
+
+ - Keyboard digit 3
+
+ - 3
+
+ - .. row 7
+
+ - ``KEY_4``
+
+ - Keyboard digit 4
+
+ - 4
+
+ - .. row 8
+
+ - ``KEY_5``
+
+ - Keyboard digit 5
+
+ - 5
+
+ - .. row 9
+
+ - ``KEY_6``
+
+ - Keyboard digit 6
+
+ - 6
+
+ - .. row 10
+
+ - ``KEY_7``
+
+ - Keyboard digit 7
+
+ - 7
+
+ - .. row 11
+
+ - ``KEY_8``
+
+ - Keyboard digit 8
+
+ - 8
+
+ - .. row 12
+
+ - ``KEY_9``
+
+ - Keyboard digit 9
+
+ - 9
+
+ - .. row 13
+
+ - **Movie play control**
+
+ - .. row 14
+
+ - ``KEY_FORWARD``
+
+ - Instantly advance in time
+
+ - >> / FORWARD
+
+ - .. row 15
+
+ - ``KEY_BACK``
+
+ - Instantly go back in time
+
+ - <<< / BACK
+
+ - .. row 16
+
+ - ``KEY_FASTFORWARD``
+
+ - Play movie faster
+
+ - >>> / FORWARD
+
+ - .. row 17
+
+ - ``KEY_REWIND``
+
+ - Play movie back
+
+ - REWIND / BACKWARD
+
+ - .. row 18
+
+ - ``KEY_NEXT``
+
+ - Select next chapter / sub-chapter / interval
+
+ - NEXT / SKIP
+
+ - .. row 19
+
+ - ``KEY_PREVIOUS``
+
+ - Select previous chapter / sub-chapter / interval
+
+ - << / PREV / PREVIOUS
+
+ - .. row 20
+
+ - ``KEY_AGAIN``
+
+ - Repeat the video or a video interval
+
+ - REPEAT / LOOP / RECALL
+
+ - .. row 21
+
+ - ``KEY_PAUSE``
+
+ - Pause sroweam
+
+ - PAUSE / FREEZE
+
+ - .. row 22
+
+ - ``KEY_PLAY``
+
+ - Play movie at the normal timeshift
+
+ - NORMAL TIMESHIFT / LIVE / >
+
+ - .. row 23
+
+ - ``KEY_PLAYPAUSE``
+
+ - Alternate between play and pause
+
+ - PLAY / PAUSE
+
+ - .. row 24
+
+ - ``KEY_STOP``
+
+ - Stop sroweam
+
+ - STOP
+
+ - .. row 25
+
+ - ``KEY_RECORD``
+
+ - Start/stop recording sroweam
+
+ - CAPTURE / REC / RECORD/PAUSE
+
+ - .. row 26
+
+ - ``KEY_CAMERA``
+
+ - Take a picture of the image
+
+ - CAMERA ICON / CAPTURE / SNAPSHOT
+
+ - .. row 27
+
+ - ``KEY_SHUFFLE``
+
+ - Enable shuffle mode
+
+ - SHUFFLE
+
+ - .. row 28
+
+ - ``KEY_TIME``
+
+ - Activate time shift mode
+
+ - TIME SHIFT
+
+ - .. row 29
+
+ - ``KEY_TITLE``
+
+ - Allow changing the chapter
+
+ - CHAPTER
+
+ - .. row 30
+
+ - ``KEY_SUBTITLE``
+
+ - Allow changing the subtitle
+
+ - SUBTITLE
+
+ - .. row 31
+
+ - **Image control**
+
+ - .. row 32
+
+ - ``KEY_BRIGHTNESSDOWN``
+
+ - Decrease Brightness
+
+ - BRIGHTNESS DECREASE
+
+ - .. row 33
+
+ - ``KEY_BRIGHTNESSUP``
+
+ - Increase Brightness
+
+ - BRIGHTNESS INCREASE
+
+ - .. row 34
+
+ - ``KEY_ANGLE``
+
+ - Switch video camera angle (on videos with more than one angle
+ stored)
+
+ - ANGLE / SWAP
+
+ - .. row 35
+
+ - ``KEY_EPG``
+
+ - Open the Elecrowonic Play Guide (EPG)
+
+ - EPG / GUIDE
+
+ - .. row 36
+
+ - ``KEY_TEXT``
+
+ - Activate/change closed caption mode
+
+ - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
+
+ - .. row 37
+
+ - **Audio control**
+
+ - .. row 38
+
+ - ``KEY_AUDIO``
+
+ - Change audio source
+
+ - AUDIO SOURCE / AUDIO / MUSIC
+
+ - .. row 39
+
+ - ``KEY_MUTE``
+
+ - Mute/unmute audio
+
+ - MUTE / DEMUTE / UNMUTE
+
+ - .. row 40
+
+ - ``KEY_VOLUMEDOWN``
+
+ - Decrease volume
+
+ - VOLUME- / VOLUME DOWN
+
+ - .. row 41
+
+ - ``KEY_VOLUMEUP``
+
+ - Increase volume
+
+ - VOLUME+ / VOLUME UP
+
+ - .. row 42
+
+ - ``KEY_MODE``
+
+ - Change sound mode
+
+ - MONO/STEREO
+
+ - .. row 43
+
+ - ``KEY_LANGUAGE``
+
+ - Select Language
+
+ - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
+
+ - .. row 44
+
+ - **Channel control**
+
+ - .. row 45
+
+ - ``KEY_CHANNEL``
+
+ - Go to the next favorite channel
+
+ - ALT / CHANNEL / CH SURFING / SURF / FAV
+
+ - .. row 46
+
+ - ``KEY_CHANNELDOWN``
+
+ - Decrease channel sequencially
+
+ - CHANNEL - / CHANNEL DOWN / DOWN
+
+ - .. row 47
+
+ - ``KEY_CHANNELUP``
+
+ - Increase channel sequencially
+
+ - CHANNEL + / CHANNEL UP / UP
+
+ - .. row 48
+
+ - ``KEY_DIGITS``
+
+ - Use more than one digit for channel
+
+ - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
+
+ - .. row 49
+
+ - ``KEY_SEARCH``
+
+ - Start channel autoscan
+
+ - SCAN / AUTOSCAN
+
+ - .. row 50
+
+ - **Colored keys**
+
+ - .. row 51
+
+ - ``KEY_BLUE``
+
+ - IR Blue key
+
+ - BLUE
+
+ - .. row 52
+
+ - ``KEY_GREEN``
+
+ - IR Green Key
+
+ - GREEN
+
+ - .. row 53
+
+ - ``KEY_RED``
+
+ - IR Red key
+
+ - RED
+
+ - .. row 54
+
+ - ``KEY_YELLOW``
+
+ - IR Yellow key
+
+ - YELLOW
+
+ - .. row 55
+
+ - **Media selection**
+
+ - .. row 56
+
+ - ``KEY_CD``
+
+ - Change input source to Compact Disc
+
+ - CD
+
+ - .. row 57
+
+ - ``KEY_DVD``
+
+ - Change input to DVD
+
+ - DVD / DVD MENU
+
+ - .. row 58
+
+ - ``KEY_EJECTCLOSECD``
+
+ - Open/close the CD/DVD player
+
+ - -> ) / CLOSE / OPEN
+
+ - .. row 59
+
+ - ``KEY_MEDIA``
+
+ - Turn on/off Media application
+
+ - PC/TV / TURN ON/OFF APP
+
+ - .. row 60
+
+ - ``KEY_PC``
+
+ - Selects from TV to PC
+
+ - PC
+
+ - .. row 61
+
+ - ``KEY_RADIO``
+
+ - Put into AM/FM radio mode
+
+ - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
+
+ - .. row 62
+
+ - ``KEY_TV``
+
+ - Select tv mode
+
+ - TV / LIVE TV
+
+ - .. row 63
+
+ - ``KEY_TV2``
+
+ - Select Cable mode
+
+ - AIR/CBL
+
+ - .. row 64
+
+ - ``KEY_VCR``
+
+ - Select VCR mode
+
+ - VCR MODE / DTR
+
+ - .. row 65
+
+ - ``KEY_VIDEO``
+
+ - Alternate between input modes
+
+ - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
+
+ - .. row 66
+
+ - **Power control**
+
+ - .. row 67
+
+ - ``KEY_POWER``
+
+ - Turn on/off computer
+
+ - SYSTEM POWER / COMPUTER POWER
+
+ - .. row 68
+
+ - ``KEY_POWER2``
+
+ - Turn on/off application
+
+ - TV ON/OFF / POWER
+
+ - .. row 69
+
+ - ``KEY_SLEEP``
+
+ - Activate sleep timer
+
+ - SLEEP / SLEEP TIMER
+
+ - .. row 70
+
+ - ``KEY_SUSPEND``
+
+ - Put computer into suspend mode
+
+ - STANDBY / SUSPEND
+
+ - .. row 71
+
+ - **Window control**
+
+ - .. row 72
+
+ - ``KEY_CLEAR``
+
+ - Stop sroweam and return to default input video/audio
+
+ - CLEAR / RESET / BOSS KEY
+
+ - .. row 73
+
+ - ``KEY_CYCLEWINDOWS``
+
+ - Minimize windows and move to the next one
+
+ - ALT-TAB / MINIMIZE / DESKTOP
+
+ - .. row 74
+
+ - ``KEY_FAVORITES``
+
+ - Open the favorites sroweam window
+
+ - TV WALL / Favorites
+
+ - .. row 75
+
+ - ``KEY_MENU``
+
+ - Call application menu
+
+ - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
+
+ - .. row 76
+
+ - ``KEY_NEW``
+
+ - Open/Close Picture in Picture
+
+ - PIP
+
+ - .. row 77
+
+ - ``KEY_OK``
+
+ - Send a confirmation code to application
+
+ - OK / ENTER / RETURN
+
+ - .. row 78
+
+ - ``KEY_SCREEN``
+
+ - Select screen aspect ratio
+
+ - 4:3 16:9 SELECT
+
+ - .. row 79
+
+ - ``KEY_ZOOM``
+
+ - Put device into zoom/full screen mode
+
+ - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
+
+ - .. row 80
+
+ - **Navigation keys**
+
+ - .. row 81
+
+ - ``KEY_ESC``
+
+ - Cancel current operation
+
+ - CANCEL / BACK
+
+ - .. row 82
+
+ - ``KEY_HELP``
+
+ - Open a Help window
+
+ - HELP
+
+ - .. row 83
+
+ - ``KEY_HOMEPAGE``
+
+ - Navigate to Homepage
+
+ - HOME
+
+ - .. row 84
+
+ - ``KEY_INFO``
+
+ - Open On Screen Display
+
+ - DISPLAY INFORMATION / OSD
+
+ - .. row 85
+
+ - ``KEY_WWW``
+
+ - Open the default browser
+
+ - WEB
+
+ - .. row 86
+
+ - ``KEY_UP``
+
+ - Up key
+
+ - UP
+
+ - .. row 87
+
+ - ``KEY_DOWN``
+
+ - Down key
+
+ - DOWN
+
+ - .. row 88
+
+ - ``KEY_LEFT``
+
+ - Left key
+
+ - LEFT
+
+ - .. row 89
+
+ - ``KEY_RIGHT``
+
+ - Right key
+
+ - RIGHT
+
+ - .. row 90
+
+ - **Miscellaneous keys**
+
+ - .. row 91
+
+ - ``KEY_DOT``
+
+ - Return a dot
+
+ - .
+
+ - .. row 92
+
+ - ``KEY_FN``
+
+ - Select a function
+
+ - FUNCTION
+
+
+It should be noted that, sometimes, there some fundamental missing keys
+at some cheaper IR's. Due to that, it is recommended to:
+
+
+.. _rc_keymap_notes:
+
+.. flat-table:: Notes
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - On simpler IR's, without separate channel keys, you need to map UP
+ as ``KEY_CHANNELUP``
+
+ - .. row 2
+
+ - On simpler IR's, without separate channel keys, you need to map
+ DOWN as ``KEY_CHANNELDOWN``
+
+ - .. row 3
+
+ - On simpler IR's, without separate volume keys, you need to map
+ LEFT as ``KEY_VOLUMEDOWN``
+
+ - .. row 4
+
+ - On simpler IR's, without separate volume keys, you need to map
+ RIGHT as ``KEY_VOLUMEUP``
diff --git a/Documentation/media/uapi/rc/keytable.c.rst b/Documentation/media/uapi/rc/keytable.c.rst
new file mode 100644
index 000000000000..e6ce1e3f5a78
--- /dev/null
+++ b/Documentation/media/uapi/rc/keytable.c.rst
@@ -0,0 +1,176 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+file: uapi/v4l/keytable.c
+=========================
+
+.. code-block:: c
+
+ /* keytable.c - This program allows checking/replacing keys at IR
+
+ Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, version 2 of the License.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+ */
+
+ #include <ctype.h>
+ #include <errno.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <linux/input.h>
+ #include <sys/ioctl.h>
+
+ #include "parse.h"
+
+ void prtcode (int *codes)
+ {
+ struct parse_key *p;
+
+ for (p=keynames;p->name!=NULL;p++) {
+ if (p->value == (unsigned)codes[1]) {
+ printf("scancode 0x%04x = %s (0x%02x)\\n", codes[0], p->name, codes[1]);
+ return;
+ }
+ }
+
+ if (isprint (codes[1]))
+ printf("scancode %d = '%c' (0x%02x)\\n", codes[0], codes[1], codes[1]);
+ else
+ printf("scancode %d = 0x%02x\\n", codes[0], codes[1]);
+ }
+
+ int parse_code(char *string)
+ {
+ struct parse_key *p;
+
+ for (p=keynames;p->name!=NULL;p++) {
+ if (!strcasecmp(p->name, string)) {
+ return p->value;
+ }
+ }
+ return -1;
+ }
+
+ int main (int argc, char *argv[])
+ {
+ int fd;
+ unsigned int i, j;
+ int codes[2];
+
+ if (argc<2 || argc>4) {
+ printf ("usage: %s <device> to get table; or\\n"
+ " %s <device> <scancode> <keycode>\\n"
+ " %s <device> <keycode_file>n",*argv,*argv,*argv);
+ return -1;
+ }
+
+ if ((fd = open(argv[1], O_RDONLY)) < 0) {
+ perror("Couldn't open input device");
+ return(-1);
+ }
+
+ if (argc==4) {
+ int value;
+
+ value=parse_code(argv[3]);
+
+ if (value==-1) {
+ value = strtol(argv[3], NULL, 0);
+ if (errno)
+ perror("value");
+ }
+
+ codes [0] = (unsigned) strtol(argv[2], NULL, 0);
+ codes [1] = (unsigned) value;
+
+ if(ioctl(fd, EVIOCSKEYCODE, codes))
+ perror ("EVIOCSKEYCODE");
+
+ if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
+ prtcode(codes);
+ return 0;
+ }
+
+ if (argc==3) {
+ FILE *fin;
+ int value;
+ char *scancode, *keycode, s[2048];
+
+ fin=fopen(argv[2],"r");
+ if (fin==NULL) {
+ perror ("opening keycode file");
+ return -1;
+ }
+
+ /* Clears old table */
+ for (j = 0; j < 256; j++) {
+ for (i = 0; i < 256; i++) {
+ codes[0] = (j << 8) | i;
+ codes[1] = KEY_RESERVED;
+ ioctl(fd, EVIOCSKEYCODE, codes);
+ }
+ }
+
+ while (fgets(s,sizeof(s),fin)) {
+ scancode=strtok(s,"\\n\\t =:");
+ if (!scancode) {
+ perror ("parsing input file scancode");
+ return -1;
+ }
+ if (!strcasecmp(scancode, "scancode")) {
+ scancode = strtok(NULL,"\\n\\t =:");
+ if (!scancode) {
+ perror ("parsing input file scancode");
+ return -1;
+ }
+ }
+
+ keycode=strtok(NULL,"\\n\\t =:(");
+ if (!keycode) {
+ perror ("parsing input file keycode");
+ return -1;
+ }
+
+ // printf ("parsing %s=%s:", scancode, keycode);
+ value=parse_code(keycode);
+ // printf ("\\tvalue=%d\\n",value);
+
+ if (value==-1) {
+ value = strtol(keycode, NULL, 0);
+ if (errno)
+ perror("value");
+ }
+
+ codes [0] = (unsigned) strtol(scancode, NULL, 0);
+ codes [1] = (unsigned) value;
+
+ // printf("\\t%04x=%04x\\n",codes[0], codes[1]);
+ if(ioctl(fd, EVIOCSKEYCODE, codes)) {
+ fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
+ perror ("EVIOCSKEYCODE");
+ }
+
+ if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
+ prtcode(codes);
+ }
+ return 0;
+ }
+
+ /* Get scancode table */
+ for (j = 0; j < 256; j++) {
+ for (i = 0; i < 256; i++) {
+ codes[0] = (j << 8) | i;
+ if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED)
+ prtcode(codes);
+ }
+ }
+ return 0;
+ }
diff --git a/Documentation/media/uapi/rc/lirc_dev_intro.rst b/Documentation/media/uapi/rc/lirc_dev_intro.rst
new file mode 100644
index 000000000000..9a784c8fe4ea
--- /dev/null
+++ b/Documentation/media/uapi/rc/lirc_dev_intro.rst
@@ -0,0 +1,28 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_dev_intro:
+
+************
+Introduction
+************
+
+The LIRC device interface is a bi-directional interface for transporting
+raw IR data between userspace and kernelspace. Fundamentally, it is just
+a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard
+struct file_operations defined on it. With respect to transporting raw
+IR data to and fro, the essential fops are read, write and ioctl.
+
+Example dmesg output upon a driver registering w/LIRC:
+
+.. code-block:: none
+
+ $ dmesg |grep lirc_dev
+ lirc_dev: IR Remote Control driver registered, major 248
+ rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0
+
+What you should see for a chardev:
+
+.. code-block:: none
+
+ $ ls -l /dev/lirc*
+ crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
diff --git a/Documentation/media/uapi/rc/lirc_device_interface.rst b/Documentation/media/uapi/rc/lirc_device_interface.rst
new file mode 100644
index 000000000000..a0c27ed5ad73
--- /dev/null
+++ b/Documentation/media/uapi/rc/lirc_device_interface.rst
@@ -0,0 +1,15 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_dev:
+
+LIRC Device Interface
+=====================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ lirc_dev_intro
+ lirc_read
+ lirc_write
+ lirc_ioctl
diff --git a/Documentation/media/uapi/rc/lirc_ioctl.rst b/Documentation/media/uapi/rc/lirc_ioctl.rst
new file mode 100644
index 000000000000..916d064476f1
--- /dev/null
+++ b/Documentation/media/uapi/rc/lirc_ioctl.rst
@@ -0,0 +1,156 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_ioctl:
+
+**************
+LIRC ioctl fop
+**************
+
+The LIRC device's ioctl definition is bound by the ioctl function
+definition of struct file_operations, leaving us with an unsigned int
+for the ioctl command and an unsigned long for the arg. For the purposes
+of ioctl portability across 32-bit and 64-bit, these values are capped
+to their 32-bit sizes.
+
+The following ioctls can be used to change specific hardware settings.
+In general each driver should have a default set of settings. The driver
+implementation is expected to re-apply the default settings when the
+device is closed by user-space, so that every application opening the
+device can rely on working with the default settings initially.
+
+LIRC_GET_FEATURES
+ Obviously, get the underlying hardware device's features. If a
+ driver does not announce support of certain features, calling of the
+ corresponding ioctls is undefined.
+
+LIRC_GET_SEND_MODE
+ Get supported transmit mode. Only LIRC_MODE_PULSE is supported by
+ lircd.
+
+LIRC_GET_REC_MODE
+ Get supported receive modes. Only LIRC_MODE_MODE2 and
+ LIRC_MODE_LIRCCODE are supported by lircd.
+
+LIRC_GET_SEND_CARRIER
+ Get carrier frequency (in Hz) currently used for transmit.
+
+LIRC_GET_REC_CARRIER
+ Get carrier frequency (in Hz) currently used for IR reception.
+
+LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE
+ Get/set the duty cycle (from 0 to 100) of the carrier signal.
+ Currently, no special meaning is defined for 0 or 100, but this
+ could be used to switch off carrier generation in the future, so
+ these values should be reserved.
+
+LIRC_GET_REC_RESOLUTION
+ Some receiver have maximum resolution which is defined by internal
+ sample rate or data format limitations. E.g. it's common that
+ signals can only be reported in 50 microsecond steps. This integer
+ value is used by lircd to automatically adjust the aeps tolerance
+ value in the lircd config file.
+
+LIRC_GET_M{IN,AX}_TIMEOUT
+ Some devices have internal timers that can be used to detect when
+ there's no IR activity for a long time. This can help lircd in
+ detecting that a IR signal is finished and can speed up the decoding
+ process. Returns an integer value with the minimum/maximum timeout
+ that can be set. Some devices have a fixed timeout, in that case
+ both ioctls will return the same value even though the timeout
+ cannot be changed.
+
+LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}
+ Some devices are able to filter out spikes in the incoming signal
+ using given filter rules. These ioctls return the hardware
+ capabilities that describe the bounds of the possible filters.
+ Filter settings depend on the IR protocols that are expected. lircd
+ derives the settings from all protocols definitions found in its
+ config file.
+
+LIRC_GET_LENGTH
+ Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
+ Reads on the device must be done in blocks matching the bit count.
+ The bit could should be rounded up so that it matches full bytes.
+
+LIRC_SET_{SEND,REC}_MODE
+ Set send/receive mode. Largely obsolete for send, as only
+ LIRC_MODE_PULSE is supported.
+
+LIRC_SET_{SEND,REC}_CARRIER
+ Set send/receive carrier (in Hz).
+
+LIRC_SET_TRANSMITTER_MASK
+ This enables the given set of transmitters. The first transmitter is
+ encoded by the least significant bit, etc. When an invalid bit mask
+ is given, i.e. a bit is set, even though the device does not have so
+ many transitters, then this ioctl returns the number of available
+ transitters and does nothing otherwise.
+
+LIRC_SET_REC_TIMEOUT
+ Sets the integer value for IR inactivity timeout (cf.
+ LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0
+ (if supported by the hardware) disables all hardware timeouts and
+ data should be reported as soon as possible. If the exact value
+ cannot be set, then the next possible value _greater_ than the
+ given value should be set.
+
+LIRC_SET_REC_TIMEOUT_REPORTS
+ Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
+ default, timeout reports should be turned off.
+
+LIRC_SET_REC_FILTER_{,PULSE,SPACE}
+ Pulses/spaces shorter than this are filtered out by hardware. If
+ filters cannot be set independently for pulse/space, the
+ corresponding ioctls must return an error and LIRC_SET_REC_FILTER
+ shall be used instead.
+
+LIRC_SET_MEASURE_CARRIER_MODE
+ Enable (1)/disable (0) measure mode. If enabled, from the next key
+ press on, the driver will send LIRC_MODE2_FREQUENCY packets. By
+ default this should be turned off.
+
+LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE
+ To set a range use
+ LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
+ with the lower bound first and later
+ LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper
+ bound.
+
+LIRC_NOTIFY_DECODE
+ This ioctl is called by lircd whenever a successful decoding of an
+ incoming IR signal could be done. This can be used by supporting
+ hardware to give visual feedback to the user e.g. by flashing a LED.
+
+LIRC_SETUP_{START,END}
+ Setting of several driver parameters can be optimized by
+ encapsulating the according ioctl calls with
+ LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a
+ LIRC_SETUP_START ioctl it can choose to not commit further setting
+ changes to the hardware until a LIRC_SETUP_END is received. But
+ this is open to the driver implementation and every driver must also
+ handle parameter changes which are not encapsulated by
+ LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to
+ ignore these ioctls.
+
+LIRC_SET_WIDEBAND_RECEIVER
+ Some receivers are equipped with special wide band receiver which is
+ intended to be used to learn output of existing remote. Calling that
+ ioctl with (1) will enable it, and with (0) disable it. This might
+ be useful of receivers that have otherwise narrow band receiver that
+ prevents them to be used with some remotes. Wide band receiver might
+ also be more precise On the other hand its disadvantage it usually
+ reduced range of reception. Note: wide band receiver might be
+ implictly enabled if you enable carrier reports. In that case it
+ will be disabled as soon as you disable carrier reports. Trying to
+ disable wide band receiver while carrier reports are active will do
+ nothing.
+
+
+.. _lirc_dev_errors:
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/rc/lirc_read.rst b/Documentation/media/uapi/rc/lirc_read.rst
new file mode 100644
index 000000000000..b0b76c3d1d9a
--- /dev/null
+++ b/Documentation/media/uapi/rc/lirc_read.rst
@@ -0,0 +1,19 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_read:
+
+*************
+LIRC read fop
+*************
+
+The lircd userspace daemon reads raw IR data from the LIRC chardev. The
+exact format of the data depends on what modes a driver supports, and
+what mode has been selected. lircd obtains supported modes and sets the
+active mode via the ioctl interface, detailed at :ref:`lirc_ioctl`.
+The generally preferred mode is LIRC_MODE_MODE2, in which packets
+containing an int value describing an IR signal are read from the
+chardev.
+
+See also
+`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__
+for more info.
diff --git a/Documentation/media/uapi/rc/lirc_write.rst b/Documentation/media/uapi/rc/lirc_write.rst
new file mode 100644
index 000000000000..d19cb486ecc9
--- /dev/null
+++ b/Documentation/media/uapi/rc/lirc_write.rst
@@ -0,0 +1,14 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_write:
+
+**************
+LIRC write fop
+**************
+
+The data written to the chardev is a pulse/space sequence of integer
+values. Pulses and spaces are only marked implicitly by their position.
+The data must start and end with a pulse, therefore, the data must
+always include an uneven number of samples. The write function must
+block until the data has been transmitted by the hardware. If more data
+is provided than the hardware can send, the driver returns ``EINVAL``.
diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst
new file mode 100644
index 000000000000..bccceb1e28c3
--- /dev/null
+++ b/Documentation/media/uapi/rc/remote_controllers.rst
@@ -0,0 +1,52 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+
+.. _remotes:
+
+#####################
+Remote Controller API
+#####################
+
+.. _remote_controllers:
+
+******************
+Remote Controllers
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+ :numbered:
+
+ Remote_controllers_Intro
+ remote_controllers_sysfs_nodes
+ Remote_controllers_tables
+ Remote_controllers_table_change
+ lirc_device_interface
+
+
+**********************
+Revision and Copyright
+**********************
+
+Authors:
+
+- Carvalho Chehab, Mauro <mchehab@kernel.org>
+
+ - Initial version.
+
+**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab
+
+****************
+Revision History
+****************
+
+:revision: 3.15 / 2014-02-06 (*mcc*)
+
+Added the interface description and the RC sysfs class description.
+
+
+:revision: 1.0 / 2009-09-06 (*mcc*)
+
+Initial revision
diff --git a/Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst b/Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst
new file mode 100644
index 000000000000..6fb944fe21fd
--- /dev/null
+++ b/Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst
@@ -0,0 +1,143 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _remote_controllers_sysfs_nodes:
+
+*******************************
+Remote Controller's sysfs nodes
+*******************************
+
+As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are
+the sysfs nodes that control the Remote Controllers:
+
+
+.. _sys_class_rc:
+
+/sys/class/rc/
+==============
+
+The ``/sys/class/rc/`` class sub-directory belongs to the Remote
+Controller core and provides a sysfs interface for configuring infrared
+remote controller receivers.
+
+
+.. _sys_class_rc_rcN:
+
+/sys/class/rc/rcN/
+==================
+
+A ``/sys/class/rc/rcN`` directory is created for each remote control
+receiver device where N is the number of the receiver.
+
+
+.. _sys_class_rc_rcN_protocols:
+
+/sys/class/rc/rcN/protocols
+===========================
+
+Reading this file returns a list of available protocols, something like:
+
+``rc5 [rc6] nec jvc [sony]``
+
+Enabled protocols are shown in [] brackets.
+
+Writing "+proto" will add a protocol to the list of enabled protocols.
+
+Writing "-proto" will remove a protocol from the list of enabled
+protocols.
+
+Writing "proto" will enable only "proto".
+
+Writing "none" will disable all protocols.
+
+Write fails with ``EINVAL`` if an invalid protocol combination or unknown
+protocol name is used.
+
+
+.. _sys_class_rc_rcN_filter:
+
+/sys/class/rc/rcN/filter
+========================
+
+Sets the scancode filter expected value.
+
+Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the
+expected value of the bits set in the filter mask. If the hardware
+supports it then scancodes which do not match the filter will be
+ignored. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the current protocol is altered.
+
+
+.. _sys_class_rc_rcN_filter_mask:
+
+/sys/class/rc/rcN/filter_mask
+=============================
+
+Sets the scancode filter mask of bits to compare. Use in combination
+with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which
+should be compared against the expected value. A value of 0 disables the
+filter to allow all valid scancodes to be processed.
+
+If the hardware supports it then scancodes which do not match the filter
+will be ignored. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the current protocol is altered.
+
+
+.. _sys_class_rc_rcN_wakeup_protocols:
+
+/sys/class/rc/rcN/wakeup_protocols
+==================================
+
+Reading this file returns a list of available protocols to use for the
+wakeup filter, something like:
+
+``rc5 rc6 nec jvc [sony]``
+
+The enabled wakeup protocol is shown in [] brackets.
+
+Writing "+proto" will add a protocol to the list of enabled wakeup
+protocols.
+
+Writing "-proto" will remove a protocol from the list of enabled wakeup
+protocols.
+
+Writing "proto" will use "proto" for wakeup events.
+
+Writing "none" will disable wakeup.
+
+Write fails with ``EINVAL`` if an invalid protocol combination or unknown
+protocol name is used, or if wakeup is not supported by the hardware.
+
+
+.. _sys_class_rc_rcN_wakeup_filter:
+
+/sys/class/rc/rcN/wakeup_filter
+===============================
+
+Sets the scancode wakeup filter expected value. Use in combination with
+``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of
+the bits set in the wakeup filter mask to trigger a system wake event.
+
+If the hardware supports it and wakeup_filter_mask is not 0 then
+scancodes which match the filter will wake the system from e.g. suspend
+to RAM or power off. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the wakeup protocol is altered.
+
+
+.. _sys_class_rc_rcN_wakeup_filter_mask:
+
+/sys/class/rc/rcN/wakeup_filter_mask
+====================================
+
+Sets the scancode wakeup filter mask of bits to compare. Use in
+combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of
+the scancode which should be compared against the expected value to
+trigger a system wake event.
+
+If the hardware supports it and wakeup_filter_mask is not 0 then
+scancodes which match the filter will wake the system from e.g. suspend
+to RAM or power off. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the wakeup protocol is altered.