V4L2 Requests: Bind Per-Frame Controls Without Reusing an In-Flight Request

An embedded stateless-codec pipeline can queue multiple frames with different controls, but it must keep each control set attached to the intended work. A request file descriptor supplies that association. Reusing it as a mutable “current settings” object while earlier work is still in flight breaks the request lifecycle.

This guide pins Linux v6.12’s Request API and considers a request-capable memory-to-memory codec. It does not assert that every camera or decoder supports requests. The A/B sequence below is a proposed ownership model, not a decoding run or a hardware-atomicity measurement.

Construct one work description before submission

Allocate a request through the supporting media-device interface. The Request API guide distinguishes preparing a request from submitting it: request-associated settings are staged, and its buffers do not enter the regular queue until the request is queued.

For a hypothetical pair of coded inputs, let A require control set CA and B require CB. Keep separate request objects for those concurrently pending work descriptions. Record each object’s application generation, associated input and intended controls before submission.

This separation is valuable even when A and B reuse the same application structure at different times. The structure’s storage location is not the work identity. Do not let a later edit to a “current frame” record silently relabel an older queued request in diagnostic logs.

Use the request fields on the correct queue

For this memory-to-memory case, the QBUF contract accepts request_fd for OUTPUT buffers, with V4L2_BUF_FLAG_REQUEST_FD set. An absent flag means the field is ignored. Associating a CAPTURE buffer with a request in this case is rejected with EBADR.

CAPTURE buffers still need their ordinary queue management. The restriction is specific to the memory-to-memory case here; the documentation separately describes simple capture devices using requests for CAPTURE buffers. Do not turn the codec rule into a universal ban for all V4L2 devices.

Keep request-based and direct submission from being mixed on the same applicable buffer queue. They are distinct queueing modes, and attempts to mix them can produce EBUSY. Likewise, avoid setting the same control both directly and through requests; the guide warns that this combination can have undefined behavior.

Separate staged, queued and completed states

A proposed owner trace is:

Request A: allocate -> stage CA and OUTPUT A -> queue -> in flight
Request B: allocate -> stage CB and OUTPUT B -> queue -> in flight
Request A: observe request completion -> inspect results -> reinitialize
Request A: stage a new complete description before another queue

Queueing is the commit boundary for the staged description. After successful submission, do not modify A’s controls or treat A as a spare request for another frame. Keep failure handling tied to the last operation that actually succeeded; a failed preparation or queue call must not advance the software state to in flight.

Original request-lifecycle model. Request completion and individual buffer availability are distinct observations.

Wait for the request, not an assumed frame count

The guide defines request completion in terms of all associated buffers becoming available for dequeue and completion-time controls being updated. Some buffers can become available before the request completes. The request poll interface reports completion with POLLPRI in revents. A timeout or an error is not completion; polling an unqueued request reports POLLERR. Check the return value and event bits before advancing ownership.

A dequeued CAPTURE buffer alone is not a general proof that the request can be recycled. The codec example also explicitly avoids guaranteeing one CAPTURE buffer for each OUTPUT buffer. Maintain the selected codec’s supported association rules rather than deriving request ownership from a guessed one-to-one output count.

After completion, read any required request-specific control results before clearing the request. Reinitialization discards its stored state. The next generation must be populated deliberately; it must not inherit an imagined residual control set from the previous use. The reinitialization contract returns EBUSY for a queued request that has not completed. Treat that as a rejected state transition, not an invitation to discard its application record.

Closing a handle is not cancellation

Closing a queued request’s descriptor makes that descriptor unavailable to userspace, but the kernel can retain the request until the driver finishes using it. Do not acknowledge “frame cancelled” merely because the local descriptor was closed. A cancellation requirement needs a separately checked stream and driver lifecycle.

Similarly, request association does not promise perfect atomic reconfiguration across every hardware entity. The documentation qualifies pipeline synchronization by hardware capability. Keep the product’s actual driver and media topology in the validation record.

Review the ownership transitions before throughput

A proposed software test should reject editing an in-flight request, reject recycling on an early buffer event, and require a newly populated description after reinitialization. Include B completing while A’s application record remains pending, so a reused index cannot misattribute the result.

Then qualify request support, supported controls, queue behavior and completion evidence on an approved target. Preserve failures and returned error codes rather than counting every attempted submission as accepted. The acceptance artifact is an A/B lifecycle trace whose controls, buffers and request generations remain associated throughout preparation, processing and reuse.