1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.
2 .. c:namespace:: MC
3
4 .. _media-request-api:
5
6 Request API
7 ===========
8
9 The Request API has been designed to allow V4L
10 modern devices (stateless codecs, complex came
11 (Android Codec v2). One such requirement is th
12 the same pipeline to reconfigure and collabora
13 Another is support of stateless codecs, which
14 to specific frames (aka 'per-frame controls')
15
16 While the initial use-case was V4L2, it can be
17 as well, as long as they use the media control
18
19 Supporting these features without the Request
20 it is, it is terribly inefficient: user-space
21 on the media pipeline, reconfigure it for the
22 be processed with that configuration, and wait
23 dequeuing before considering the next frame. T
24 buffer queues since in practice only one buffe
25
26 The Request API allows a specific configuratio
27 controller topology + configuration for each m
28 specific buffers. This allows user-space to sc
29 with different configurations in advance, know
30 applied when needed to get the expected result
31 of request completion are also available for r
32
33 General Usage
34 -------------
35
36 The Request API extends the Media Controller A
37 subsystem-specific APIs to support request usa
38 level, requests are allocated from the support
39 node. Their life cycle is then managed through
40 an opaque way. Configuration data, buffer hand
41 stored in requests are accessed through subsys
42 request support, such as V4L2 APIs that take a
43 parameter.
44
45 Request Allocation
46 ------------------
47
48 User-space allocates requests using :ref:`MEDI
49 for the media device node. This returns a file
50 request. Typically, several such requests will
51
52 Request Preparation
53 -------------------
54
55 Standard V4L2 ioctls can then receive a reques
56 fact that the ioctl is part of said request, a
57 immediately. See :ref:`MEDIA_IOC_REQUEST_ALLOC
58 support this. Configurations set with a ``requ
59 instead of being immediately applied, and buff
60 enter the regular buffer queue until the reque
61
62 Request Submission
63 ------------------
64
65 Once the configuration and buffers of the requ
66 queued by calling :ref:`MEDIA_REQUEST_IOC_QUEU
67 A request must contain at least one buffer, ot
68 A queued request cannot be modified anymore.
69
70 .. caution::
71 For :ref:`memory-to-memory devices <mem2mem
72 output buffers, not for capture buffers. At
73 to a request will result in an ``EBADR`` er
74
75 If the request contains configurations for mul
76 may synchronize so the requested pipeline's to
77 buffers are processed. Media controller driver
78 since perfect atomicity may not be possible du
79
80 .. caution::
81
82 It is not allowed to mix queuing requests w
83 whichever method is used first locks this i
84 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` i
85 :ref:`closed <func-close>`. Attempts to dir
86 a buffer was queued via a request or vice v
87 error.
88
89 Controls can still be set without a request an
90 regardless of whether a request is in use or n
91
92 .. caution::
93
94 Setting the same control through a request
95 undefined behavior!
96
97 User-space can :c:func:`poll()` a request file
98 order to wait until the request completes. A r
99 once all its associated buffers are available
100 associated controls have been updated with the
101 Note that user-space does not need to wait for
102 dequeue its buffers: buffers that are availabl
103 be dequeued independently of the request's sta
104
105 A completed request contains the state of the
106 executed. User-space can query that state by c
107 :ref:`ioctl VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_C
108 descriptor. Calling :ref:`ioctl VIDIOC_G_EXT_C
109 request that has been queued but not yet compl
110 since the control values might be changed at a
111 request is in flight.
112
113 .. _media-request-life-time:
114
115 Recycling and Destruction
116 -------------------------
117
118 Finally, a completed request can either be dis
119 :c:func:`close()` on a request file descriptor
120 that file descriptor unusable and the request
121 longer in use by the kernel. That is, if the r
122 file descriptor is closed, then it won't be fr
123 the request.
124
125 The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear
126 available again. No state is retained by this
127 if it had just been allocated.
128
129 Example for a Codec Device
130 --------------------------
131
132 For use-cases such as :ref:`codecs <mem2mem>`,
133 to associate specific controls to
134 be applied by the driver for the OUTPUT buffer
135 to queue many such buffers in advance. It can
136 ability to capture the state of controls when
137 information that may be subject to change.
138
139 Put into code, after obtaining a request, user
140 OUTPUT buffer to it:
141
142 .. code-block:: c
143
144 struct v4l2_buffer buf;
145 struct v4l2_ext_controls ctrls;
146 int req_fd;
147 ...
148 if (ioctl(media_fd, MEDIA_IOC_REQUEST_
149 return errno;
150 ...
151 ctrls.which = V4L2_CTRL_WHICH_REQUEST_
152 ctrls.request_fd = req_fd;
153 if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS
154 return errno;
155 ...
156 buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
157 buf.flags |= V4L2_BUF_FLAG_REQUEST_FD;
158 buf.request_fd = req_fd;
159 if (ioctl(codec_fd, VIDIOC_QBUF, &buf)
160 return errno;
161
162 Note that it is not allowed to use the Request
163 since there are no per-frame settings to repor
164
165 Once the request is fully prepared, it can be
166
167 .. code-block:: c
168
169 if (ioctl(req_fd, MEDIA_REQUEST_IOC_QU
170 return errno;
171
172 User-space can then either wait for the reques
173 its file descriptor, or start dequeuing CAPTUR
174 want to get CAPTURE buffers as soon as possibl
175 regular :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`:
176
177 .. code-block:: c
178
179 struct v4l2_buffer buf;
180
181 memset(&buf, 0, sizeof(buf));
182 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE
183 if (ioctl(codec_fd, VIDIOC_DQBUF, &buf
184 return errno;
185
186 Note that this example assumes for simplicity
187 there will be one CAPTURE buffer, but this doe
188
189 We can then, after ensuring that the request i
190 request file descriptor, query control values
191 a call to :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_E
192 This is particularly useful for volatile contr
193 query values as soon as the capture buffer is
194
195 .. code-block:: c
196
197 struct pollfd pfd = { .events = POLLPR
198 poll(&pfd, 1, -1);
199 ...
200 ctrls.which = V4L2_CTRL_WHICH_REQUEST_
201 ctrls.request_fd = req_fd;
202 if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS
203 return errno;
204
205 Once we don't need the request anymore, we can
206 :ref:`MEDIA_REQUEST_IOC_REINIT`...
207
208 .. code-block:: c
209
210 if (ioctl(req_fd, MEDIA_REQUEST_IOC_RE
211 return errno;
212
213 ... or close its file descriptor to completely
214
215 .. code-block:: c
216
217 close(req_fd);
218
219 Example for a Simple Capture Device
220 -----------------------------------
221
222 With a simple capture device, requests can be
223 for a given CAPTURE buffer.
224
225 .. code-block:: c
226
227 struct v4l2_buffer buf;
228 struct v4l2_ext_controls ctrls;
229 int req_fd;
230 ...
231 if (ioctl(media_fd, MEDIA_IOC_REQUEST_
232 return errno;
233 ...
234 ctrls.which = V4L2_CTRL_WHICH_REQUEST_
235 ctrls.request_fd = req_fd;
236 if (ioctl(camera_fd, VIDIOC_S_EXT_CTRL
237 return errno;
238 ...
239 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE
240 buf.flags |= V4L2_BUF_FLAG_REQUEST_FD;
241 buf.request_fd = req_fd;
242 if (ioctl(camera_fd, VIDIOC_QBUF, &buf
243 return errno;
244
245 Once the request is fully prepared, it can be
246
247 .. code-block:: c
248
249 if (ioctl(req_fd, MEDIA_REQUEST_IOC_QU
250 return errno;
251
252 User-space can then dequeue buffers, wait for
253 controls and recycle the request as in the M2M
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.