Commit a163ad5c authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 4eb96763
......@@ -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 <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 <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 <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 <VIDIOC_QBUF>` 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() <func-open>` function, ``VIDIOC_DQBUF`` 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.
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` and
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` 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 <v4l2-buffer>` ``timestamp`` of captured or
: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 :ref:`v4l2_buffer <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 <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. [2]_
.. [1]
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment