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