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

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

Documentation/linux_tv/media/v4l/dmabuf.rst

+22 −19
Original line number Original line Diff line number Diff line
@@ -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 
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 
    }

    }





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 
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 
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.