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

[Nicolas Dufresne]

Hi Ming,

Le lundi 08 juin 2026 à 06:26 +0000, Ming Qian (OSS) a écrit :
> 
> 
> > -----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).

Be aware that Sashiko is an AI bot, llm words things with extreme conviction,
and it this case forget about backward compatibility from pre-spec.

> 
> 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-resolu
> tion-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?

The coda source_change notification is completely fake. It does not dependent on
the bitstream content. So the event is left there, since its kind of part of the
ABI, but it does not behave like other implementation, or pre-spec drivers.

So what we do in GStreamer, is that for legacy driver (no
V4L2_FMT_FLAG_DYN_RESOLUTION), we pre-allocate both queues, based on our guessed
dimensions. If it happens that the conformance windows is small enough, it often
works. DRC will only work if the display dimension changes.

For any modern driver, that implement V4L2_FMT_FLAG_DYN_RESOLUTION, we strictly
wait for the event, and on DRC, even if the display resolution changes, we let
the driver tell us when to actually reconfigure. The legacy method was kept to
not break coda and older driver, the new method is a lot more reliable, and
avoid allocating twice the capture queue (wrong guess).

The userspace implementation is also a bit more flexible, as normally the legacy
way should kind of work for any drivers, and we still subscribe it seems. But
the implication is just strange and shouldn't be needed in drivers with
V4L2_FMT_FLAG_DYN_RESOLUTION support.

Nicolas



> 
> [1] https://gitlab.freedesktop.org/gstreamer/gstreamer/-/work_items/5126
> 
> Best regards,
> Ming

Attachment: signature.asc
Description: This is a digitally signed message part