media/mediactl/request-api.rst

1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
4 .. _media-request-api:
12 the same pipeline to reconfigure and collaborate closely on a per-frame basis.
14 to specific frames (aka 'per-frame controls') in order to be used efficiently.
16 While the initial use-case was V4L2, it can be extended to other subsystems
20 it is, it is terribly inefficient: user-space would have to flush all activity
22 be processed with that configuration, and wait until they are all available for
26 The Request API allows a specific configuration of the pipeline (media
27 controller topology + configuration for each media entity) to be associated with
28 specific buffers. This allows user-space to schedule several tasks ("requests")
29 with different configurations in advance, knowing that the configuration will be
30 applied when needed to get the expected result. Configuration values at the time
34 -------------
37 subsystem-specific APIs to support request usage. At the Media Controller
40 an opaque way. Configuration data, buffer handles and processing results
41 stored in requests are accessed through subsystem-specific APIs extended for
46 ------------------
48 User-space allocates requests using :ref:`MEDIA_IOC_REQUEST_ALLOC`
53 -------------------
63 ------------------
65 Once the configuration and buffers of the request are specified, it can be
71    For :ref:`memory-to-memory devices <mem2mem>` you can use requests only for
85    :ref:`closed <func-close>`. Attempts to directly queue a buffer when earlier
97 User-space can :c:func:`poll()` a request file descriptor in
101 Note that user-space does not need to wait for the request to complete to
106 executed. User-space can query that state by calling
113 .. _media-request-life-time:
116 -------------------------
130 --------------------------
132 For use-cases such as :ref:`codecs <mem2mem>`, the request API can be used
134 be applied by the driver for the OUTPUT buffer, allowing user-space
139 Put into code, after obtaining a request, user-space can assign controls and one
142 .. code-block:: c
163 since there are no per-frame settings to report there.
167 .. code-block:: c
172 User-space can then either wait for the request to complete by calling poll() on
177 .. code-block:: c
195 .. code-block:: c
198 	poll(&pfd, 1, -1);
208 .. code-block:: c
215 .. code-block:: c
220 -----------------------------------
225 .. code-block:: c
247 .. code-block:: c
252 User-space can then dequeue buffers, wait for the request completion, query