thunderbolt: Fix NULL dereference in tb_remove_work()grafted

There is a slight race between tb_remove_work() and tb_domain_remove()
which leads to dereferencing a NULL tb->root_switch pointer inside
tb_free_unplugged_xdomains():

        Thread A                            Thread B

  tb_remove_work()
                                    tb_domain_remove()
                                      mutex_lock(&tb->lock)
                                      tb_stop()
                                        /* doesn't cancel a running callback */
                                        cancel_delayed_work(&tcm->remove_work)
                                        ...
                                        tb_switch_remove(tb->root_switch)
                                        tb->root_switch = NULL
                                      mutex_unlock(&tb->lock)
    mutex_lock(&tb->lock)
    ...
    /* without checking ->root_switch */
    tb_free_unplugged_xdomains(tb->root_switch)
    mutex_unlock(&tb->lock)

Commit a8937f35cf39 ("thunderbolt: Remove XDomain from the bus without
holding tb->lock") doesn't seem right to move tb_free_unplugged_xdomains()
out of the &tb->lock section and the check for tb->root_switch, in
particular.  It states:

  For this reason separate removing the XDomain from the topology data
  structures (where we need the lock) from unregistering the device from
  the bus (where remove callbacks of the drivers are being called).

tb_free_unplugged_xdomains() belongs to the former group of functions
requiring the lock.  And it also calls tb_xdomain_remove() which should
only be called with &tb->lock held.

Found by Linux Verification Center (linuxtesting.org) with Svace static
analysis tool.

Fixes: a8937f35cf39 ("thunderbolt: Remove XDomain from the bus without holding tb->lock")
Cc: stable@vger.kernel.org
Signed-off-by: Fedor Pchelkin <pchelkin@ispras.ru>
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>

27 files changed, 2890 insertions, 0 deletions

diff --git a/Documentation/userspace-api/media/rc/keytable.c.rst b/Documentation/userspace-api/media/rc/keytable.c.rst
new file mode 100644
index 000000000..243e02d26
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/keytable.c.rst
@@ -0,0 +1,176 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+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@kernel.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/userspace-api/media/rc/lirc-dev-intro.rst b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst
new file mode 100644
index 000000000..d899331b9
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst
@@ -0,0 +1,176 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _lirc_dev_intro:
+
+************
+Introduction
+************
+
+LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
+a bi-directional interface for transporting raw IR and decoded scancodes
+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 and
+decoded scancodes to and fro, the essential fops are read, write and ioctl.
+
+It is also possible to attach a BPF program to a LIRC device for decoding
+raw IR into scancodes.
+
+Example dmesg output upon a driver registering w/LIRC:
+
+.. code-block:: none
+
+    $ dmesg |grep lirc_dev
+    rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter
+
+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
+
+Note that the package `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_
+contains tools for working with LIRC devices:
+
+ - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC
+   device features.
+
+ - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load
+   BPF IR decoders and test IR decoding. Some BPF IR decoders are also
+   provided.
+
+.. _lirc_modes:
+
+**********
+LIRC modes
+**********
+
+LIRC supports some modes of receiving and sending IR codes, as shown
+on the following table.
+
+.. _lirc-mode-scancode:
+.. _lirc-scancode-flag-toggle:
+.. _lirc-scancode-flag-repeat:
+
+``LIRC_MODE_SCANCODE``
+
+    This mode is for both sending and receiving IR.
+
+    For transmitting (aka sending), create a struct lirc_scancode with
+    the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
+    set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
+    members set to 0. Write this struct to the lirc device.
+
+    For receiving, you read struct lirc_scancode from the LIRC device.
+    The ``scancode`` field is set to the received scancode and the
+    :ref:`IR protocol <Remote_controllers_Protocols>` is set in
+    :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
+    in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
+
+    The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle
+    bit is set in protocols that support it (e.g. rc-5 and rc-6), or
+    ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols
+    that support it (e.g. nec).
+
+    In the Sanyo and NEC protocol, if you hold a button on remote, rather than
+    repeating the entire scancode, the remote sends a shorter message with
+    no scancode, which just means button is held, a "repeat". When this is
+    received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and
+    keycode is repeated.
+
+    With nec, there is no way to distinguish "button hold" from "repeatedly
+    pressing the same button". The rc-5 and rc-6 protocols have a toggle bit.
+    When a button is released and pressed again, the toggle bit is inverted.
+    If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set.
+
+    The ``timestamp`` field is filled with the time nanoseconds
+    (in ``CLOCK_MONOTONIC``) when the scancode was decoded.
+
+.. _lirc-mode-mode2:
+
+``LIRC_MODE_MODE2``
+
+    The driver returns a sequence of pulse and space codes to userspace,
+    as a series of u32 values.
+
+    This mode is used only for IR receive.
+
+    The upper 8 bits determine the packet type, and the lower 24 bits
+    the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
+    the macro ``LIRC_MODE2()`` will give you the type, which
+    is one of:
+
+    ``LIRC_MODE2_PULSE``
+
+        Signifies the presence of IR in microseconds, also known as *flash*.
+
+    ``LIRC_MODE2_SPACE``
+
+        Signifies absence of IR in microseconds, also known as *gap*.
+
+    ``LIRC_MODE2_FREQUENCY``
+
+        If measurement of the carrier frequency was enabled with
+        :ref:`lirc_set_measure_carrier_mode` then this packet gives you
+        the carrier frequency in Hertz.
+
+    ``LIRC_MODE2_TIMEOUT``
+
+        When the timeout set with :ref:`lirc_set_rec_timeout` expires due
+        to no IR being detected, this packet will be sent, with the number
+        of microseconds with no IR.
+
+    ``LIRC_MODE2_OVERFLOW``
+
+        Signifies that the IR receiver encounter an overflow, and some IR
+        is missing. The IR data after this should be correct again. The
+        actual value is not important, but this is set to 0xffffff by the
+        kernel for compatibility with lircd.
+
+.. _lirc-mode-pulse:
+
+``LIRC_MODE_PULSE``
+
+    In pulse mode, a sequence of pulse/space integer values are written to the
+    lirc device using :ref:`lirc-write`.
+
+    The values are alternating pulse and space lengths, in microseconds. The
+    first and last entry must be a pulse, so there must be an odd number
+    of entries.
+
+    This mode is used only for IR send.
+
+*************************************
+Data types used by LIRC_MODE_SCANCODE
+*************************************
+
+.. kernel-doc:: include/uapi/linux/lirc.h
+    :identifiers: lirc_scancode rc_proto
+
+********************
+BPF based IR decoder
+********************
+
+The kernel has support for decoding the most common
+:ref:`IR protocols <Remote_controllers_Protocols>`, but there
+are many protocols which are not supported. To support these, it is possible
+to load an BPF program which does the decoding. This can only be done on
+LIRC devices which support reading raw IR.
+
+First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument,
+program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached
+to the LIRC device, this program will be called for each pulse, space or
+timeout event on the LIRC device. The context for the BPF program is a
+pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
+value. When the program has decoded the scancode, it can be submitted using
+the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer
+movements can be reported using ``bpf_rc_pointer_rel()``.
+
+Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF
+program, it can be attached to the LIRC device using the `bpf(2)`_ syscall.
+The target must be the file descriptor for the LIRC device, and the
+attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be
+attached to a single LIRC device at a time.
+
+.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
diff --git a/Documentation/userspace-api/media/rc/lirc-dev.rst b/Documentation/userspace-api/media/rc/lirc-dev.rst
new file mode 100644
index 000000000..978f86d30
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-dev.rst
@@ -0,0 +1,14 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _lirc_dev:
+
+LIRC Device Interface
+=====================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    lirc-dev-intro
+    lirc-func
+    lirc-header
diff --git a/Documentation/userspace-api/media/rc/lirc-func.rst b/Documentation/userspace-api/media/rc/lirc-func.rst
new file mode 100644
index 000000000..5c84888f1
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-func.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _lirc_func:
+
+LIRC Function Reference
+=======================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    lirc-read
+    lirc-write
+    lirc-get-features
+    lirc-get-send-mode
+    lirc-get-rec-mode
+    lirc-get-rec-resolution
+    lirc-set-send-duty-cycle
+    lirc-get-timeout
+    lirc-set-rec-timeout
+    lirc-set-rec-carrier
+    lirc-set-rec-carrier-range
+    lirc-set-send-carrier
+    lirc-set-transmitter-mask
+    lirc-set-measure-carrier-mode
+    lirc-set-wideband-receiver
diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst
new file mode 100644
index 000000000..545137620
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst
@@ -0,0 +1,174 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_get_features:
+
+***********************
+ioctl LIRC_GET_FEATURES
+***********************
+
+Name
+====
+
+LIRC_GET_FEATURES - Get the underlying hardware device's features
+
+Synopsis
+========
+
+.. c:macro:: LIRC_GET_FEATURES
+
+``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``features``
+    Bitmask with the LIRC features.
+
+Description
+===========
+
+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 features
+=============
+
+.. _LIRC-CAN-REC-RAW:
+
+``LIRC_CAN_REC_RAW``
+
+    Unused. Kept just to avoid breaking uAPI.
+
+.. _LIRC-CAN-REC-PULSE:
+
+``LIRC_CAN_REC_PULSE``
+
+    Unused. Kept just to avoid breaking uAPI.
+    :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` can only be used for transmitting.
+
+.. _LIRC-CAN-REC-MODE2:
+
+``LIRC_CAN_REC_MODE2``
+
+    This is raw IR driver for receiving. This means that
+    :ref:`LIRC_MODE_MODE2 <lirc-mode-MODE2>` is used. This also implies
+    that :ref:`LIRC_MODE_SCANCODE <lirc-mode-SCANCODE>` is also supported,
+    as long as the kernel is recent enough. Use the
+    :ref:`lirc_set_rec_mode` to switch modes.
+
+.. _LIRC-CAN-REC-LIRCCODE:
+
+``LIRC_CAN_REC_LIRCCODE``
+
+    Unused. Kept just to avoid breaking uAPI.
+
+.. _LIRC-CAN-REC-SCANCODE:
+
+``LIRC_CAN_REC_SCANCODE``
+
+    This is a scancode driver for receiving. This means that
+    :ref:`LIRC_MODE_SCANCODE <lirc-mode-SCANCODE>` is used.
+
+.. _LIRC-CAN-SET-SEND-CARRIER:
+
+``LIRC_CAN_SET_SEND_CARRIER``
+
+    The driver supports changing the modulation frequency via
+    :ref:`ioctl LIRC_SET_SEND_CARRIER <LIRC_SET_SEND_CARRIER>`.
+
+.. _LIRC-CAN-SET-SEND-DUTY-CYCLE:
+
+``LIRC_CAN_SET_SEND_DUTY_CYCLE``
+
+    The driver supports changing the duty cycle using
+    :ref:`ioctl LIRC_SET_SEND_DUTY_CYCLE <LIRC_SET_SEND_DUTY_CYCLE>`.
+
+.. _LIRC-CAN-SET-TRANSMITTER-MASK:
+
+``LIRC_CAN_SET_TRANSMITTER_MASK``
+
+    The driver supports changing the active transmitter(s) using
+    :ref:`ioctl LIRC_SET_TRANSMITTER_MASK <LIRC_SET_TRANSMITTER_MASK>`.
+
+.. _LIRC-CAN-SET-REC-CARRIER:
+
+``LIRC_CAN_SET_REC_CARRIER``
+
+    The driver supports setting the receive carrier frequency using
+    :ref:`ioctl LIRC_SET_REC_CARRIER <LIRC_SET_REC_CARRIER>`.
+
+.. _LIRC-CAN-SET-REC-CARRIER-RANGE:
+
+``LIRC_CAN_SET_REC_CARRIER_RANGE``
+
+    The driver supports
+    :ref:`ioctl LIRC_SET_REC_CARRIER_RANGE <LIRC_SET_REC_CARRIER_RANGE>`.
+
+.. _LIRC-CAN-GET-REC-RESOLUTION:
+
+``LIRC_CAN_GET_REC_RESOLUTION``
+
+    The driver supports
+    :ref:`ioctl LIRC_GET_REC_RESOLUTION <LIRC_GET_REC_RESOLUTION>`.
+
+.. _LIRC-CAN-SET-REC-TIMEOUT:
+
+``LIRC_CAN_SET_REC_TIMEOUT``
+
+    The driver supports
+    :ref:`ioctl LIRC_SET_REC_TIMEOUT <LIRC_SET_REC_TIMEOUT>`.
+
+.. _LIRC-CAN-MEASURE-CARRIER:
+
+``LIRC_CAN_MEASURE_CARRIER``
+
+    The driver supports measuring of the modulation frequency using
+    :ref:`ioctl LIRC_SET_MEASURE_CARRIER_MODE <LIRC_SET_MEASURE_CARRIER_MODE>`.
+
+.. _LIRC-CAN-USE-WIDEBAND-RECEIVER:
+
+``LIRC_CAN_USE_WIDEBAND_RECEIVER``
+
+    The driver supports learning mode using
+    :ref:`ioctl LIRC_SET_WIDEBAND_RECEIVER <LIRC_SET_WIDEBAND_RECEIVER>`.
+
+.. _LIRC-CAN-SEND-RAW:
+
+``LIRC_CAN_SEND_RAW``
+
+    Unused. Kept just to avoid breaking uAPI.
+
+.. _LIRC-CAN-SEND-PULSE:
+
+``LIRC_CAN_SEND_PULSE``
+
+    The driver supports sending (also called as IR blasting or IR TX) using
+    :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`. This implies that
+    :ref:`LIRC_MODE_SCANCODE <lirc-mode-SCANCODE>` is also supported for
+    transmit, as long as the kernel is recent enough. Use the
+    :ref:`lirc_set_send_mode` to switch modes.
+
+.. _LIRC-CAN-SEND-MODE2:
+
+``LIRC_CAN_SEND_MODE2``
+
+    Unused. Kept just to avoid breaking uAPI.
+    :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` can only be used for receiving.
+
+.. _LIRC-CAN-SEND-LIRCCODE:
+
+``LIRC_CAN_SEND_LIRCCODE``
+
+    Unused. Kept just to avoid breaking uAPI.
+
+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/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
new file mode 100644
index 000000000..628fe3179
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst
@@ -0,0 +1,69 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_get_rec_mode:
+.. _lirc_set_rec_mode:
+
+**********************************************
+ioctls LIRC_GET_REC_MODE and LIRC_SET_REC_MODE
+**********************************************
+
+Name
+====
+
+LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_GET_REC_MODE
+
+``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_REC_MODE
+
+``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``mode``
+    Mode used for receive.
+
+Description
+===========
+
+Get and set the current receive mode. Only
+:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` and
+:ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` are supported.
+Use :ref:`lirc_get_features` to find out which modes the driver supports.
+
+Return Value
+============
+
+.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device not available.
+
+    -  .. row 2
+
+       -  ``ENOTTY``
+
+       -  Device does not support receiving.
+
+    -  .. row 3
+
+       -  ``EINVAL``
+
+       -  Invalid mode or invalid mode for this device.
diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
new file mode 100644
index 000000000..4dfa9c236
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_get_rec_resolution:
+
+*****************************
+ioctl LIRC_GET_REC_RESOLUTION
+*****************************
+
+Name
+====
+
+LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microseconds.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_GET_REC_RESOLUTION
+
+``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``microseconds``
+    Resolution, in microseconds.
+
+Description
+===========
+
+Some receivers 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 ioctl returns the integer value with such resolution, with can be
+used by userspace applications like lircd to automatically adjust the
+tolerance value.
+
+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/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
new file mode 100644
index 000000000..637871805
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst
@@ -0,0 +1,71 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_get_send_mode:
+.. _lirc_set_send_mode:
+
+************************************************
+ioctls LIRC_GET_SEND_MODE and LIRC_SET_SEND_MODE
+************************************************
+
+Name
+====
+
+LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_GET_SEND_MODE
+
+``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)``
+
+.. c:macro:: LIRC_SET_SEND_MODE
+
+``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``mode``
+    The mode used for transmitting.
+
+Description
+===========
+
+Get/set current transmit mode.
+
+Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` and
+:ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` are supported by for IR send,
+depending on the driver. Use :ref:`lirc_get_features` to find out which
+modes the driver supports.
+
+Return Value
+============
+
+.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
+
+.. flat-table::
+    :header-rows:  0
+    :stub-columns: 0
+
+    -  .. row 1
+
+       -  ``ENODEV``
+
+       -  Device not available.
+
+    -  .. row 2
+
+       -  ``ENOTTY``
+
+       -  Device does not support transmitting.
+
+    -  .. row 3
+
+       -  ``EINVAL``
+
+       -  Invalid mode or invalid mode for this device.
diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
new file mode 100644
index 000000000..597c3282a
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_get_min_timeout:
+.. _lirc_get_max_timeout:
+
+****************************************************
+ioctls LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT
+****************************************************
+
+Name
+====
+
+LIRC_GET_MIN_TIMEOUT / LIRC_GET_MAX_TIMEOUT - Obtain the possible timeout
+range for IR receive.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_GET_MIN_TIMEOUT
+
+``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_GET_MAX_TIMEOUT
+
+``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``timeout``
+    Timeout, in microseconds.
+
+Description
+===========
+
+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.
+
+.. note::
+
+   Some devices have a fixed timeout, in that case
+   both ioctls will return the same value even though the timeout
+   cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`.
+
+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/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst
new file mode 100644
index 000000000..ba4992625
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-header.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _lirc_header:
+
+*****************
+LIRC uAPI symbols
+*****************
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+
+
+.. kernel-include:: include/uapi/linux/lirc.h
+    :generate-cross-refs:
+    :exception-file: lirc.h.rst.exceptions
+    :toc:
+    :warn-broken:
+
diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst
new file mode 100644
index 000000000..ce3431869
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-read.rst
@@ -0,0 +1,65 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc-read:
+
+***********
+LIRC read()
+***********
+
+Name
+====
+
+lirc-read - Read from a LIRC device
+
+Synopsis
+========
+
+.. code-block:: c
+
+    #include <unistd.h>
+
+.. c:function:: ssize_t read( int fd, void *buf, size_t count )
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by ``open()``.
+
+``buf``
+   Buffer to be filled
+
+``count``
+   Max number of bytes to read
+
+Description
+===========
+
+:c:func:`read()` attempts to read up to ``count`` bytes from file
+descriptor ``fd`` into the buffer starting at ``buf``.  If ``count`` is zero,
+:c:func:`read()` returns zero and has no other results. If ``count``
+is greater than ``SSIZE_MAX``, the result is unspecified.
+
+The exact format of the data depends on what :ref:`lirc_modes` a driver
+uses. Use :ref:`lirc_get_features` to get the supported mode, and use
+:ref:`lirc_set_rec_mode` set the current active mode.
+
+The mode :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` is for raw IR,
+in which packets containing an unsigned int value describing an IR signal are
+read from the chardev.
+
+Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available,
+in this mode scancodes which are either decoded by software decoders, or
+by hardware decoders. The :c:type:`rc_proto` member is set to the
+:ref:`IR protocol <Remote_controllers_Protocols>`
+used for transmission, and ``scancode`` to the decoded scancode,
+and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
+
+Return Value
+============
+
+On success, the number of bytes read is returned. It is not an error if
+this number is smaller than the number of bytes requested, or the amount
+of data required for one frame.  On error, -1 is returned, and the ``errno``
+variable is set appropriately.
diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
new file mode 100644
index 000000000..04ced1aa6
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_measure_carrier_mode:
+
+***********************************
+ioctl LIRC_SET_MEASURE_CARRIER_MODE
+***********************************
+
+Name
+====
+
+LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE
+
+``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``enable``
+    enable = 1 means enable measure mode, enable = 0 means disable measure
+    mode.
+
+Description
+===========
+
+.. _lirc-mode2-frequency:
+
+Enable or disable 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.
+
+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/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
new file mode 100644
index 000000000..7512dc86b
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst
@@ -0,0 +1,49 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_rec_carrier_range:
+
+********************************
+ioctl LIRC_SET_REC_CARRIER_RANGE
+********************************
+
+Name
+====
+
+LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate
+IR receive.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_REC_CARRIER_RANGE
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``frequency``
+    Frequency of the carrier that modulates PWM data, in Hz.
+
+Description
+===========
+
+This ioctl sets the upper range of carrier frequency that will be recognized
+by the IR receiver.
+
+.. note::
+
+   To set a range use :ref:`LIRC_SET_REC_CARRIER_RANGE
+   <LIRC_SET_REC_CARRIER_RANGE>` with the lower bound first and later call
+   :ref:`LIRC_SET_REC_CARRIER <LIRC_SET_REC_CARRIER>` with the upper bound.
+
+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/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
new file mode 100644
index 000000000..60e321446
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_rec_carrier:
+
+**************************
+ioctl LIRC_SET_REC_CARRIER
+**************************
+
+Name
+====
+
+LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_REC_CARRIER
+
+``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``frequency``
+    Frequency of the carrier that modulates PWM data, in Hz.
+
+Description
+===========
+
+Set receive carrier used to modulate IR PWM pulses and spaces.
+
+.. note::
+
+   If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl
+   sets the upper bound frequency that will be recognized by the device.
+
+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/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
new file mode 100644
index 000000000..bf9fb2cc6
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst
@@ -0,0 +1,55 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_rec_timeout:
+.. _lirc_get_rec_timeout:
+
+***************************************************
+ioctl LIRC_GET_REC_TIMEOUT and LIRC_SET_REC_TIMEOUT
+***************************************************
+
+Name
+====
+
+LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR inactivity timeout.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_GET_REC_TIMEOUT
+
+``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)``
+
+.. c:macro:: LIRC_SET_REC_TIMEOUT
+
+``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``timeout``
+    Timeout, in microseconds.
+
+Description
+===========
+
+Get and set the integer value for IR inactivity timeout.
+
+If supported by the hardware, setting it to 0  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.
+
+.. note::
+
+   The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`.
+
+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/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
new file mode 100644
index 000000000..a003f9447
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_send_carrier:
+
+***************************
+ioctl LIRC_SET_SEND_CARRIER
+***************************
+
+Name
+====
+
+LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_SEND_CARRIER
+
+``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``frequency``
+    Frequency of the carrier to be modulated, in Hz.
+
+Description
+===========
+
+Set send carrier used to modulate IR PWM pulses and spaces.
+
+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/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
new file mode 100644
index 000000000..a94750d00
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_send_duty_cycle:
+
+******************************
+ioctl LIRC_SET_SEND_DUTY_CYCLE
+******************************
+
+Name
+====
+
+LIRC_SET_SEND_DUTY_CYCLE - Set the duty cycle of the carrier signal for
+IR transmit.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE
+
+``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``duty_cycle``
+    Duty cycle, describing the pulse width in percent (from 1 to 99) of
+    the total cycle. Values 0 and 100 are reserved.
+
+Description
+===========
+
+Get/set the duty cycle of the carrier signal for IR transmit.
+
+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.
+
+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/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
new file mode 100644
index 000000000..38acbcd6e
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_transmitter_mask:
+
+*******************************
+ioctl LIRC_SET_TRANSMITTER_MASK
+*******************************
+
+Name
+====
+
+LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_TRANSMITTER_MASK
+
+``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``mask``
+    Mask with channels to enable tx. Channel 0 is the least significant bit.
+
+Description
+===========
+
+Some IR TX devices have multiple output channels, in such case,
+:ref:`LIRC_CAN_SET_TRANSMITTER_MASK <LIRC-CAN-SET-TRANSMITTER-MASK>` is
+returned via :ref:`LIRC_GET_FEATURES` and this ioctl sets what channels will
+send IR codes.
+
+This ioctl enables the given set of transmitters. The first transmitter is
+encoded by the least significant bit and so on.
+
+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.
+
+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/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
new file mode 100644
index 000000000..5ae8fac8e
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst
@@ -0,0 +1,56 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc_set_wideband_receiver:
+
+********************************
+ioctl LIRC_SET_WIDEBAND_RECEIVER
+********************************
+
+Name
+====
+
+LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver.
+
+Synopsis
+========
+
+.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER
+
+``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)``
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by open().
+
+``enable``
+    enable = 1 means enable wideband receiver, enable = 0 means disable
+    wideband receiver.
+
+Description
+===========
+
+Some receivers are equipped with special wide band receiver which is
+intended to be used to learn output of existing remote. This ioctl
+allows enabling or disabling 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 implicitly 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.
+
+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/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst
new file mode 100644
index 000000000..970a8b3fa
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc-write.rst
@@ -0,0 +1,72 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. c:namespace:: RC
+
+.. _lirc-write:
+
+************
+LIRC write()
+************
+
+Name
+====
+
+lirc-write - Write to a LIRC device
+
+Synopsis
+========
+
+.. code-block:: c
+
+    #include <unistd.h>
+
+.. c:function:: ssize_t write( int fd, void *buf, size_t count )
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by ``open()``.
+
+``buf``
+    Buffer with data to be written
+
+``count``
+    Number of bytes at the buffer
+
+Description
+===========
+
+:c:func:`write()` writes up to ``count`` bytes to the device
+referenced by the file descriptor ``fd`` from the buffer starting at
+``buf``.
+
+The exact format of the data depends on what mode a driver is in, use
+:ref:`lirc_get_features` to get the supported modes and use
+:ref:`lirc_set_send_mode` set the mode.
+
+When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, 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 blocks until the data has been transmitted
+by the hardware. If more data is provided than the hardware can send, the
+driver returns ``EINVAL``.
+
+When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one
+``struct lirc_scancode`` must be written to the chardev at a time, else
+``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member,
+and the :ref:`IR protocol <Remote_controllers_Protocols>` in the
+:c:type:`rc_proto`: member. All other members must be
+set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
+for the protocol or the scancode is not valid for the specified protocol,
+``EINVAL`` is returned. The write function blocks until the scancode
+is transmitted by the hardware.
+
+Return Value
+============
+
+On success, the number of bytes written is returned. It is not an error if
+this number is smaller than the number of bytes requested, or the amount
+of data required for one frame.  On error, -1 is returned, 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/userspace-api/media/rc/lirc.h.rst.exceptions b/Documentation/userspace-api/media/rc/lirc.h.rst.exceptions
new file mode 100644
index 000000000..1aeb7d7af
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/lirc.h.rst.exceptions
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: GPL-2.0
+
+# Ignore header name
+ignore define _LINUX_LIRC_H
+
+# Ignore helper macros
+
+ignore define lirc_t
+
+ignore define LIRC_SPACE
+ignore define LIRC_PULSE
+ignore define LIRC_FREQUENCY
+ignore define LIRC_TIMEOUT
+ignore define LIRC_OVERFLOW
+ignore define LIRC_VALUE
+ignore define LIRC_MODE2
+ignore define LIRC_IS_SPACE
+ignore define LIRC_IS_PULSE
+ignore define LIRC_IS_FREQUENCY
+ignore define LIRC_IS_TIMEOUT
+ignore define LIRC_IS_OVERFLOW
+
+ignore define LIRC_MODE2SEND
+ignore define LIRC_SEND2MODE
+ignore define LIRC_MODE2REC
+ignore define LIRC_REC2MODE
+
+ignore define LIRC_CAN_SEND
+ignore define LIRC_CAN_REC
+
+ignore define LIRC_CAN_SEND_MASK
+ignore define LIRC_CAN_REC_MASK
+ignore define LIRC_CAN_SET_REC_FILTER
+ignore define LIRC_CAN_NOTIFY_DECODE
+
+# Obsolete ioctls
+
+ignore ioctl LIRC_GET_LENGTH
+ignore ioctl LIRC_SET_REC_TIMEOUT_REPORTS
+
+# rc protocols
+
+ignore symbol RC_PROTO_UNKNOWN
+ignore symbol RC_PROTO_OTHER
+ignore symbol RC_PROTO_RC5
+ignore symbol RC_PROTO_RC5X_20
+ignore symbol RC_PROTO_RC5_SZ
+ignore symbol RC_PROTO_JVC
+ignore symbol RC_PROTO_SONY12
+ignore symbol RC_PROTO_SONY15
+ignore symbol RC_PROTO_SONY20
+ignore symbol RC_PROTO_NEC
+ignore symbol RC_PROTO_NECX
+ignore symbol RC_PROTO_NEC32
+ignore symbol RC_PROTO_SANYO
+ignore symbol RC_PROTO_MCIR2_KBD
+ignore symbol RC_PROTO_MCIR2_MSE
+ignore symbol RC_PROTO_RC6_0
+ignore symbol RC_PROTO_RC6_6A_20
+ignore symbol RC_PROTO_RC6_6A_24
+ignore symbol RC_PROTO_RC6_6A_32
+ignore symbol RC_PROTO_RC6_MCE
+ignore symbol RC_PROTO_SHARP
+ignore symbol RC_PROTO_XMP
+ignore symbol RC_PROTO_CEC
+ignore symbol RC_PROTO_IMON
+ignore symbol RC_PROTO_RCMM12
+ignore symbol RC_PROTO_RCMM24
+ignore symbol RC_PROTO_RCMM32
+ignore symbol RC_PROTO_XBOX_DVD
+ignore symbol RC_PROTO_MAX
+
+# Undocumented macros
+
+ignore define PULSE_BIT
+ignore define PULSE_MASK
+
+ignore define LIRC_MODE2_SPACE
+ignore define LIRC_MODE2_PULSE
+ignore define LIRC_MODE2_TIMEOUT
+ignore define LIRC_MODE2_OVERFLOW
+
+ignore define LIRC_VALUE_MASK
+ignore define LIRC_MODE2_MASK
+
+ignore define LIRC_MODE_RAW
+ignore define LIRC_MODE_LIRCCODE
diff --git a/Documentation/userspace-api/media/rc/rc-intro.rst b/Documentation/userspace-api/media/rc/rc-intro.rst
new file mode 100644
index 000000000..2ba62cde2
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/rc-intro.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _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/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst
new file mode 100644
index 000000000..ec706290c
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/rc-protos.rst
@@ -0,0 +1,454 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _Remote_controllers_Protocols:
+
+*****************************************
+Remote Controller Protocols and Scancodes
+*****************************************
+
+IR is encoded as a series of pulses and spaces, using a protocol. These
+protocols can encode e.g. an address (which device should respond) and a
+command: what it should do. The values for these are not always consistent
+across different devices for a given protocol.
+
+Therefore out the output of the IR decoder is a scancode; a single u32
+value. Using keymap tables this can be mapped to linux key codes.
+
+Other things can be encoded too. Some IR protocols encode a toggle bit; this
+is to distinguish whether the same button is being held down, or has been
+released and pressed again. If has been released and pressed again, the
+toggle bit will invert from one IR message to the next.
+
+Some remotes have a pointer-type device which can used to control the
+mouse; some air conditioning systems can have their target temperature
+target set in IR.
+
+The following are the protocols the kernel knows about and also lists
+how scancodes are encoded for each protocol.
+
+rc-5 (RC_PROTO_RC5)
+-------------------
+
+This IR protocol uses manchester encoding to encode 14 bits. There is a
+detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php.
+
+The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5
+protocol, or the manchester BPF decoder.
+
+.. flat-table:: rc5 bits scancode mapping
+   :widths:       1 1 2
+
+   * - rc-5 bit
+
+     - scancode bit
+
+     - description
+
+   * - 1
+
+     - none
+
+     - Start bit, always set
+
+   * - 1
+
+     - 6 (inverted)
+
+     - 2nd start bit in rc5,  re-used as 6th command bit
+
+   * - 1
+
+     - none
+
+     - Toggle bit
+
+   * - 5
+
+     - 8 to 13
+
+     - Address
+
+   * - 6
+
+     - 0 to 5
+
+     - Command
+
+There is a variant of rc5 called either rc5x or extended rc5
+where there the second stop bit is the 6th command bit, but inverted.
+This is done so it the scancodes and encoding is compatible with existing
+schemes. This bit is stored in bit 6 of the scancode, inverted. This is
+done to keep it compatible with plain rc-5 where there are two start bits.
+
+rc-5-sz (RC_PROTO_RC5_SZ)
+-------------------------
+This is much like rc-5 but one bit longer. The scancode is encoded
+differently.
+
+.. flat-table:: rc-5-sz bits scancode mapping
+   :widths:       1 1 2
+
+   * - rc-5-sz bits
+
+     - scancode bit
+
+     - description
+
+   * - 1
+
+     - none
+
+     - Start bit, always set
+
+   * - 1
+
+     - 13
+
+     - Address bit
+
+   * - 1
+
+     - none
+
+     - Toggle bit
+
+   * - 6
+
+     - 6 to 11
+
+     - Address
+
+   * - 6
+
+     - 0 to 5
+
+     - Command
+
+rc-5x-20 (RC_PROTO_RC5X_20)
+---------------------------
+
+This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space
+after the 8th bit.
+
+.. flat-table:: rc-5x-20 bits scancode mapping
+   :widths:       1 1 2
+
+   * - rc-5-sz bits
+
+     - scancode bit
+
+     - description
+
+   * - 1
+
+     - none
+
+     - Start bit, always set
+
+   * - 1
+
+     - 14
+
+     - Address bit
+
+   * - 1
+
+     - none
+
+     - Toggle bit
+
+   * - 5
+
+     - 16 to 20
+
+     - Address
+
+   * - 6
+
+     - 8 to 13
+
+     - Address
+
+   * - 6
+
+     - 0 to 5
+
+     - Command
+
+
+jvc (RC_PROTO_JVC)
+------------------
+
+The jvc protocol is much like nec, without the inverted values. It is
+described here https://www.sbprojects.net/knowledge/ir/jvc.php.
+
+The scancode is a 16 bits value, where the address is the lower 8 bits
+and the command the higher 8 bits; this is reversed from IR order.
+
+sony-12 (RC_PROTO_SONY12)
+-------------------------
+
+The sony protocol is a pulse-width encoding. There are three variants,
+which just differ in number of bits and scancode encoding.
+
+.. flat-table:: sony-12 bits scancode mapping
+   :widths:       1 1 2
+
+   * - sony-12 bits
+
+     - scancode bit
+
+     - description
+
+   * - 5
+
+     - 16 to 20
+
+     - device
+
+   * - 7
+
+     - 0 to 6
+
+     - function
+
+sony-15 (RC_PROTO_SONY15)
+-------------------------
+
+The sony protocol is a pulse-width encoding. There are three variants,
+which just differ in number of bits and scancode encoding.
+
+.. flat-table:: sony-12 bits scancode mapping
+   :widths:       1 1 2
+
+   * - sony-12 bits
+
+     - scancode bit
+
+     - description
+
+   * - 8
+
+     - 16 to 23
+
+     - device
+
+   * - 7
+
+     - 0 to 6
+
+     - function
+
+sony-20 (RC_PROTO_SONY20)
+-------------------------
+
+The sony protocol is a pulse-width encoding. There are three variants,
+which just differ in number of bits and scancode encoding.
+
+.. flat-table:: sony-20 bits scancode mapping
+   :widths:       1 1 2
+
+   * - sony-20 bits
+
+     - scancode bit
+
+     - description
+
+   * - 5
+
+     - 16 to 20
+
+     - device
+
+   * - 7
+
+     - 0 to 7
+
+     - device
+
+   * - 8
+
+     - 8 to 15
+
+     - extended bits
+
+nec (RC_PROTO_NEC)
+------------------
+
+The nec protocol encodes an 8 bit address and an 8 bit command. It is
+described here https://www.sbprojects.net/knowledge/ir/nec.php. Note
+that the protocol sends least significant bit first.
+
+As a check, the nec protocol sends the address and command twice; the
+second time it is inverted. This is done for verification.
+
+A plain nec IR message has 16 bits; the high 8 bits are the address
+and the low 8 bits are the command.
+
+nec-x (RC_PROTO_NECX)
+---------------------
+
+Extended nec has a 16 bit address and a 8 bit command. This is encoded
+as a 24 bit value as you would expect, with the lower 8 bits the command
+and the upper 16 bits the address.
+
+nec-32 (RC_PROTO_NEC32)
+-----------------------
+
+nec-32 does not send an inverted address or an inverted command; the
+entire message, all 32 bits, are used.
+
+For this to be decoded correctly, the second 8 bits must not be the
+inverted value of the first, and also the last 8 bits must not be the
+inverted value of the third 8 bit value.
+
+The scancode has a somewhat unusual encoding.
+
+.. flat-table:: nec-32 bits scancode mapping
+
+   * - nec-32 bits
+
+     - scancode bit
+
+   * - First 8 bits
+
+     - 16 to 23
+
+   * - Second 8 bits
+
+     - 24 to 31
+
+   * - Third 8 bits
+
+     - 0 to 7
+
+   * - Fourth 8 bits
+
+     - 8 to 15
+
+sanyo (RC_PROTO_SANYO)
+----------------------
+
+The sanyo protocol is like the nec protocol, but with 13 bits address
+rather than 8 bits. Both the address and the command are followed by
+their inverted versions, but these are not present in the scancodes.
+
+Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8
+bits are the command.
+
+mcir2-kbd (RC_PROTO_MCIR2_KBD)
+------------------------------
+
+This protocol is generated by the Microsoft MCE keyboard for keyboard
+events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded.
+
+mcir2-mse (RC_PROTO_MCIR2_MSE)
+------------------------------
+
+This protocol is generated by the Microsoft MCE keyboard for pointer
+events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded.
+
+rc-6-0 (RC_PROTO_RC6_0)
+-----------------------
+
+This is the rc-6 in mode 0. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The scancode is the exact 16 bits as in the protocol. There is also a
+toggle bit.
+
+rc-6-6a-20 (RC_PROTO_RC6_6A_20)
+-------------------------------
+
+This is the rc-6 in mode 6a, 20 bits. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The scancode is the exact 20 bits
+as in the protocol. There is also a toggle bit.
+
+rc-6-6a-24 (RC_PROTO_RC6_6A_24)
+-------------------------------
+
+This is the rc-6 in mode 6a, 24 bits. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The scancode is the exact 24 bits
+as in the protocol. There is also a toggle bit.
+
+rc-6-6a-32 (RC_PROTO_RC6_6A_32)
+-------------------------------
+
+This is the rc-6 in mode 6a, 32 bits. rc-6 is described here
+https://www.sbprojects.net/knowledge/ir/rc6.php.
+The upper 16 bits are the vendor,
+and the lower 16 bits are the vendor-specific bits. This protocol is
+for the non-Microsoft MCE variant (vendor != 0x800f).
+
+
+rc-6-mce (RC_PROTO_RC6_MCE)
+---------------------------
+
+This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor,
+and the lower 16 bits are the vendor-specific bits. This protocol is
+for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the
+protocol itself is ignored, and the 16th bit should be takes as the toggle
+bit.
+
+sharp (RC_PROTO_SHARP)
+----------------------
+
+This is a protocol used by Sharp VCRs, is described here
+https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long
+(40ms) space between the normal and inverted values, and some IR receivers
+cannot decode this.
+
+There is a 5 bit address and a 8 bit command. In the scancode the address is
+in bits 8 to 12, and the command in bits 0 to 7.
+
+xmp (RC_PROTO_XMP)
+------------------
+
+This protocol has several versions and only version 1 is supported. Refer
+to the decoder (ir-xmp-decoder.c) to see how it is encoded.
+
+
+cec (RC_PROTO_CEC)
+------------------
+
+This is not an IR protocol, this is a protocol over CEC. The CEC
+infrastructure uses rc-core for handling CEC commands, so that they
+can easily be remapped.
+
+imon (RC_PROTO_IMON)
+--------------------
+
+This protocol is used by Antec Veris/SoundGraph iMON remotes.
+
+The protocol
+describes both button presses and pointer movements. The protocol encodes
+31 bits, and the scancode is simply the 31 bits with the top bit always 0.
+
+rc-mm-12 (RC_PROTO_RCMM12)
+--------------------------
+
+The rc-mm protocol is described here
+https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
+the 12 bits.
+
+rc-mm-24 (RC_PROTO_RCMM24)
+--------------------------
+
+The rc-mm protocol is described here
+https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
+the 24 bits.
+
+rc-mm-32 (RC_PROTO_RCMM32)
+--------------------------
+
+The rc-mm protocol is described here
+https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply
+the 32 bits.
+
+xbox-dvd (RC_PROTO_XBOX_DVD)
+----------------------------
+
+This protocol is used by Xbox DVD Remote, which was made for the original
+Xbox. There is no in-kernel decoder or encoder for this protocol. The usb
+device decodes the protocol. There is a BPF decoder available in v4l-utils.
diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst
new file mode 100644
index 000000000..70b5966aa
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst
@@ -0,0 +1,144 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _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::
+
+	rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce
+
+Note that protocol variants are listed, so ``nec``, ``sony``, ``rc-5``, ``rc-6``
+have their different bit length encodings listed if available.
+
+Note that all protocol variants are listed.
+
+The enabled wakeup protocol is shown in [] brackets.
+
+Only one protocol can be selected at a time.
+
+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.
diff --git a/Documentation/userspace-api/media/rc/rc-table-change.rst b/Documentation/userspace-api/media/rc/rc-table-change.rst
new file mode 100644
index 000000000..d7de8a56d
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/rc-table-change.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _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/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst
new file mode 100644
index 000000000..aab99260f
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/rc-tables.rst
@@ -0,0 +1,759 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+
+.. _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:
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
+
+.. 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_NUMERIC_0``
+
+       -  Keyboard digit 0
+
+       -  0
+
+    -  .. row 4
+
+       -  ``KEY_NUMERIC_1``
+
+       -  Keyboard digit 1
+
+       -  1
+
+    -  .. row 5
+
+       -  ``KEY_NUMERIC_2``
+
+       -  Keyboard digit 2
+
+       -  2
+
+    -  .. row 6
+
+       -  ``KEY_NUMERIC_3``
+
+       -  Keyboard digit 3
+
+       -  3
+
+    -  .. row 7
+
+       -  ``KEY_NUMERIC_4``
+
+       -  Keyboard digit 4
+
+       -  4
+
+    -  .. row 8
+
+       -  ``KEY_NUMERIC_5``
+
+       -  Keyboard digit 5
+
+       -  5
+
+    -  .. row 9
+
+       -  ``KEY_NUMERIC_6``
+
+       -  Keyboard digit 6
+
+       -  6
+
+    -  .. row 10
+
+       -  ``KEY_NUMERIC_7``
+
+       -  Keyboard digit 7
+
+       -  7
+
+    -  .. row 11
+
+       -  ``KEY_NUMERIC_8``
+
+       -  Keyboard digit 8
+
+       -  8
+
+    -  .. row 12
+
+       -  ``KEY_NUMERIC_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 stream
+
+       -  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 stream
+
+       -  STOP
+
+    -  .. row 25
+
+       -  ``KEY_RECORD``
+
+       -  Start/stop recording stream
+
+       -  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 sequentially
+
+       -  CHANNEL - / CHANNEL DOWN / DOWN
+
+    -  .. row 47
+
+       -  ``KEY_CHANNELUP``
+
+       -  Increase channel sequentially
+
+       -  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 stream 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 stream 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_ASPECT_RATIO``
+
+       -  Select screen aspect ratio
+
+       -  4:3 16:9 SELECT
+
+    -  .. row 79
+
+       -  ``KEY_FULL_SCREEN``
+
+       -  Put device into zoom/full screen mode
+
+       -  ZOOM / FULL SCREEN / ZOOM+ / HIDE PANEL / 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/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst
new file mode 100644
index 000000000..483f9ae92
--- /dev/null
+++ b/Documentation/userspace-api/media/rc/remote_controllers.rst
@@ -0,0 +1,46 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
+.. include:: <isonum.txt>
+
+.. _remote_controllers:
+
+################################
+Part III - Remote Controller API
+################################
+
+.. toctree::
+    :caption: Table of Contents
+    :maxdepth: 5
+    :numbered:
+
+    rc-intro
+    rc-sysfs-nodes
+    rc-protos
+    rc-tables
+    rc-table-change
+    lirc-dev
+
+
+**********************
+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