UPSTREAM: media: lirc: when transmitting scancodes, block until transmit is done

The semantics for lirc IR transmit with raw IR is that the write call
should block until the IR is transmitted. Some drivers have no idea
when this actually is (e.g. mceusb), so there is a wait.

This is useful for userspace, as it might want to send a IR button press,
a gap of a predefined number of milliseconds, and then send a repeat
message.

It turns out that for transmitting scancodes this feature is even more
useful, as user space has no idea how long the IR is. So, maintain
the existing semantics for IR scancode transmit.

Signed-off-by: Sean Young <sean@mess.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
(cherry picked from commit dde7edff359461d07074ef2f0c4dc85b775d493f)
Signed-off-by: Ziyuan Xu <xzy.xu@rock-chips.com>

 Conflicts:
    Documentation/media/uapi/rc/lirc-write.rst

1 files changed, 74 insertions, 0 deletions

diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst
new file mode 100644
index 000000000000..d4566b0a2015
--- /dev/null
+++ b/Documentation/media/uapi/rc/lirc-write.rst
@@ -0,0 +1,74 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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 protocol 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.