Lines Matching full:request

4 .. _media-request-api:
6 Request API
9 The Request API has been designed to allow V4L2 to deal with requirements of
19 Supporting these features without the Request API is not always possible and if
26 The Request API allows a specific configuration of the pipeline (media
31 of request completion are also available for reading.
36 The Request API extends the Media Controller API and cooperates with
37 subsystem-specific APIs to support request usage. At the Media Controller
39 node. Their life cycle is then managed through the request file descriptors in
42 request support, such as V4L2 APIs that take an explicit ``request_fd``
45 Request Allocation
50 request. Typically, several such requests will be allocated.
52 Request Preparation
55 Standard V4L2 ioctls can then receive a request file descriptor to express the
56 fact that the ioctl is part of said request, and is not to be applied
59 instead of being immediately applied, and buffers queued to a request do not
60 enter the regular buffer queue until the request itself is queued.
62 Request Submission
65 Once the configuration and buffers of the request are specified, it can be
66 queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor.
67 A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
68 A queued request cannot be modified anymore.
73    to a request will result in an ``EBADR`` error.
75 If the request contains configurations for multiple entities, individual drivers
86    a buffer was queued via a request or vice versa will result in an ``EBUSY``
89 Controls can still be set without a request and are applied immediately,
90 regardless of whether a request is in use or not.
94    Setting the same control through a request and also directly can lead to
97 User-space can :c:func:`poll()` a request file descriptor in
98 order to wait until the request completes. A request is considered complete
101 Note that user-space does not need to wait for the request to complete to
102 dequeue its buffers: buffers that are available halfway through a request can
103 be dequeued independently of the request's state.
105 A completed request contains the state of the device after the request was
107 :ref:`ioctl VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with the request file
109 request that has been queued but not yet completed will return ``EBUSY``
111 request is in flight.
113 .. _media-request-life-time:
118 Finally, a completed request can either be discarded or be reused. Calling
119 :c:func:`close()` on a request file descriptor will make
120 that file descriptor unusable and the request will be freed once it is no
121 longer in use by the kernel. That is, if the request is queued and then the
123 the request.
125 The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it
126 available again. No state is retained by this operation: the request is as
132 For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
136 ability to capture the state of controls when the request completes to read back
139 Put into code, after obtaining a request, user-space can assign controls and one
162 Note that it is not allowed to use the Request API for CAPTURE buffers
165 Once the request is fully prepared, it can be queued to the driver:
172 User-space can then either wait for the request to complete by calling poll() on
189 We can then, after ensuring that the request is completed via polling the
190 request file descriptor, query control values at the time of its completion via
205 Once we don't need the request anymore, we can either recycle it for reuse with
245 Once the request is fully prepared, it can be queued to the driver:
252 User-space can then dequeue buffers, wait for the request completion, query
253 controls and recycle the request as in the M2M example above.