Lines Matching full:request

27 .. _media-request-api:
29 Request API
32 The Request API has been designed to allow V4L2 to deal with requirements of
42 Supporting these features without the Request API is not always possible and if
49 The Request API allows a specific configuration of the pipeline (media
54 of request completion are also available for reading.
59 The Request API extends the Media Controller API and cooperates with
60 subsystem-specific APIs to support request usage. At the Media Controller
62 node. Their life cycle is then managed through the request file descriptors in
65 request support, such as V4L2 APIs that take an explicit ``request_fd``
68 Request Allocation
73 request. Typically, several such requests will be allocated.
75 Request Preparation
78 Standard V4L2 ioctls can then receive a request file descriptor to express the
79 fact that the ioctl is part of said request, and is not to be applied
82 instead of being immediately applied, and buffers queued to a request do not
83 enter the regular buffer queue until the request itself is queued.
85 Request Submission
88 Once the configuration and buffers of the request are specified, it can be
89 queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor.
90 A request must contain at least one buffer, otherwise ``ENOENT`` is returned.
91 A queued request cannot be modified anymore.
96    to a request will result in an ``EBADR`` error.
98 If the request contains configurations for multiple entities, individual drivers
109    a buffer was queued via a request or vice versa will result in an ``EBUSY``
112 Controls can still be set without a request and are applied immediately,
113 regardless of whether a request is in use or not.
117    Setting the same control through a request and also directly can lead to
120 User-space can :ref:`poll() <request-func-poll>` a request file descriptor in
121 order to wait until the request completes. A request is considered complete
124 Note that user-space does not need to wait for the request to complete to
125 dequeue its buffers: buffers that are available halfway through a request can
126 be dequeued independently of the request's state.
128 A completed request contains the state of the device after the request was
130 :ref:`ioctl VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with the request file
132 request that has been queued but not yet completed will return ``EBUSY``
134 request is in flight.
136 .. _media-request-life-time:
141 Finally, a completed request can either be discarded or be reused. Calling
142 :ref:`close() <request-func-close>` on a request file descriptor will make
143 that file descriptor unusable and the request will be freed once it is no
144 longer in use by the kernel. That is, if the request is queued and then the
146 the request.
148 The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it
149 available again. No state is retained by this operation: the request is as
155 For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
159 ability to capture the state of controls when the request completes to read back
162 Put into code, after obtaining a request, user-space can assign controls and one
185 Note that it is not allowed to use the Request API for CAPTURE buffers
188 Once the request is fully prepared, it can be queued to the driver:
195 User-space can then either wait for the request to complete by calling poll() on
212 We can then, after ensuring that the request is completed via polling the
213 request file descriptor, query control values at the time of its completion via
228 Once we don't need the request anymore, we can either recycle it for reuse with
268 Once the request is fully prepared, it can be queued to the driver:
275 User-space can then dequeue buffers, wait for the request completion, query
276 controls and recycle the request as in the M2M example above.