From bd6a63f2e69ea16851a99b200cd2039186173775 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 12 Jul 2016 09:35:26 -0300 Subject: [media] doc-rst: reorganize LIRC ReST files Reorganize the LIRC rst files, using "-" instead of "_" on their names, and creating a separate chapter for syscalls. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/rc/lirc-dev-intro.rst | 62 ++++++++++++++++++++++ Documentation/media/uapi/rc/lirc-dev.rst | 14 +++++ Documentation/media/uapi/rc/lirc-func.rst | 28 ++++++++++ Documentation/media/uapi/rc/lirc-read.rst | 62 ++++++++++++++++++++++ Documentation/media/uapi/rc/lirc-write.rst | 58 ++++++++++++++++++++ Documentation/media/uapi/rc/lirc_dev_intro.rst | 62 ---------------------- .../media/uapi/rc/lirc_device_interface.rst | 29 ---------- Documentation/media/uapi/rc/lirc_read.rst | 62 ---------------------- Documentation/media/uapi/rc/lirc_write.rst | 58 -------------------- Documentation/media/uapi/rc/remote_controllers.rst | 3 +- 10 files changed, 225 insertions(+), 213 deletions(-) create mode 100644 Documentation/media/uapi/rc/lirc-dev-intro.rst create mode 100644 Documentation/media/uapi/rc/lirc-dev.rst create mode 100644 Documentation/media/uapi/rc/lirc-func.rst create mode 100644 Documentation/media/uapi/rc/lirc-read.rst create mode 100644 Documentation/media/uapi/rc/lirc-write.rst delete mode 100644 Documentation/media/uapi/rc/lirc_dev_intro.rst delete mode 100644 Documentation/media/uapi/rc/lirc_device_interface.rst delete mode 100644 Documentation/media/uapi/rc/lirc_read.rst delete mode 100644 Documentation/media/uapi/rc/lirc_write.rst (limited to 'Documentation') diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst new file mode 100644 index 000000000000..ef97e40f2fd8 --- /dev/null +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_dev_intro: + +************ +Introduction +************ + +The LIRC device interface is a bi-directional interface for transporting +raw IR data between userspace and kernelspace. Fundamentally, it is just +a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard +struct file_operations defined on it. With respect to transporting raw +IR data to and fro, the essential fops are read, write and ioctl. + +Example dmesg output upon a driver registering w/LIRC: + +.. code-block:: none + + $ dmesg |grep lirc_dev + lirc_dev: IR Remote Control driver registered, major 248 + rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0 + +What you should see for a chardev: + +.. code-block:: none + + $ ls -l /dev/lirc* + crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 + +********** +LIRC modes +********** + +LIRC supports some modes of receiving and sending IR codes, as shown +on the following table. + +.. _lirc-mode-mode2: + +``LIRC_MODE_MODE2`` + + The driver returns a sequence of pulse and space codes to userspace. + + This mode is used only for IR receive. + +.. _lirc-mode-lirccode: + +``LIRC_MODE_LIRCCODE`` + + The IR signal is decoded internally by the receiver. The LIRC interface + returns the scancode as an integer value. This is the usual mode used + by several TV media cards. + + This mode is used only for IR receive. + +.. _lirc-mode-pulse: + +``LIRC_MODE_PULSE`` + + On puse mode, a sequence of pulse/space integer values are written to the + lirc device using :Ref:`lirc-write`. + + This mode is used only for IR send. diff --git a/Documentation/media/uapi/rc/lirc-dev.rst b/Documentation/media/uapi/rc/lirc-dev.rst new file mode 100644 index 000000000000..03cde25f5859 --- /dev/null +++ b/Documentation/media/uapi/rc/lirc-dev.rst @@ -0,0 +1,14 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_dev: + +LIRC Device Interface +===================== + + +.. toctree:: + :maxdepth: 1 + + lirc-dev-intro + lirc-func + lirc-header diff --git a/Documentation/media/uapi/rc/lirc-func.rst b/Documentation/media/uapi/rc/lirc-func.rst new file mode 100644 index 000000000000..9b5a772ec96c --- /dev/null +++ b/Documentation/media/uapi/rc/lirc-func.rst @@ -0,0 +1,28 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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-get-length + 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/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst new file mode 100644 index 000000000000..8d4e9b6e507d --- /dev/null +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc-read: + +*********** +LIRC read() +*********** + +Name +==== + +lirc-read - Read from a LIRC device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: ssize_t read( int fd, void *buf, size_t count ) + + +Arguments +========= + +``fd`` + File descriptor returned by ``open()``. + +``buf`` +``count`` + + +Description +=========== + +:ref:`read() ` attempts to read up to ``count`` bytes from file +descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, +:ref:`read() ` returns zero and has no other results. If ``count`` +is greater than ``SSIZE_MAX``, the result is unspecified. + +The lircd userspace daemon reads raw IR data from the LIRC chardev. The +exact format of the data depends on what modes a driver supports, and +what mode has been selected. lircd obtains supported modes and sets the +active mode via the ioctl interface, detailed at :ref:`lirc_func`. +The generally preferred mode for receive is +:ref:`LIRC_MODE_MODE2 `, in which packets containing an +int value describing an IR signal are read from the chardev. + +See also +`http://www.lirc.org/html/technical.html `__ +for more info. + +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/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst new file mode 100644 index 000000000000..dcba3b1bee6e --- /dev/null +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -0,0 +1,58 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc-write: + +************ +LIRC write() +************ + +Name +==== + +lirc-write - Write to a LIRC device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: ssize_t write( int fd, void *buf, size_t count ) + + +Arguments +========= + +``fd`` + File descriptor returned by ``open()``. + +``buf`` +``count`` + + +Description +=========== + +:ref:`write() ` writes up to ``count`` bytes to the device +referenced by the file descriptor ``fd`` from the buffer starting at +``buf``. + +The data written to the chardev is a pulse/space sequence of integer +values. Pulses and spaces are only marked implicitly by their position. +The data must start and end with a pulse, therefore, the data must +always include an uneven number of samples. The write function must +block until the data has been transmitted by the hardware. If more data +is provided than the hardware can send, the driver returns ``EINVAL``. + + +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. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/lirc_dev_intro.rst b/Documentation/media/uapi/rc/lirc_dev_intro.rst deleted file mode 100644 index ef97e40f2fd8..000000000000 --- a/Documentation/media/uapi/rc/lirc_dev_intro.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _lirc_dev_intro: - -************ -Introduction -************ - -The LIRC device interface is a bi-directional interface for transporting -raw IR data between userspace and kernelspace. Fundamentally, it is just -a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard -struct file_operations defined on it. With respect to transporting raw -IR data to and fro, the essential fops are read, write and ioctl. - -Example dmesg output upon a driver registering w/LIRC: - -.. code-block:: none - - $ dmesg |grep lirc_dev - lirc_dev: IR Remote Control driver registered, major 248 - rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0 - -What you should see for a chardev: - -.. code-block:: none - - $ ls -l /dev/lirc* - crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 - -********** -LIRC modes -********** - -LIRC supports some modes of receiving and sending IR codes, as shown -on the following table. - -.. _lirc-mode-mode2: - -``LIRC_MODE_MODE2`` - - The driver returns a sequence of pulse and space codes to userspace. - - This mode is used only for IR receive. - -.. _lirc-mode-lirccode: - -``LIRC_MODE_LIRCCODE`` - - The IR signal is decoded internally by the receiver. The LIRC interface - returns the scancode as an integer value. This is the usual mode used - by several TV media cards. - - This mode is used only for IR receive. - -.. _lirc-mode-pulse: - -``LIRC_MODE_PULSE`` - - On puse mode, a sequence of pulse/space integer values are written to the - lirc device using :Ref:`lirc-write`. - - This mode is used only for IR send. diff --git a/Documentation/media/uapi/rc/lirc_device_interface.rst b/Documentation/media/uapi/rc/lirc_device_interface.rst deleted file mode 100644 index a2ad957c96ae..000000000000 --- a/Documentation/media/uapi/rc/lirc_device_interface.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _lirc_dev: - -LIRC Device Interface -===================== - - -.. toctree:: - :maxdepth: 1 - - lirc_dev_intro - 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-get-length - 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/media/uapi/rc/lirc_read.rst b/Documentation/media/uapi/rc/lirc_read.rst deleted file mode 100644 index a8f1b446c294..000000000000 --- a/Documentation/media/uapi/rc/lirc_read.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _lirc-read: - -*********** -LIRC read() -*********** - -Name -==== - -lirc-read - Read from a LIRC device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. cpp:function:: ssize_t read( int fd, void *buf, size_t count ) - - -Arguments -========= - -``fd`` - File descriptor returned by ``open()``. - -``buf`` -``count`` - - -Description -=========== - -:ref:`read() ` attempts to read up to ``count`` bytes from file -descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, -:ref:`read() ` returns zero and has no other results. If ``count`` -is greater than ``SSIZE_MAX``, the result is unspecified. - -The lircd userspace daemon reads raw IR data from the LIRC chardev. The -exact format of the data depends on what modes a driver supports, and -what mode has been selected. lircd obtains supported modes and sets the -active mode via the ioctl interface, detailed at :ref:`lirc_ioctl`. -The generally preferred mode is LIRC_MODE_MODE2, in which packets -containing an int value describing an IR signal are read from the -chardev. - -See also -`http://www.lirc.org/html/technical.html `__ -for more info. - -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/media/uapi/rc/lirc_write.rst b/Documentation/media/uapi/rc/lirc_write.rst deleted file mode 100644 index dcba3b1bee6e..000000000000 --- a/Documentation/media/uapi/rc/lirc_write.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _lirc-write: - -************ -LIRC write() -************ - -Name -==== - -lirc-write - Write to a LIRC device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. cpp:function:: ssize_t write( int fd, void *buf, size_t count ) - - -Arguments -========= - -``fd`` - File descriptor returned by ``open()``. - -``buf`` -``count`` - - -Description -=========== - -:ref:`write() ` writes up to ``count`` bytes to the device -referenced by the file descriptor ``fd`` from the buffer starting at -``buf``. - -The data written to the chardev is a pulse/space sequence of integer -values. Pulses and spaces are only marked implicitly by their position. -The data must start and end with a pulse, therefore, the data must -always include an uneven number of samples. The write function must -block until the data has been transmitted by the hardware. If more data -is provided than the hardware can send, the driver returns ``EINVAL``. - - -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. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst index 3e9731afedd9..169286501ebb 100644 --- a/Documentation/media/uapi/rc/remote_controllers.rst +++ b/Documentation/media/uapi/rc/remote_controllers.rst @@ -23,8 +23,7 @@ Remote Controllers rc-sysfs-nodes rc-tables rc-table-change - lirc_device_interface - lirc-header + lirc-dev ********************** -- cgit