Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _userp: | |
4 | ||
5 | ***************************** | |
6 | Streaming I/O (User Pointers) | |
7 | ***************************** | |
8 | ||
9 | Input and output devices support this I/O method when the | |
10 | ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct | |
11 | :ref:`v4l2_capability <v4l2-capability>` returned by the | |
7347081e | 12 | :ref:`VIDIOC_QUERYCAP` ioctl is set. If the |
5377d91f | 13 | particular user pointer method (not only memory mapping) is supported |
071dedfe MCC |
14 | must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl |
15 | with the memory type set to ``V4L2_MEMORY_USERPTR``. | |
5377d91f MH |
16 | |
17 | This I/O method combines advantages of the read/write and memory mapping | |
18 | methods. Buffers (planes) are allocated by the application itself, and | |
19 | can reside for example in virtual or shared memory. Only pointers to | |
20 | data are exchanged, these pointers and meta-information are passed in | |
21 | struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct | |
22 | :ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The | |
23 | driver must be switched into user pointer I/O mode by calling the | |
7347081e | 24 | :ref:`VIDIOC_REQBUFS` with the desired buffer type. |
5377d91f MH |
25 | No buffers (planes) are allocated beforehand, consequently they are not |
26 | indexed and cannot be queried like mapped buffers with the | |
a163ad5c | 27 | :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl. |
5377d91f | 28 | |
282f02cb MCC |
29 | Example: Initiating streaming I/O with user pointers |
30 | ==================================================== | |
5377d91f MH |
31 | |
32 | .. code-block:: c | |
33 | ||
34 | struct v4l2_requestbuffers reqbuf; | |
35 | ||
36 | memset (&reqbuf, 0, sizeof (reqbuf)); | |
37 | reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; | |
38 | reqbuf.memory = V4L2_MEMORY_USERPTR; | |
39 | ||
40 | if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) { | |
a163ad5c MCC |
41 | if (errno == EINVAL) |
42 | printf ("Video capturing or user pointer streaming is not supported\\n"); | |
43 | else | |
44 | perror ("VIDIOC_REQBUFS"); | |
5377d91f | 45 | |
a163ad5c | 46 | exit (EXIT_FAILURE); |
5377d91f MH |
47 | } |
48 | ||
49 | Buffer (plane) addresses and sizes are passed on the fly with the | |
a163ad5c | 50 | :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly |
5377d91f | 51 | cycled, applications can pass different addresses and sizes at each |
a163ad5c MCC |
52 | :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the |
53 | driver swaps memory pages within physical memory to create a continuous | |
54 | area of memory. This happens transparently to the application in the | |
55 | virtual memory subsystem of the kernel. When buffer pages have been | |
56 | swapped out to disk they are brought back and finally locked in physical | |
4855307b | 57 | memory for DMA. [#f1]_ |
5377d91f MH |
58 | |
59 | Filled or displayed buffers are dequeued with the | |
af4a4d0d | 60 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the |
5377d91f MH |
61 | memory pages at any time between the completion of the DMA and this |
62 | ioctl. The memory is also unlocked when | |
af4a4d0d | 63 | :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called, |
7347081e | 64 | :ref:`VIDIOC_REQBUFS`, or when the device is closed. |
5377d91f MH |
65 | Applications must take care not to free buffers without dequeuing. For |
66 | once, the buffers remain locked until further, wasting physical memory. | |
67 | Second the driver will not be notified when the memory is returned to | |
68 | the application's free list and subsequently reused for other purposes, | |
69 | possibly completing the requested DMA and overwriting valuable data. | |
70 | ||
71 | For capturing applications it is customary to enqueue a number of empty | |
72 | buffers, to start capturing and enter the read loop. Here the | |
73 | application waits until a filled buffer can be dequeued, and re-enqueues | |
74 | the buffer when the data is no longer needed. Output applications fill | |
75 | and enqueue buffers, when enough buffers are stacked up output is | |
76 | started. In the write loop, when the application runs out of free | |
77 | buffers it must wait until an empty buffer can be dequeued and reused. | |
78 | Two methods exist to suspend execution of the application until one or | |
a163ad5c | 79 | more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF |
0579e6e3 | 80 | <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the |
a163ad5c MCC |
81 | ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function, |
82 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` | |
83 | error code when no buffer is available. The :ref:`select() | |
84 | <func-select>` or :ref:`poll() <func-poll>` function are always | |
85 | available. | |
5377d91f MH |
86 | |
87 | To start and stop capturing or output applications call the | |
a163ad5c | 88 | :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and |
706f8a99 MCC |
89 | :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. |
90 | ||
91 | .. note:: ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from | |
92 | both queues and unlocks all buffers as a side effect. Since there is no | |
93 | notion of doing anything "now" on a multitasking system, if an | |
94 | application needs to synchronize with another event it should examine | |
95 | the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or | |
96 | outputted buffers. | |
5377d91f MH |
97 | |
98 | Drivers implementing user pointer I/O must support the | |
a163ad5c MCC |
99 | :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, |
100 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` | |
101 | and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the | |
4855307b | 102 | :ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [#f2]_ |
5377d91f | 103 | |
4855307b | 104 | .. [#f1] |
5377d91f MH |
105 | We expect that frequently used buffers are typically not swapped out. |
106 | Anyway, the process of swapping, locking or generating scatter-gather | |
107 | lists may be time consuming. The delay can be masked by the depth of | |
108 | the incoming buffer queue, and perhaps by maintaining caches assuming | |
109 | a buffer will be soon enqueued again. On the other hand, to optimize | |
110 | memory usage drivers can limit the number of buffers locked in | |
111 | advance and recycle the most recently used buffers first. Of course, | |
112 | the pages of empty buffers in the incoming queue need not be saved to | |
113 | disk. Output buffers must be saved on the incoming and outgoing queue | |
114 | because an application may share them with other processes. | |
115 | ||
4855307b | 116 | .. [#f2] |
760c7010 MCC |
117 | At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are |
118 | the same, and :ref:`select() <func-select>` is too important to be optional. | |
5377d91f | 119 | The rest should be evident. |