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 ...@@ -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. :ref:`VIDIOC_REQBUFS` with the desired buffer type.
No buffers (planes) are allocated beforehand, consequently they are not No buffers (planes) are allocated beforehand, consequently they are not
indexed and cannot be queried like mapped buffers with the indexed and cannot be queried like mapped buffers with the
``VIDIOC_QUERYBUF`` ioctl. :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
.. code-block:: c .. code-block:: c
...@@ -37,23 +37,23 @@ indexed and cannot be queried like mapped buffers with the ...@@ -37,23 +37,23 @@ indexed and cannot be queried like mapped buffers with the
reqbuf.memory = V4L2_MEMORY_USERPTR; reqbuf.memory = V4L2_MEMORY_USERPTR;
if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) { if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
if (errno == EINVAL) if (errno == EINVAL)
printf ("Video capturing or user pointer streaming is not supported\\n"); printf ("Video capturing or user pointer streaming is not supported\\n");
else else
perror ("VIDIOC_REQBUFS"); perror ("VIDIOC_REQBUFS");
exit (EXIT_FAILURE); exit (EXIT_FAILURE);
} }
Buffer (plane) addresses and sizes are passed on the fly with the 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 cycled, applications can pass different addresses and sizes at each
``VIDIOC_QBUF`` call. If required by the hardware the driver swaps :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
memory pages within physical memory to create a continuous area of driver swaps memory pages within physical memory to create a continuous
memory. This happens transparently to the application in the virtual area of memory. This happens transparently to the application in the
memory subsystem of the kernel. When buffer pages have been swapped out virtual memory subsystem of the kernel. When buffer pages have been
to disk they are brought back and finally locked in physical memory for swapped out to disk they are brought back and finally locked in physical
DMA. [1]_ memory for DMA. [1]_
Filled or displayed buffers are dequeued with the Filled or displayed buffers are dequeued with the
:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock 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 ...@@ -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 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. 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 Two methods exist to suspend execution of the application until one or
more buffers can be dequeued. By default ``VIDIOC_DQBUF`` blocks when no more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
buffer is in the outgoing queue. When the ``O_NONBLOCK`` flag was given <VIDIOC_QBUF>`` blocks when no buffer is in the outgoing queue. When the
to the :ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
immediately with an ``EAGAIN`` error code when no buffer is available. The :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
:ref:`select() <func-select>` or :ref:`poll() <func-poll>` function error code when no buffer is available. The :ref:`select()
are always available. <func-select>` or :ref:`poll() <func-poll>` function are always
available.
To start and stop capturing or output applications call the 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 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. Note
``VIDIOC_STREAMOFF`` removes all buffers from both queues and unlocks :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both
all buffers as a side effect. Since there is no notion of doing anything queues and unlocks all buffers as a side effect. Since there is no
"now" on a multitasking system, if an application needs to synchronize notion of doing anything "now" on a multitasking system, if an
with another event it should examine the struct application needs to synchronize with another event it should examine
:ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
outputted buffers. outputted buffers.
Drivers implementing user pointer I/O must support the Drivers implementing user pointer I/O must support the
``VIDIOC_REQBUFS``, ``VIDIOC_QBUF``, ``VIDIOC_DQBUF``, :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl, the :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]_ :ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [2]_
.. [1] .. [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