diff options
Diffstat (limited to 'Documentation/userspace-api/media/rc')
27 files changed, 3041 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 000000000000..901d33d37843 --- /dev/null +++ b/Documentation/userspace-api/media/rc/keytable.c.rst @@ -0,0 +1,183 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +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 000000000000..0c3d70ded55d --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst @@ -0,0 +1,171 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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. + + ``LIRC_MODE2_SPACE`` + + Signifies absence of IR in microseconds. + + ``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`` + + If timeout reports are enabled with + :ref:`lirc_set_rec_timeout_reports`, 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-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. + +******************** +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 000000000000..7a395fa52934 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-dev.rst @@ -0,0 +1,21 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 000000000000..e37c99583212 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-func.rst @@ -0,0 +1,34 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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-rec-timeout-reports + 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 000000000000..f4b9ca09f828 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst @@ -0,0 +1,200 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_get_features: + +*********************** +ioctl LIRC_GET_FEATURES +*********************** + +Name +==== + +LIRC_GET_FEATURES - Get the underlying hardware device's features + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features) + :name: LIRC_GET_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-DUTY-CYCLE-RANGE: + +``LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE`` + + Unused. Kept just to avoid breaking uAPI. + +.. _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-SET-REC-FILTER: + +``LIRC_CAN_SET_REC_FILTER`` + + Unused. Kept just to avoid breaking uAPI. + +.. _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-NOTIFY-DECODE: + +``LIRC_CAN_NOTIFY_DECODE`` + + Unused. Kept just to avoid breaking uAPI. + +.. _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 000000000000..674ce16d5d33 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst @@ -0,0 +1,74 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) + :name: LIRC_GET_REC_MODE + +.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) + :name: LIRC_SET_REC_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 000000000000..f20b5bf41232 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst @@ -0,0 +1,54 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_get_rec_resolution: + +***************************** +ioctl LIRC_GET_REC_RESOLUTION +***************************** + +Name +==== + +LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microseconds. + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds) + :name: LIRC_GET_REC_RESOLUTION + +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 000000000000..973a47bf6068 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst @@ -0,0 +1,78 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) + :name: LIRC_GET_SEND_MODE + +.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) + :name: LIRC_SET_SEND_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 000000000000..5db84096d7f8 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst @@ -0,0 +1,63 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout) + :name: LIRC_GET_MIN_TIMEOUT + +.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout) + :name: LIRC_GET_MAX_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 000000000000..c7e0716da159 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -0,0 +1,17 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_header: + +**************** +LIRC Header File +**************** + +.. kernel-include:: $BUILDDIR/lirc.h.rst + 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 000000000000..13f7f5353851 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-read.rst @@ -0,0 +1,76 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 ) + :name: lirc-read + + +Arguments +========= + +``fd`` + File descriptor returned by ``open()``. + +``buf`` + Buffer to be filled + +``count`` + Max number of bytes to read + +Description +=========== + +:ref:`read() <lirc-read>` attempts to read up to ``count`` bytes from file +descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, +:ref:`read() <lirc-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 000000000000..4cf9472eb904 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst @@ -0,0 +1,53 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_set_measure_carrier_mode: + +*********************************** +ioctl LIRC_SET_MEASURE_CARRIER_MODE +*********************************** + +Name +==== + +LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable ) + :name: LIRC_SET_MEASURE_CARRIER_MODE + +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 000000000000..0439e93aa267 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst @@ -0,0 +1,54 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency ) + :name: LIRC_SET_REC_CARRIER_RANGE + +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 000000000000..f4d18897cb9f --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst @@ -0,0 +1,53 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_set_rec_carrier: + +************************** +ioctl LIRC_SET_REC_CARRIER +************************** + +Name +==== + +LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive. + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency ) + :name: LIRC_SET_REC_CARRIER + +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-reports.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst new file mode 100644 index 000000000000..ab97f87fa757 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst @@ -0,0 +1,56 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_set_rec_timeout_reports: + +********************************** +ioctl LIRC_SET_REC_TIMEOUT_REPORTS +********************************** + +Name +==== + +LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable ) + :name: LIRC_SET_REC_TIMEOUT_REPORTS + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``enable`` + enable = 1 means enable timeout report, enable = 0 means disable timeout + reports. + + +Description +=========== + +.. _lirc-mode2-timeout: + +Enable or disable timeout reports for IR receive. By default, timeout reports +should be turned off. + +.. note:: + + This ioctl is only valid for :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`. + + +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 000000000000..227776cf7c62 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst @@ -0,0 +1,61 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout ) + :name: LIRC_GET_REC_TIMEOUT + +.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout ) + :name: LIRC_SET_REC_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 000000000000..7eaf2b993207 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst @@ -0,0 +1,48 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_set_send_carrier: + +*************************** +ioctl LIRC_SET_SEND_CARRIER +*************************** + +Name +==== + +LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX. + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency ) + :name: LIRC_SET_SEND_CARRIER + +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 000000000000..0dee89364cde --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst @@ -0,0 +1,54 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle) + :name: LIRC_SET_SEND_DUTY_CYCLE + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``duty_cycle`` + Duty cicle, 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 000000000000..dcee4b71dcf6 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst @@ -0,0 +1,58 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask ) + :name: LIRC_SET_TRANSMITTER_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 000000000000..22f6fe43b7e7 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -0,0 +1,63 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _lirc_set_wideband_receiver: + +******************************** +ioctl LIRC_SET_WIDEBAND_RECEIVER +******************************** + +Name +==== + +LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver. + +Synopsis +======== + +.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable ) + :name: LIRC_SET_WIDEBAND_RECEIVER + +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 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. + + +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 000000000000..96ca4a22062e --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-write.rst @@ -0,0 +1,82 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 ) + :name: lirc-write + +Arguments +========= + +``fd`` + File descriptor returned by ``open()``. + +``buf`` + Buffer with data to be written + +``count`` + Number of bytes at the buffer + +Description +=========== + +:ref:`write() <lirc-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/rc-intro.rst b/Documentation/userspace-api/media/rc/rc-intro.rst new file mode 100644 index 000000000000..14e85157bf23 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-intro.rst @@ -0,0 +1,31 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 000000000000..b250ebe301d5 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -0,0 +1,456 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 commmand 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 000000000000..73dd75f77d65 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst @@ -0,0 +1,151 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 000000000000..f5d00a20b939 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-table-change.rst @@ -0,0 +1,25 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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 000000000000..33b724b17ff3 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -0,0 +1,766 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _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.7cm}| + +.. 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 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/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst new file mode 100644 index 000000000000..3ab2d6db1564 --- /dev/null +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -0,0 +1,59 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. include:: <isonum.txt> + +.. _remote_controllers: + +################################ +Part III - Remote Controller API +################################ + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :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 |