From a163ad5ceb30d2034b70cda8bdad0aaabdba1614 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 4 Jul 2016 16:06:57 -0300 Subject: [PATCH] doc-rst: userp: Add ioctl cross references There are lots of ioctls mentioned there that aren't cross-referenced. Convert the const to cross references. That makes it visually better, and improves navigation along the document. While here, remove bad whitespaces. Signed-off-by: Mauro Carvalho Chehab --- Documentation/linux_tv/media/v4l/userp.rst | 56 +++++++++++----------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/Documentation/linux_tv/media/v4l/userp.rst b/Documentation/linux_tv/media/v4l/userp.rst index 6db760d3d725..188c0b9f169e 100644 --- a/Documentation/linux_tv/media/v4l/userp.rst +++ b/Documentation/linux_tv/media/v4l/userp.rst @@ -24,7 +24,7 @@ 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 -``VIDIOC_QUERYBUF`` ioctl. +:ref:`VIDIOC_QUERYBUF ` ioctl. .. code-block:: c @@ -37,23 +37,23 @@ indexed and cannot be queried like mapped buffers with the 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"); + if (errno == EINVAL) + printf ("Video capturing or user pointer streaming is not supported\\n"); + else + perror ("VIDIOC_REQBUFS"); - exit (EXIT_FAILURE); + exit (EXIT_FAILURE); } Buffer (plane) addresses and sizes are passed on the fly with the -:ref:`VIDIOC_QBUF` ioctl. Although buffers are commonly +:ref:`VIDIOC_QBUF ` ioctl. Although buffers are commonly cycled, applications can pass different addresses and sizes at each -``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. [1]_ +:ref:`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. [1]_ Filled or displayed buffers are dequeued with the :ref:`VIDIOC_DQBUF ` ioctl. The driver can unlock the @@ -75,26 +75,28 @@ 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 ``VIDIOC_DQBUF`` blocks when no -buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given -to the :ref:`open() ` function, ``VIDIOC_DQBUF`` returns -immediately with an ``EAGAIN`` error code when no buffer is available. The -:ref:`select() ` or :ref:`poll() ` function -are always available. +more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF +`` blocks when no buffer is in the outgoing queue. When the +``O_NONBLOCK`` flag was given to the :ref:`open() ` function, +:ref:`VIDIOC_DQBUF ` returns immediately with an ``EAGAIN`` +error code when no buffer is available. The :ref:`select() +` or :ref:`poll() ` function are always +available. To start and stop capturing or output applications call the -:ref:`VIDIOC_STREAMON` and +:ref:`VIDIOC_STREAMON ` and :ref:`VIDIOC_STREAMOFF ` ioctl. Note -``VIDIOC_STREAMOFF`` 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 -:ref:`v4l2_buffer ` ``timestamp`` of captured or +:ref:`VIDIOC_STREAMOFF ` 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 :ref:`v4l2_buffer ` ``timestamp`` of captured or outputted buffers. Drivers implementing user pointer I/O must support the -``VIDIOC_REQBUFS``, ``VIDIOC_QBUF``, ``VIDIOC_DQBUF``, -``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl, the +:ref:`VIDIOC_REQBUFS `, :ref:`VIDIOC_QBUF `, +:ref:`VIDIOC_DQBUF `, :ref:`VIDIOC_STREAMON ` +and :ref:`VIDIOC_STREAMOFF ` ioctls, the :ref:`select() ` and :ref:`poll() ` function. [2]_ .. [1] -- 2.39.5