Commit 69eee8a5 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

doc-rst: dmabuf: 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.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 8f764eb9
...@@ -20,9 +20,9 @@ exporting V4L2 buffers as DMABUF file descriptors. ...@@ -20,9 +20,9 @@ exporting V4L2 buffers as DMABUF file descriptors.
Input and output devices support the streaming I/O method when the Input and output devices support the streaming I/O method when the
``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
:ref:`v4l2_capability <v4l2-capability>` returned by the :ref:`v4l2_capability <v4l2-capability>` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl is set. Whether :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
importing DMA buffers through DMABUF file descriptors is supported is importing DMA buffers through DMABUF file descriptors is supported is
determined by calling the :ref:`VIDIOC_REQBUFS` determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``. ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
This I/O method is dedicated to sharing DMA buffers between different This I/O method is dedicated to sharing DMA buffers between different
...@@ -34,7 +34,7 @@ such file descriptor are exchanged. The descriptors and meta-information ...@@ -34,7 +34,7 @@ such file descriptor are exchanged. The descriptors and meta-information
are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The :ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
driver must be switched into DMABUF I/O mode by calling the driver must be switched into DMABUF I/O mode by calling the
:ref:`VIDIOC_REQBUFS` with the desired buffer type. :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
.. code-block:: c .. code-block:: c
...@@ -57,10 +57,10 @@ driver must be switched into DMABUF I/O mode by calling the ...@@ -57,10 +57,10 @@ driver must be switched into DMABUF I/O mode by calling the
} }
The buffer (plane) file descriptor is passed on the fly with the The buffer (plane) file descriptor is passed on the fly with the
:ref:`VIDIOC_QBUF` ioctl. In case of multiplanar :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
buffers, every plane can be associated with a different DMABUF buffers, every plane can be associated with a different DMABUF
descriptor. Although buffers are commonly cycled, applications can pass descriptor. Although buffers are commonly cycled, applications can pass
a different DMABUF descriptor at each ``VIDIOC_QBUF`` call. a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
.. code-block:: c .. code-block:: c
...@@ -119,7 +119,7 @@ Captured or displayed buffers are dequeued with the ...@@ -119,7 +119,7 @@ Captured or displayed buffers are dequeued with the
buffer at any time between the completion of the DMA and this ioctl. The buffer at any time between the completion of the DMA and this ioctl. The
memory is also unlocked when memory is also unlocked when
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called, :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
:ref:`VIDIOC_REQBUFS`, or when the device is closed. :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
For capturing applications it is customary to enqueue a number of empty For capturing applications it is customary to enqueue a number of empty
buffers, to start capturing and enter the read loop. Here the buffers, to start capturing and enter the read loop. Here the
...@@ -129,24 +129,27 @@ and enqueue buffers, when enough buffers are stacked up output is ...@@ -129,24 +129,27 @@ 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``
error code when no buffer is available. The
:ref:`select() <func-select>` and :ref:`poll() <func-poll>` :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
functions are always available. functions are always available.
To start and stop capturing or displaying applications call the To start and stop capturing or displaying applications call the
:ref:`VIDIOC_STREAMON` and :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that
``VIDIOC_STREAMOFF`` removes all buffers from both queues and unlocks :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
all buffers as a side effect. Since there is no notion of doing anything both 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 DMABUF importing I/O must support the Drivers implementing DMABUF importing 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`` ioctls, and the :ref:`VIDIOC_DQBUF <VIDIOC_DQBUF>`, :ref:`VIDIOC_STREAMON
:ref:`select() <func-select>` and :ref:`poll() <func-poll>` functions. <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
functions.
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