RE: [PATCH RFC 1/2] media: docs: Clarify V4L2_FMT_FLAG_DYN_RESOLUTION usage

[Ming Qian (OSS)]

>-----Original Message-----
>From: sashiko-bot@xxxxxxxxxx <sashiko-bot@xxxxxxxxxx>
>Sent: Monday, June 8, 2026 12:06 PM
>To: Ming Qian (OSS) <ming.qian@xxxxxxxxxxx>
>Cc: imx@xxxxxxxxxxxxxxx; Frank.Li@xxxxxxxxxx; linux-media@xxxxxxxxxxxxxxx
>Subject: Re: [PATCH RFC 1/2] media: docs: Clarify
>V4L2_FMT_FLAG_DYN_RESOLUTION usage
>
>Thank you for your contribution! Sashiko AI review found 1 potential issue(s)
>to consider:
>- [High] The added documentation conflates
>`V4L2_FMT_FLAG_DYN_RESOLUTION` (which designates mid-stream dynamic
>resolution switching capability) with the mandatory initial
>`V4L2_EVENT_SOURCE_CHANGE` event. By stating "Clients can use this flag to
>determine whether the decoder will signal the initial resolution", it explicitly
>legitimizes a flawed userspace heuristic that violates the V4L2 stateful decoder
>specification. The specification mandates that for coded formats containing
>resolution info, the decoder MUST parse the stream and emit an initial
>`V4L2_EVENT_SOURCE_CHANGE` event (Initialization Step 4). Compliant drivers
>(e.g., `coda`) correctly emit this initial event but do NOT set
>`V4L2_FMT_FLAG_DYN_RESOLUTION` because they lack mid-stream switching
>capabilities. If userspace follows this documented advice, it will erroneously
>skip waiting for the initial event on these drivers, breaking Capture Setup and
>stream decoding.
>--
>
>commit ec9c0583334c246f7813132b55724e42622e8edd
>Author: Ming Qian <ming.qian@xxxxxxxxxxx>
>
>media: docs: Clarify V4L2_FMT_FLAG_DYN_RESOLUTION usage
>
>This commit updates the V4L2 stateful decoder documentation to clarify the
>usage of the V4L2_FMT_FLAG_DYN_RESOLUTION flag. It adds a note stating
>that decoders setting this flag will always emit an initial source change event.
>The documentation suggests clients can use this flag to decide whether to wait
>for the initial resolution signal.
>
>> diff --git a/Documentation/userspace-api/media/v4l/dev-decoder.rst
>> b/Documentation/userspace-api/media/v4l/dev-decoder.rst
>> --- a/Documentation/userspace-api/media/v4l/dev-decoder.rst
>> +++ b/Documentation/userspace-api/media/v4l/dev-decoder.rst
>> @@ -361,6 +361,14 @@ Initialization
>[ ... ]
>> +    .. note::
>> +
>> +       Decoders that set the ``V4L2_FMT_FLAG_DYN_RESOLUTION`` flag for
>the
>> +       coded format will always emit an initial
>``V4L2_EVENT_SOURCE_CHANGE``
>> +       event with ``V4L2_EVENT_SRC_CH_RESOLUTION`` during this phase.
>Clients
>> +       can use this flag to determine whether the decoder will signal the
>> +       initial resolution before producing decoded frames.
>
>[Severity: High]
>Does this guidance conflate the V4L2_FMT_FLAG_DYN_RESOLUTION flag,
>which designates mid-stream dynamic resolution switching, with the
>mandatory initial V4L2_EVENT_SOURCE_CHANGE event?
>
>The V4L2 Stateful Decoder API requires an initial
>V4L2_EVENT_SOURCE_CHANGE event during the Initialization phase for stream
>parsing, irrespective of dynamic resolution support.
>
>Compliant drivers like coda correctly emit this initial event but do not set
>V4L2_FMT_FLAG_DYN_RESOLUTION because they lack mid-stream switching
>capabilities.
>
>If userspace follows this documented advice, wouldn't it erroneously skip
>waiting for the initial event on these drivers, potentially breaking capture setup
>and stream decoding?
>
>--
>Sashiko AI review · https://sashiko.dev/#/patchset/20260608-flag-dyn-
>resolution-v1-0-44dc65516148@xxxxxxxxxxx?part=1

Hi,

Thanks for the review.

You are right that the V4L2 stateful decoder specification states the initial V4L2_EVENT_SOURCE_CHANGE is mandatory for coded formats that contain resolution information in the stream (Initialization Step 4).

However, in practice, GStreamer's v4l2 stateful decoder implementation uses V4L2_FMT_FLAG_DYN_RESOLUTION to determine whether to subscribe and wait for the initial source change event. The reasoning from the GStreamer side, as Nicolas explained [1]:

  
"https://docs.kernel.org/userspace-api/media/v4l/dev-decoder.html#dynamic-resolution-change
    Says:
        Not all decoders can detect resolution changes. Those that do set the
        V4L2_FMT_FLAG_DYN_RESOLUTION flag.

    So normally that wording should prevent requiring an initial SRC_CH,
    or emitting later SRC_CH. Your driver don't have this flag, then your
    driver can't emit this event. But a measure we should take into
    GStreamer would be to not register (or mark) this event."

@Nicolas, could you elaborate on why GStreamer needs V4L2_FMT_FLAG_DYN_RESOLUTION to handle the initial source change event?
Is this something that should be fixed on the GStreamer side (i.e., always wait for the initial event), or is the current heuristic intentional due to legacy drivers that don't emit the event?

[1] https://gitlab.freedesktop.org/gstreamer/gstreamer/-/work_items/5126

Best regards,
Ming