media: docs: move uAPI book to userspace-api/media

Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee3862 ("docs: Create a user-space API guide").

As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.

Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

1 files changed, 0 insertions, 128 deletions

diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst
deleted file mode 100644
index b19da8655452..000000000000
--- a/Documentation/media/uapi/v4l/userp.rst
+++ /dev/null
@@ -1,128 +0,0 @@
-.. 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/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _userp:
-
-*****************************
-Streaming I/O (User Pointers)
-*****************************
-
-Input and output devices support this I/O method when the
-``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
-:c:type:`v4l2_capability` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl is set. If the
-particular user pointer method (not only memory mapping) is supported
-must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl
-with the memory type set to ``V4L2_MEMORY_USERPTR``.
-
-This I/O method combines advantages of the read/write and memory mapping
-methods. Buffers (planes) are allocated by the application itself, and
-can reside for example in virtual or shared memory. Only pointers to
-data are exchanged, these pointers and meta-information are passed in
-struct :c:type:`v4l2_buffer` (or in struct
-:c:type:`v4l2_plane` in the multi-planar API case). The
-driver must be switched into user pointer I/O mode by calling the
-:ref:`VIDIOC_REQBUFS` with the desired buffer type.
-No buffers (planes) are allocated beforehand, consequently they are not
-indexed and cannot be queried like mapped buffers with the
-:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
-
-Example: Initiating streaming I/O with user pointers
-====================================================
-
-.. code-block:: c
-
-    struct v4l2_requestbuffers reqbuf;
-
-    memset (&reqbuf, 0, sizeof (reqbuf));
-    reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-    reqbuf.memory = V4L2_MEMORY_USERPTR;
-
-    if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
-	if (errno == EINVAL)
-	    printf ("Video capturing or user pointer streaming is not supported\\n");
-	else
-	    perror ("VIDIOC_REQBUFS");
-
-	exit (EXIT_FAILURE);
-    }
-
-Buffer (plane) addresses and sizes are passed on the fly with the
-:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
-cycled, applications can pass different addresses and sizes at each
-:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
-driver swaps memory pages within physical memory to create a continuous
-area of memory. This happens transparently to the application in the
-virtual memory subsystem of the kernel. When buffer pages have been
-swapped out to disk they are brought back and finally locked in physical
-memory for DMA. [#f1]_
-
-Filled or displayed buffers are dequeued with the
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
-memory pages at any time between the completion of the DMA and this
-ioctl. The memory is also unlocked when
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
-:ref:`VIDIOC_REQBUFS`, or when the device is closed.
-Applications must take care not to free buffers without dequeuing.
-Firstly, the buffers remain locked for longer, wasting physical memory.
-Secondly the driver will not be notified when the memory is returned to
-the application's free list and subsequently reused for other purposes,
-possibly completing the requested DMA and overwriting valuable data.
-
-For capturing applications it is customary to enqueue a number of empty
-buffers, to start capturing and enter the read loop. Here the
-application waits until a filled buffer can be dequeued, and re-enqueues
-the buffer when the data is no longer needed. Output applications fill
-and enqueue buffers, when enough buffers are stacked up output is
-started. In the write loop, when the application runs out of free
-buffers it must wait until an empty buffer can be dequeued and reused.
-Two methods exist to suspend execution of the application until one or
-more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
-<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
-``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
-error code when no buffer is available. The :ref:`select()
-<func-select>` or :ref:`poll() <func-poll>` function are always
-available.
-
-To start and stop capturing or output applications call the
-:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl.
-
-.. note::
-
-   :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
-   both queues and unlocks all buffers as a side effect. Since there is no
-   notion of doing anything "now" on a multitasking system, if an
-   application needs to synchronize with another event it should examine
-   the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or
-   outputted buffers.
-
-Drivers implementing user pointer I/O must support the
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [#f2]_
-
-.. [#f1]
-   We expect that frequently used buffers are typically not swapped out.
-   Anyway, the process of swapping, locking or generating scatter-gather
-   lists may be time consuming. The delay can be masked by the depth of
-   the incoming buffer queue, and perhaps by maintaining caches assuming
-   a buffer will be soon enqueued again. On the other hand, to optimize
-   memory usage drivers can limit the number of buffers locked in
-   advance and recycle the most recently used buffers first. Of course,
-   the pages of empty buffers in the incoming queue need not be saved to
-   disk. Output buffers must be saved on the incoming and outgoing queue
-   because an application may share them with other processes.
-
-.. [#f2]
-   At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
-   the same, and :ref:`select() <func-select>` is too important to be optional.
-   The rest should be evident.