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