~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/userspace-api/media/v4l/dmabuf.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/userspace-api/media/v4l/dmabuf.rst (Architecture alpha) and /Documentation/userspace-api/media/v4l/dmabuf.rst (Architecture mips)


  1 .. SPDX-License-Identifier: GFDL-1.1-no-invari      1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
  2 .. c:namespace:: V4L                                2 .. c:namespace:: V4L
  3                                                     3 
  4 .. _dmabuf:                                         4 .. _dmabuf:
  5                                                     5 
  6 ************************************                6 ************************************
  7 Streaming I/O (DMA buffer importing)                7 Streaming I/O (DMA buffer importing)
  8 ************************************                8 ************************************
  9                                                     9 
 10 The DMABUF framework provides a generic method     10 The DMABUF framework provides a generic method for sharing buffers
 11 between multiple devices. Device drivers that      11 between multiple devices. Device drivers that support DMABUF can export
 12 a DMA buffer to userspace as a file descriptor     12 a DMA buffer to userspace as a file descriptor (known as the exporter
 13 role), import a DMA buffer from userspace usin     13 role), import a DMA buffer from userspace using a file descriptor
 14 previously exported for a different or the sam     14 previously exported for a different or the same device (known as the
 15 importer role), or both. This section describe     15 importer role), or both. This section describes the DMABUF importer role
 16 API in V4L2.                                       16 API in V4L2.
 17                                                    17 
 18 Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF     18 Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about
 19 exporting V4L2 buffers as DMABUF file descript     19 exporting V4L2 buffers as DMABUF file descriptors.
 20                                                    20 
 21 Input and output devices support the streaming     21 Input and output devices support the streaming I/O method when the
 22 ``V4L2_CAP_STREAMING`` flag in the ``capabilit     22 ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
 23 :c:type:`v4l2_capability` returned by the          23 :c:type:`v4l2_capability` returned by the
 24 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl     24 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
 25 importing DMA buffers through DMABUF file desc     25 importing DMA buffers through DMABUF file descriptors is supported is
 26 determined by calling the :ref:`VIDIOC_REQBUFS     26 determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
 27 ioctl with the memory type set to ``V4L2_MEMOR     27 ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
 28                                                    28 
 29 This I/O method is dedicated to sharing DMA bu     29 This I/O method is dedicated to sharing DMA buffers between different
 30 devices, which may be V4L devices or other vid     30 devices, which may be V4L devices or other video-related devices (e.g.
 31 DRM). Buffers (planes) are allocated by a driv     31 DRM). Buffers (planes) are allocated by a driver on behalf of an
 32 application. Next, these buffers are exported      32 application. Next, these buffers are exported to the application as file
 33 descriptors using an API which is specific for     33 descriptors using an API which is specific for an allocator driver. Only
 34 such file descriptor are exchanged. The descri     34 such file descriptor are exchanged. The descriptors and meta-information
 35 are passed in struct :c:type:`v4l2_buffer` (or     35 are passed in struct :c:type:`v4l2_buffer` (or in struct
 36 :c:type:`v4l2_plane` in the multi-planar API c     36 :c:type:`v4l2_plane` in the multi-planar API case). The
 37 driver must be switched into DMABUF I/O mode b     37 driver must be switched into DMABUF I/O mode by calling the
 38 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with th     38 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
 39                                                    39 
 40 Example: Initiating streaming I/O with DMABUF      40 Example: Initiating streaming I/O with DMABUF file descriptors
 41 ==============================================     41 ==============================================================
 42                                                    42 
 43 .. code-block:: c                                  43 .. code-block:: c
 44                                                    44 
 45     struct v4l2_requestbuffers reqbuf;             45     struct v4l2_requestbuffers reqbuf;
 46                                                    46 
 47     memset(&reqbuf, 0, sizeof (reqbuf));           47     memset(&reqbuf, 0, sizeof (reqbuf));
 48     reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;     48     reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 49     reqbuf.memory = V4L2_MEMORY_DMABUF;            49     reqbuf.memory = V4L2_MEMORY_DMABUF;
 50     reqbuf.count = 1;                              50     reqbuf.count = 1;
 51                                                    51 
 52     if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) ==      52     if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
 53         if (errno == EINVAL)                       53         if (errno == EINVAL)
 54             printf("Video capturing or DMABUF      54             printf("Video capturing or DMABUF streaming is not supported\\n");
 55         else                                       55         else
 56             perror("VIDIOC_REQBUFS");              56             perror("VIDIOC_REQBUFS");
 57                                                    57 
 58         exit(EXIT_FAILURE);                        58         exit(EXIT_FAILURE);
 59     }                                              59     }
 60                                                    60 
 61 The buffer (plane) file descriptor is passed o     61 The buffer (plane) file descriptor is passed on the fly with the
 62 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In cas     62 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
 63 buffers, every plane can be associated with a      63 buffers, every plane can be associated with a different DMABUF
 64 descriptor. Although buffers are commonly cycl     64 descriptor. Although buffers are commonly cycled, applications can pass
 65 a different DMABUF descriptor at each :ref:`VI     65 a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
 66                                                    66 
 67 Example: Queueing DMABUF using single plane AP     67 Example: Queueing DMABUF using single plane API
 68 ==============================================     68 ===============================================
 69                                                    69 
 70 .. code-block:: c                                  70 .. code-block:: c
 71                                                    71 
 72     int buffer_queue(int v4lfd, int index, int     72     int buffer_queue(int v4lfd, int index, int dmafd)
 73     {                                              73     {
 74         struct v4l2_buffer buf;                    74         struct v4l2_buffer buf;
 75                                                    75 
 76         memset(&buf, 0, sizeof buf);               76         memset(&buf, 0, sizeof buf);
 77         buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE     77         buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 78         buf.memory = V4L2_MEMORY_DMABUF;           78         buf.memory = V4L2_MEMORY_DMABUF;
 79         buf.index = index;                         79         buf.index = index;
 80         buf.m.fd = dmafd;                          80         buf.m.fd = dmafd;
 81                                                    81 
 82         if (ioctl(v4lfd, VIDIOC_QBUF, &buf) ==     82         if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
 83             perror("VIDIOC_QBUF");                 83             perror("VIDIOC_QBUF");
 84             return -1;                             84             return -1;
 85         }                                          85         }
 86                                                    86 
 87         return 0;                                  87         return 0;
 88     }                                              88     }
 89                                                    89 
 90 Example 3.6. Queueing DMABUF using multi plane     90 Example 3.6. Queueing DMABUF using multi plane API
 91 ==============================================     91 ==================================================
 92                                                    92 
 93 .. code-block:: c                                  93 .. code-block:: c
 94                                                    94 
 95     int buffer_queue_mp(int v4lfd, int index,      95     int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
 96     {                                              96     {
 97         struct v4l2_buffer buf;                    97         struct v4l2_buffer buf;
 98         struct v4l2_plane planes[VIDEO_MAX_PLA     98         struct v4l2_plane planes[VIDEO_MAX_PLANES];
 99         int i;                                     99         int i;
100                                                   100 
101         memset(&buf, 0, sizeof buf);              101         memset(&buf, 0, sizeof buf);
102         buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE    102         buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
103         buf.memory = V4L2_MEMORY_DMABUF;          103         buf.memory = V4L2_MEMORY_DMABUF;
104         buf.index = index;                        104         buf.index = index;
105         buf.m.planes = planes;                    105         buf.m.planes = planes;
106         buf.length = n_planes;                    106         buf.length = n_planes;
107                                                   107 
108         memset(&planes, 0, sizeof planes);        108         memset(&planes, 0, sizeof planes);
109                                                   109 
110         for (i = 0; i < n_planes; ++i)            110         for (i = 0; i < n_planes; ++i)
111             buf.m.planes[i].m.fd = dmafd[i];      111             buf.m.planes[i].m.fd = dmafd[i];
112                                                   112 
113         if (ioctl(v4lfd, VIDIOC_QBUF, &buf) ==    113         if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
114             perror("VIDIOC_QBUF");                114             perror("VIDIOC_QBUF");
115             return -1;                            115             return -1;
116         }                                         116         }
117                                                   117 
118         return 0;                                 118         return 0;
119     }                                             119     }
120                                                   120 
121 Captured or displayed buffers are dequeued wit    121 Captured or displayed buffers are dequeued with the
122 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The d    122 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
123 buffer at any time between the completion of t    123 buffer at any time between the completion of the DMA and this ioctl. The
124 memory is also unlocked when                      124 memory is also unlocked when
125 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is c    125 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
126 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or whe    126 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
127                                                   127 
128 For capturing applications it is customary to     128 For capturing applications it is customary to enqueue a number of empty
129 buffers, to start capturing and enter the read    129 buffers, to start capturing and enter the read loop. Here the
130 application waits until a filled buffer can be    130 application waits until a filled buffer can be dequeued, and re-enqueues
131 the buffer when the data is no longer needed.     131 the buffer when the data is no longer needed. Output applications fill
132 and enqueue buffers, when enough buffers are s    132 and enqueue buffers, when enough buffers are stacked up output is
133 started. In the write loop, when the applicati    133 started. In the write loop, when the application runs out of free
134 buffers it must wait until an empty buffer can    134 buffers it must wait until an empty buffer can be dequeued and reused.
135 Two methods exist to suspend execution of the     135 Two methods exist to suspend execution of the application until one or
136 more buffers can be dequeued. By default :ref:    136 more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
137 <VIDIOC_QBUF>` blocks when no buffer is in the    137 <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
138 ``O_NONBLOCK`` flag was given to the :c:func:`    138 ``O_NONBLOCK`` flag was given to the :c:func:`open()` function,
139 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns imme    139 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
140 error code when no buffer is available. The       140 error code when no buffer is available. The
141 :c:func:`select()` and :c:func:`poll()`           141 :c:func:`select()` and :c:func:`poll()`
142 functions are always available.                   142 functions are always available.
143                                                   143 
144 To start and stop capturing or displaying appl    144 To start and stop capturing or displaying applications call the
145 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and      145 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
146 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioct    146 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls.
147                                                   147 
148 .. note::                                         148 .. note::
149                                                   149 
150    :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` r    150    :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
151    both queues and unlocks all buffers as a si    151    both queues and unlocks all buffers as a side effect. Since there is no
152    notion of doing anything "now" on a multita    152    notion of doing anything "now" on a multitasking system, if an
153    application needs to synchronize with anoth    153    application needs to synchronize with another event it should examine
154    the struct :c:type:`v4l2_buffer` ``timestam    154    the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or
155    outputted buffers.                             155    outputted buffers.
156                                                   156 
157 Drivers implementing DMABUF importing I/O must    157 Drivers implementing DMABUF importing I/O must support the
158 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`    158 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
159 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIO    159 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
160 <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF     160 <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
161 and the :c:func:`select()` and :c:func:`poll()    161 and the :c:func:`select()` and :c:func:`poll()`
162 functions.                                        162 functions.
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php