[PATCH] drm/atomic: clarify the rules around drm_atomic_state->allow_modeset

[Pekka Paalanen]

On Wed, 11 Oct 2023 11:20:51 +0200
Daniel Vetter <daniel.vetter at ffwll.ch> wrote:

> msm is automagically upgrading normal commits to full modesets, and
> that's a big no-no:
> 
> - for one this results in full on->off->on transitions on all these
>   crtc, at least if you're using the usual helpers. Which seems to be
>   the case, and is breaking uapi
> 
> - further even if the ctm change itself would not result in flicker,
>   this can hide modesets for other reasons. Which again breaks the
>   uapi
> 
> v2: I forgot the case of adding unrelated crtc state. Add that case
> and link to the existing kerneldoc explainers. This has come up in an
> irc discussion with Manasi and Ville about intel's bigjoiner mode.
> Also cc everyone involved in the msm irc discussion, more people
> joined after I sent out v1.
> 
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> Cc: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
> Cc: Maxime Ripard <mripard at kernel.org>
> Cc: Thomas Zimmermann <tzimmermann at suse.de>
> Cc: David Airlie <airlied at gmail.com>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Pekka Paalanen <pekka.paalanen at collabora.com>
> Cc: Rob Clark <robdclark at gmail.com>
> Cc: Simon Ser <contact at emersion.fr>
> Cc: Manasi Navare <navaremanasi at google.com>
> Cc: Ville Syrjälä <ville.syrjala at linux.intel.com>
> Cc: Abhinav Kumar <quic_abhinavk at quicinc.com>
> Cc: Dmitry Baryshkov <dmitry.baryshkov at linaro.org>
> Signed-off-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> ---
>  include/drm/drm_atomic.h | 23 +++++++++++++++++++++--
>  1 file changed, 21 insertions(+), 2 deletions(-)
> 
> diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h
> index cf8e1220a4ac..545c48545402 100644
> --- a/include/drm/drm_atomic.h
> +++ b/include/drm/drm_atomic.h
> @@ -372,8 +372,27 @@ struct drm_atomic_state {
>  	 *
>  	 * Allow full modeset. This is used by the ATOMIC IOCTL handler to
>  	 * implement the DRM_MODE_ATOMIC_ALLOW_MODESET flag. Drivers should
> -	 * never consult this flag, instead looking at the output of
> -	 * drm_atomic_crtc_needs_modeset().
> +	 * not consult this flag, instead looking at the output of
> +	 * drm_atomic_crtc_needs_modeset(). The detailed rules are:
> +	 *
> +	 * - Drivers must not consult @allow_modeset in the atomic commit path,
> +	 *   and instead use drm_atomic_crtc_needs_modeset().

Change to

	Drivers must not consult @allow_modeset in the atomic commit path.
	Use drm_atomic_crtc_needs_modeset() instead.

maybe?

It's hard for me to see the difference between "instead use X" and
"instead of X". "Use Y instead (of X)." helps me at least.

> +	 *
> +	 * - Drivers may consult @allow_modeset in the atomic check path, if
> +	 *   they have the choice between an optimal hardware configuration
> +	 *   which requires a modeset, and a less optimal configuration which
> +	 *   can be committed without a modeset. An example would be suboptimal
> +	 *   scanout FIFO allocation resulting in increased idle power
> +	 *   consumption. This allows userspace to avoid flickering and delays
> +	 *   for the normal composition loop at reasonable cost.
> +	 *
> +	 * - Drivers must consult @allow_modeset before adding unrelated struct
> +	 *   drm_crtc_state to this commit by calling
> +	 *   drm_atomic_get_crtc_state(). See also the warning in the
> +	 *   documentation for that function.
> +	 *
> +	 * - Drivers must never change this flag, it is only under the control
> +	 *   of userspace.

*only userspace may set it. ?

>  	 */
>  	bool allow_modeset : 1;
>  	/**

Wording bikeshed aside,

Acked-by: Pekka Paalanen <pekka.paalanen at collabora.com>


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20231011/3e436b77/attachment.sig>