€•9Œsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œhj6ubhŒ parameter.”…””}”(hj6h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K$hj%h²hubeh}”(h]”Œ general-usage”ah ]”h"]”Œ general usage”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K"ubh×)”}”(hhh]”(hÜ)”}”(hŒRequest Allocation”h]”hŒRequest Allocation”…””}”(hjch²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhj`h²hh³hÇh´K.ubhì)”}”(hŒÊUser-space allocates requests using :ref:`MEDIA_IOC_REQUEST_ALLOC` for the media device node. This returns a file descriptor representing the request. Typically, several such requests will be allocated.”h]”(hŒ$User-space allocates requests using ”…””}”(hjqh²hh³Nh´Nubh)”}”(hŒ:ref:`MEDIA_IOC_REQUEST_ALLOC`”h]”hŒinline”“”)”}”(hj{h]”hŒMEDIA_IOC_REQUEST_ALLOC”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”(Œxref”Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hjyubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”Œ(userspace-api/media/mediactl/request-api”Œ refdomain”jŠŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆŒ reftarget”Œmedia_ioc_request_alloc”uh1hh³hÇh´K0hjqubhŒˆ for the media device node. This returns a file descriptor representing the request. Typically, several such requests will be allocated.”…””}”(hjqh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K0hj`h²hubeh}”(h]”Œrequest-allocation”ah ]”h"]”Œrequest allocation”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K.ubh×)”}”(hhh]”(hÜ)”}”(hŒRequest Preparation”h]”hŒRequest Preparation”…””}”(hj³h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhj°h²hh³hÇh´K5ubhì)”}”(hXºStandard V4L2 ioctls can then receive a request file descriptor to express the fact that the ioctl is part of said request, and is not to be applied immediately. See :ref:`MEDIA_IOC_REQUEST_ALLOC` for a list of ioctls that support this. Configurations set with a ``request_fd`` parameter are stored instead of being immediately applied, and buffers queued to a request do not enter the regular buffer queue until the request itself is queued.”h]”(hŒ¦Standard V4L2 ioctls can then receive a request file descriptor to express the fact that the ioctl is part of said request, and is not to be applied immediately. See ”…””}”(hjÁh²hh³Nh´Nubh)”}”(hŒ:ref:`MEDIA_IOC_REQUEST_ALLOC`”h]”j~)”}”(hjËh]”hŒMEDIA_IOC_REQUEST_ALLOC”…””}”(hjÍh²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hjÉubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”j׌reftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjœŒmedia_ioc_request_alloc”uh1hh³hÇh´K7hjÁubhŒC for a list of ioctls that support this. Configurations set with a ”…””}”(hjÁh²hh³Nh´Nubj?)”}”(hŒ``request_fd``”h]”hŒ request_fd”…””}”(hjíh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j>hjÁubhŒ¥ parameter are stored instead of being immediately applied, and buffers queued to a request do not enter the regular buffer queue until the request itself is queued.”…””}”(hjÁh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K7hj°h²hubeh}”(h]”Œrequest-preparation”ah ]”h"]”Œrequest preparation”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K5ubh×)”}”(hhh]”(hÜ)”}”(hŒRequest Submission”h]”hŒRequest Submission”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhj h²hh³hÇh´K?ubhì)”}”(hXOnce the configuration and buffers of the request are specified, it can be queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor. A request must contain at least one buffer, otherwise ``ENOENT`` is returned. A queued request cannot be modified anymore.”h]”(hŒ]Once the configuration and buffers of the request are specified, it can be queued by calling ”…””}”(hjh²hh³Nh´Nubh)”}”(hŒ:ref:`MEDIA_REQUEST_IOC_QUEUE`”h]”j~)”}”(hj(h]”hŒMEDIA_REQUEST_IOC_QUEUE”…””}”(hj*h²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj&ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”j4Œreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjœŒmedia_request_ioc_queue”uh1hh³hÇh´KAhjubhŒW on the request file descriptor. A request must contain at least one buffer, otherwise ”…””}”(hjh²hh³Nh´Nubj?)”}”(hŒ ``ENOENT``”h]”hŒENOENT”…””}”(hjJh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j>hjubhŒ: is returned. A queued request cannot be modified anymore.”…””}”(hjh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KAhj h²hubhŒcaution”“”)”}”(hŒÇFor :ref:`memory-to-memory devices ` you can use requests only for output buffers, not for capture buffers. Attempting to add a capture buffer to a request will result in an ``EBADR`` error.”h]”hì)”}”(hŒÇFor :ref:`memory-to-memory devices ` you can use requests only for output buffers, not for capture buffers. Attempting to add a capture buffer to a request will result in an ``EBADR`` error.”h]”(hŒFor ”…””}”(hjhh²hh³Nh´Nubh)”}”(hŒ):ref:`memory-to-memory devices `”h]”j~)”}”(hjrh]”hŒmemory-to-memory devices”…””}”(hjth²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hjpubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”j~Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒmem2mem”uh1hh³hÇh´KGhjhubhŒŠ you can use requests only for output buffers, not for capture buffers. Attempting to add a capture buffer to a request will result in an ”…””}”(hjhh²hh³Nh´Nubj?)”}”(hŒ ``EBADR``”h]”hŒEBADR”…””}”(hj”h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j>hjhubhŒ error.”…””}”(hjhh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KGhjdubah}”(h]”h ]”h"]”h$]”h&]”uh1jbhj h²hh³hÇh´Nubhì)”}”(hX4If the request contains configurations for multiple entities, individual drivers may synchronize so the requested pipeline's topology is applied before the buffers are processed. Media controller drivers do a best effort implementation since perfect atomicity may not be possible due to hardware limitations.”h]”hX6If the request contains configurations for multiple entities, individual drivers may synchronize so the requested pipeline’s topology is applied before the buffers are processed. Media controller drivers do a best effort implementation since perfect atomicity may not be possible due to hardware limitations.”…””}”(hj²h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KKhj h²hubjc)”}”(hXfIt is not allowed to mix queuing requests with directly queuing buffers: whichever method is used first locks this in place until :ref:`VIDIOC_STREAMOFF ` is called or the device is :ref:`closed `. Attempts to directly queue a buffer when earlier a buffer was queued via a request or vice versa will result in an ``EBUSY`` error.”h]”hì)”}”(hXfIt is not allowed to mix queuing requests with directly queuing buffers: whichever method is used first locks this in place until :ref:`VIDIOC_STREAMOFF ` is called or the device is :ref:`closed `. Attempts to directly queue a buffer when earlier a buffer was queued via a request or vice versa will result in an ``EBUSY`` error.”h]”(hŒ‚It is not allowed to mix queuing requests with directly queuing buffers: whichever method is used first locks this in place until ”…””}”(hjÄh²hh³Nh´Nubh)”}”(hŒ):ref:`VIDIOC_STREAMOFF `”h]”j~)”}”(hjÎh]”hŒVIDIOC_STREAMOFF”…””}”(hjÐh²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hjÌubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jÚŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒvidioc_streamon”uh1hh³hÇh´KRhjÄubhŒ is called or the device is ”…””}”(hjÄh²hh³Nh´Nubh)”}”(hŒ:ref:`closed `”h]”j~)”}”(hjòh]”hŒclosed”…””}”(hjôh²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hjðubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jþŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒ func-close”uh1hh³hÇh´KRhjÄubhŒu. Attempts to directly queue a buffer when earlier a buffer was queued via a request or vice versa will result in an ”…””}”(hjÄh²hh³Nh´Nubj?)”}”(hŒ ``EBUSY``”h]”hŒEBUSY”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j>hjÄubhŒ error.”…””}”(hjÄh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KRhjÀubah}”(h]”h ]”h"]”h$]”h&]”uh1jbhj h²hh³hÇh´Nubhì)”}”(hŒzControls can still be set without a request and are applied immediately, regardless of whether a request is in use or not.”h]”hŒzControls can still be set without a request and are applied immediately, regardless of whether a request is in use or not.”…””}”(hj2h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KYhj h²hubjc)”}”(hŒ\Setting the same control through a request and also directly can lead to undefined behavior!”h]”hì)”}”(hŒ\Setting the same control through a request and also directly can lead to undefined behavior!”h]”hŒ\Setting the same control through a request and also directly can lead to undefined behavior!”…””}”(hjDh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K^hj@ubah}”(h]”h ]”h"]”h$]”h&]”uh1jbhj h²hh³hÇh´Nubhì)”}”(hXëUser-space can :c:func:`poll()` a request file descriptor in order to wait until the request completes. A request is considered complete once all its associated buffers are available for dequeuing and all the associated controls have been updated with the values at the time of completion. Note that user-space does not need to wait for the request to complete to dequeue its buffers: buffers that are available halfway through a request can be dequeued independently of the request's state.”h]”(hŒUser-space can ”…””}”(hjXh²hh³Nh´Nubh)”}”(hŒ:c:func:`poll()`”h]”j?)”}”(hjbh]”hŒpoll()”…””}”(hjdh²hh³Nh´Nubah}”(h]”h ]”(j‰Œc”Œc-func”eh"]”h$]”h&]”uh1j>hj`ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jnŒreftype”Œfunc”Œ refexplicit”‰Œrefwarn”‰Œ c:parent_key”Œsphinx.domains.c”Œ LookupKey”“”)”}”Œdata”]”j€Œ ASTIdentifier”“”)”}”Œ identifier”ŒMC”sbN†”asbjœŒpoll”uh1hh³hÇh´KahjXubhXÎ a request file descriptor in order to wait until the request completes. A request is considered complete once all its associated buffers are available for dequeuing and all the associated controls have been updated with the values at the time of completion. Note that user-space does not need to wait for the request to complete to dequeue its buffers: buffers that are available halfway through a request can be dequeued independently of the request’s state.”…””}”(hjXh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kahj h²hubhì)”}”(hXÆA completed request contains the state of the device after the request was executed. User-space can query that state by calling :ref:`ioctl VIDIOC_G_EXT_CTRLS ` with the request file descriptor. Calling :ref:`ioctl VIDIOC_G_EXT_CTRLS ` for a request that has been queued but not yet completed will return ``EBUSY`` since the control values might be changed at any time by the driver while the request is in flight.”h]”(hŒ€A completed request contains the state of the device after the request was executed. User-space can query that state by calling ”…””}”(hj™h²hh³Nh´Nubh)”}”(hŒ4:ref:`ioctl VIDIOC_G_EXT_CTRLS `”h]”j~)”}”(hj£h]”hŒioctl VIDIOC_G_EXT_CTRLS”…””}”(hj¥h²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj¡ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”j¯Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒvidioc_g_ext_ctrls”uh1hh³hÇh´Kihj™ubhŒ+ with the request file descriptor. Calling ”…””}”(hj™h²hh³Nh´Nubh)”}”(hŒ4:ref:`ioctl VIDIOC_G_EXT_CTRLS `”h]”j~)”}”(hjÇh]”hŒioctl VIDIOC_G_EXT_CTRLS”…””}”(hjÉh²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hjÅubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jÓŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒvidioc_g_ext_ctrls”uh1hh³hÇh´Kihj™ubhŒF for a request that has been queued but not yet completed will return ”…””}”(hj™h²hh³Nh´Nubj?)”}”(hŒ ``EBUSY``”h]”hŒEBUSY”…””}”(hjéh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j>hj™ubhŒd since the control values might be changed at any time by the driver while the request is in flight.”…””}”(hj™h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kihj h²hubhÉ)”}”(hŒ.. _media-request-life-time:”h]”h}”(h]”h ]”h"]”h$]”h&]”hÔŒmedia-request-life-time”uh1hÈh´Kqhj h²hh³hÇubeh}”(h]”Œrequest-submission”ah ]”h"]”Œrequest submission”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K?ubh×)”}”(hhh]”(hÜ)”}”(hŒRecycling and Destruction”h]”hŒRecycling and Destruction”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhjh²hh³hÇh´Ktubhì)”}”(hXsFinally, a completed request can either be discarded or be reused. Calling :c:func:`close()` on a request file descriptor will make that file descriptor unusable and the request will be freed once it is no longer in use by the kernel. That is, if the request is queued and then the file descriptor is closed, then it won't be freed until the driver completed the request.”h]”(hŒKFinally, a completed request can either be discarded or be reused. Calling ”…””}”(hj%h²hh³Nh´Nubh)”}”(hŒ:c:func:`close()`”h]”j?)”}”(hj/h]”hŒclose()”…””}”(hj1h²hh³Nh´Nubah}”(h]”h ]”(j‰jnŒc-func”eh"]”h$]”h&]”uh1j>hj-ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jnŒreftype”Œfunc”Œ refexplicit”‰Œrefwarn”‰jjƒjœŒclose”uh1hh³hÇh´Kvhj%ubhX on a request file descriptor will make that file descriptor unusable and the request will be freed once it is no longer in use by the kernel. That is, if the request is queued and then the file descriptor is closed, then it won’t be freed until the driver completed the request.”…””}”(hj%h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kvhjh²hubhì)”}”(hŒ¶The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it available again. No state is retained by this operation: the request is as if it had just been allocated.”h]”(hŒThe ”…””}”(hjVh²hh³Nh´Nubh)”}”(hŒ:ref:`MEDIA_REQUEST_IOC_REINIT`”h]”j~)”}”(hj`h]”hŒMEDIA_REQUEST_IOC_REINIT”…””}”(hjbh²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj^ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jlŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjœŒmedia_request_ioc_reinit”uh1hh³hÇh´K}hjVubhŒ• will clear a request’s state and make it available again. No state is retained by this operation: the request is as if it had just been allocated.”…””}”(hjVh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K}hjh²hubeh}”(h]”(Œrecycling-and-destruction”j eh ]”h"]”(Œrecycling and destruction”Œmedia-request-life-time”eh$]”h&]”uh1hÖhhØh²hh³hÇh´KtŒexpect_referenced_by_name”}”jŽjsŒexpect_referenced_by_id”}”j jsubh×)”}”(hhh]”(hÜ)”}”(hŒExample for a Codec Device”h]”hŒExample for a Codec Device”…””}”(hj˜h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhj•h²hh³hÇh´K‚ubhì)”}”(hX{For use-cases such as :ref:`codecs `, the request API can be used to associate specific controls to be applied by the driver for the OUTPUT buffer, allowing user-space to queue many such buffers in advance. It can also take advantage of requests' ability to capture the state of controls when the request completes to read back information that may be subject to change.”h]”(hŒFor use-cases such as ”…””}”(hj¦h²hh³Nh´Nubh)”}”(hŒ:ref:`codecs `”h]”j~)”}”(hj°h]”hŒcodecs”…””}”(hj²h²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj®ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”j¼Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒmem2mem”uh1hh³hÇh´K„hj¦ubhXP, the request API can be used to associate specific controls to be applied by the driver for the OUTPUT buffer, allowing user-space to queue many such buffers in advance. It can also take advantage of requests’ ability to capture the state of controls when the request completes to read back information that may be subject to change.”…””}”(hj¦h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K„hj•h²hubhì)”}”(hŒePut into code, after obtaining a request, user-space can assign controls and one OUTPUT buffer to it:”h]”hŒePut into code, after obtaining a request, user-space can assign controls and one OUTPUT buffer to it:”…””}”(hjØh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K‹hj•h²hubhŒ literal_block”“”)”}”(hXÎstruct v4l2_buffer buf; struct v4l2_ext_controls ctrls; int req_fd; ... if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) return errno; ... ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; ctrls.request_fd = req_fd; if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) return errno; ... buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; buf.request_fd = req_fd; if (ioctl(codec_fd, VIDIOC_QBUF, &buf)) return errno;”h]”hXÎstruct v4l2_buffer buf; struct v4l2_ext_controls ctrls; int req_fd; ... if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) return errno; ... ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; ctrls.request_fd = req_fd; if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) return errno; ... buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; buf.request_fd = req_fd; if (ioctl(codec_fd, VIDIOC_QBUF, &buf)) return errno;”…””}”hjèsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆŒforce”‰Œlanguage”jnŒhighlight_args”}”uh1jæh³hÇh´KŽhj•h²hubhì)”}”(hŒ}Note that it is not allowed to use the Request API for CAPTURE buffers since there are no per-frame settings to report there.”h]”hŒ}Note that it is not allowed to use the Request API for CAPTURE buffers since there are no per-frame settings to report there.”…””}”(hjúh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K¢hj•h²hubhì)”}”(hŒCOnce the request is fully prepared, it can be queued to the driver:”h]”hŒCOnce the request is fully prepared, it can be queued to the driver:”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K¥hj•h²hubjç)”}”(hŒAif (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) return errno;”h]”hŒAif (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) return errno;”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´K§hj•h²hubhì)”}”(hXUser-space can then either wait for the request to complete by calling poll() on its file descriptor, or start dequeuing CAPTURE buffers. Most likely, it will want to get CAPTURE buffers as soon as possible and this can be done using a regular :ref:`VIDIOC_DQBUF `:”h]”(hŒôUser-space can then either wait for the request to complete by calling poll() on its file descriptor, or start dequeuing CAPTURE buffers. Most likely, it will want to get CAPTURE buffers as soon as possible and this can be done using a regular ”…””}”(hj%h²hh³Nh´Nubh)”}”(hŒ!:ref:`VIDIOC_DQBUF `”h]”j~)”}”(hj/h]”hŒ VIDIOC_DQBUF”…””}”(hj1h²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj-ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”j;Œreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒ vidioc_qbuf”uh1hh³hÇh´K¬hj%ubhŒ:”…””}”(hj%h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K¬hj•h²hubjç)”}”(hŒstruct v4l2_buffer buf; memset(&buf, 0, sizeof(buf)); buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; if (ioctl(codec_fd, VIDIOC_DQBUF, &buf)) return errno;”h]”hŒstruct v4l2_buffer buf; memset(&buf, 0, sizeof(buf)); buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; if (ioctl(codec_fd, VIDIOC_DQBUF, &buf)) return errno;”…””}”hjWsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´K±hj•h²hubhì)”}”(hŒ“Note that this example assumes for simplicity that for every OUTPUT buffer there will be one CAPTURE buffer, but this does not have to be the case.”h]”hŒ“Note that this example assumes for simplicity that for every OUTPUT buffer there will be one CAPTURE buffer, but this does not have to be the case.”…””}”(hjfh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kºhj•h²hubhì)”}”(hXRWe can then, after ensuring that the request is completed via polling the request file descriptor, query control values at the time of its completion via a call to :ref:`VIDIOC_G_EXT_CTRLS `. This is particularly useful for volatile controls for which we want to query values as soon as the capture buffer is produced.”h]”(hŒ¤We can then, after ensuring that the request is completed via polling the request file descriptor, query control values at the time of its completion via a call to ”…””}”(hjth²hh³Nh´Nubh)”}”(hŒ.:ref:`VIDIOC_G_EXT_CTRLS `”h]”j~)”}”(hj~h]”hŒVIDIOC_G_EXT_CTRLS”…””}”(hj€h²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj|ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jŠŒreftype”Œref”Œ refexplicit”ˆŒrefwarn”ˆjœŒvidioc_g_ext_ctrls”uh1hh³hÇh´K½hjtubhŒ€. This is particularly useful for volatile controls for which we want to query values as soon as the capture buffer is produced.”…””}”(hjth²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´K½hj•h²hubjç)”}”(hŒÜstruct pollfd pfd = { .events = POLLPRI, .fd = req_fd }; poll(&pfd, 1, -1); ... ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; ctrls.request_fd = req_fd; if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS, &ctrls)) return errno;”h]”hŒÜstruct pollfd pfd = { .events = POLLPRI, .fd = req_fd }; poll(&pfd, 1, -1); ... ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; ctrls.request_fd = req_fd; if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS, &ctrls)) return errno;”…””}”hj¦sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´KÃhj•h²hubhì)”}”(hŒrOnce we don't need the request anymore, we can either recycle it for reuse with :ref:`MEDIA_REQUEST_IOC_REINIT`...”h]”(hŒROnce we don’t need the request anymore, we can either recycle it for reuse with ”…””}”(hjµh²hh³Nh´Nubh)”}”(hŒ:ref:`MEDIA_REQUEST_IOC_REINIT`”h]”j~)”}”(hj¿h]”hŒMEDIA_REQUEST_IOC_REINIT”…””}”(hjÁh²hh³Nh´Nubah}”(h]”h ]”(j‰Œstd”Œstd-ref”eh"]”h$]”h&]”uh1j}hj½ubah}”(h]”h ]”h"]”h$]”h&]”Œrefdoc”j–Œ refdomain”jËŒreftype”Œref”Œ refexplicit”‰Œrefwarn”ˆjœŒmedia_request_ioc_reinit”uh1hh³hÇh´KÍhjµubhŒ...”…””}”(hjµh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÍhj•h²hubjç)”}”(hŒBif (ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT)) return errno;”h]”hŒBif (ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT)) return errno;”…””}”hjçsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´KÐhj•h²hubhì)”}”(hŒ=... or close its file descriptor to completely dispose of it.”h]”hŒ=... or close its file descriptor to completely dispose of it.”…””}”(hjöh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÕhj•h²hubjç)”}”(hŒclose(req_fd);”h]”hŒclose(req_fd);”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´K×hj•h²hubeh}”(h]”Œexample-for-a-codec-device”ah ]”h"]”Œexample for a codec device”ah$]”h&]”uh1hÖhhØh²hh³hÇh´K‚ubh×)”}”(hhh]”(hÜ)”}”(hŒ#Example for a Simple Capture Device”h]”hŒ#Example for a Simple Capture Device”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÛhjh²hh³hÇh´KÜubhì)”}”(hŒkWith a simple capture device, requests can be used to specify controls to apply for a given CAPTURE buffer.”h]”hŒkWith a simple capture device, requests can be used to specify controls to apply for a given CAPTURE buffer.”…””}”(hj,h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´KÞhjh²hubjç)”}”(hXÑstruct v4l2_buffer buf; struct v4l2_ext_controls ctrls; int req_fd; ... if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) return errno; ... ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; ctrls.request_fd = req_fd; if (ioctl(camera_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) return errno; ... buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; buf.request_fd = req_fd; if (ioctl(camera_fd, VIDIOC_QBUF, &buf)) return errno;”h]”hXÑstruct v4l2_buffer buf; struct v4l2_ext_controls ctrls; int req_fd; ... if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) return errno; ... ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; ctrls.request_fd = req_fd; if (ioctl(camera_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) return errno; ... buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; buf.request_fd = req_fd; if (ioctl(camera_fd, VIDIOC_QBUF, &buf)) return errno;”…””}”hj:sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´Káhjh²hubhì)”}”(hŒCOnce the request is fully prepared, it can be queued to the driver:”h]”hŒCOnce the request is fully prepared, it can be queued to the driver:”…””}”(hjIh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kõhjh²hubjç)”}”(hŒAif (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) return errno;”h]”hŒAif (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) return errno;”…””}”hjWsbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆjö‰j÷jnjø}”uh1jæh³hÇh´K÷hjh²hubhì)”}”(hŒ‰User-space can then dequeue buffers, wait for the request completion, query controls and recycle the request as in the M2M example above.”h]”hŒ‰User-space can then dequeue buffers, wait for the request completion, query controls and recycle the request as in the M2M example above.”…””}”(hjfh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÇh´Kühjh²hubeh}”(h]”Œ#example-for-a-simple-capture-device”ah ]”h"]”Œ#example for a simple capture device”ah$]”h&]”uh1hÖhhØh²hh³hÇh´KÜubeh}”(h]”(Œ request-api”hÕeh ]”h"]”(Œ request api”Œmedia-request-api”eh$]”h&]”uh1hÖhhh²hh³hÇh´Kj‘}”j‚hÊsj“}”hÕhÊsubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÇuh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÛNŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jªŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÇŒ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”(hÕ]”hÊaj ]”jauŒnameids”}”(j‚hÕjj~j]jZj­jªj jjjjŽj jjŠjjjyjvuŒ nametypes”}”(j‚ˆj‰j]‰j­‰j ‰j‰jŽˆj‰j‰jy‰uh}”(hÕhØj~hØjZj%jªj`jj°jj j jjŠjjj•jvjuŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”(hŒsystem_message”“”)”}”(hhh]”hì)”}”(hhh]”hŒ7Hyperlink target "media-request-api" is not referenced.”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”uh1hëhjubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œsource”hÇŒline”Kuh1jubj)”}”(hhh]”hì)”}”(hhh]”hŒ=Hyperlink target "media-request-life-time" is not referenced.”…””}”hj0sbah}”(h]”h ]”h"]”h$]”h&]”uh1hëhj-ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”j*Œsource”hÇŒline”Kquh1jubeŒ transformer”NŒ include_log”]”Œ decoration”Nh²hub.