Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Mon, 10 Jul 2023 11:30:54 +0300
From:   Pekka Paalanen <ppaalanen@gmail.com>
To:     =?UTF-8?B?QW5kcsOp?= Almeida <andrealmeid@igalia.com>
Cc:     dri-devel@lists.freedesktop.org, amd-gfx@lists.freedesktop.org,
        linux-kernel@vger.kernel.org, wayland-devel@lists.freedesktop.org,
        kernel-dev@igalia.com, alexander.deucher@amd.com,
        christian.koenig@amd.com, pierre-eric.pelloux-prayer@amd.com,
        Simon Ser <contact@emersion.fr>,
        Rob Clark <robdclark@gmail.com>,
        Daniel Vetter <daniel@ffwll.ch>,
        Daniel Stone <daniel@fooishbar.org>,
        'Marek =?UTF-8?B?T2zFocOhayc=?= <maraeo@gmail.com>,
        Dave Airlie <airlied@gmail.com>,
        Michel =?UTF-8?B?RMOkbnplcg==?= <michel.daenzer@mailbox.org>,
        Randy Dunlap <rdunlap@infradead.org>, hwentlan@amd.com,
        joshua@froggi.es, ville.syrjala@linux.intel.com
Subject: Re: [PATCH v5 6/6] drm/doc: Define KMS atomic state set
Message-ID: <20230710113054.316a9f31@eldfell>
In-Reply-To: <20230707224059.305474-7-andrealmeid@igalia.com>
References: <20230707224059.305474-1-andrealmeid@igalia.com>
        <20230707224059.305474-7-andrealmeid@igalia.com>
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="Sig_/_cBaQ_yD9IwDg/Rsy2Dl+2I";
 protocol="application/pgp-signature"; micalg=pgp-sha256
Precedence: bulk

--Sig_/_cBaQ_yD9IwDg/Rsy2Dl+2I
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

On Fri,  7 Jul 2023 19:40:59 -0300
Andr=C3=A9 Almeida <andrealmeid@igalia.com> wrote:

> From: Pekka Paalanen <pekka.paalanen@collabora.com>
>=20
> Specify how the atomic state is maintained between userspace and
> kernel, plus the special case for async flips.
>=20
> Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
> Signed-off-by: Andr=C3=A9 Almeida <andrealmeid@igalia.com>
> ---
> v4: total rework by Pekka
> ---
>  Documentation/gpu/drm-uapi.rst | 41 ++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)

Thank you for polishing that email into a proper patch!

For patches 1 and 2:
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>


Thanks,
pq

> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.=
rst
> index 65fb3036a580..6a1662c08901 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -486,3 +486,44 @@ and the CRTC index is its position in this array.
> =20
>  .. kernel-doc:: include/uapi/drm/drm_mode.h
>     :internal:
> +
> +KMS atomic state
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +An atomic commit can change multiple KMS properties in an atomic fashion,
> +without ever applying intermediate or partial state changes.  Either the=
 whole
> +commit succeeds or fails, and it will never be applied partially. This i=
s the
> +fundamental improvement of the atomic API over the older non-atomic API =
which is
> +referred to as the "legacy API".  Applying intermediate state could unex=
pectedly
> +fail, cause visible glitches, or delay reaching the final state.
> +
> +An atomic commit can be flagged with DRM_MODE_ATOMIC_TEST_ONLY, which me=
ans the
> +complete state change is validated but not applied.  Userspace should us=
e this
> +flag to validate any state change before asking to apply it. If validati=
on fails
> +for any reason, userspace should attempt to fall back to another, perhaps
> +simpler, final state.  This allows userspace to probe for various config=
urations
> +without causing visible glitches on screen and without the need to undo a
> +probing change.
> +
> +The changes recorded in an atomic commit apply on top the current KMS st=
ate in
> +the kernel. Hence, the complete new KMS state is the complete old KMS st=
ate with
> +the committed property settings done on top. The kernel will automatical=
ly avoid
> +no-operation changes, so it is safe and even expected for userspace to s=
end
> +redundant property settings.  No-operation changes do not count towards =
actually
> +needed changes, e.g.  setting MODE_ID to a different blob with identical
> +contents as the current KMS state shall not be a modeset on its own.
> +
> +A "modeset" is a change in KMS state that might enable, disable, or temp=
orarily
> +disrupt the emitted video signal, possibly causing visible glitches on s=
creen. A
> +modeset may also take considerably more time to complete than other kind=
s of
> +changes, and the video sink might also need time to adapt to the new sig=
nal
> +properties. Therefore a modeset must be explicitly allowed with the flag
> +DRM_MODE_ATOMIC_ALLOW_MODESET.  This in combination with
> +DRM_MODE_ATOMIC_TEST_ONLY allows userspace to determine if a state chang=
e is
> +likely to cause visible disruption on screen and avoid such changes when=
 end
> +users do not expect them.
> +
> +An atomic commit with the flag DRM_MODE_PAGE_FLIP_ASYNC is allowed to
> +effectively change only the FB_ID property on any planes. No-operation c=
hanges
> +are ignored as always. Changing any other property will cause the commit=
 to be
> +rejected.


--Sig_/_cBaQ_yD9IwDg/Rsy2Dl+2I
Content-Type: application/pgp-signature
Content-Description: OpenPGP digital signature

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEJQjwWQChkWOYOIONI1/ltBGqqqcFAmSrwb4ACgkQI1/ltBGq
qqcBAg//RoZa8NlDML/orFXTdrRJYvLDZ4R3Cek3ssDoj7yBDQy6HnXaLJwHwkf9
WhkN28UTOu00/CsmgAVT2P3Cuz5ebS7zJsLkBqS7OzLqWx+8+WodZW8BswZvRilo
EhrDGDDd+/8LFd57y2XFyuIMiwfDkK3ME17zl0s0fiGXtOixe4O3Q/vHajdBTp84
JpLJ+fxnD2T4/R7mva7YxPPNbSxX/rTwkmcedf16MEfk6KX3LIVrGWQ+6jIyXMKQ
ztC+R9R9SQ17WKMVck70nq82NwfF+VaFf78szBGnBkVTIn7jTRoyCPLn5mtLxzxT
AS9/5y4JUbtb8d7Q/pG6eOdr25oUhJjSqhGBz83qicAn2U+dcwi9QzehyD9Kqd9S
9NUjc8WN8mZSzt+8Pef528m3Ts7JrF57HJ4BTehuFhqXl/taJSJVGF8uBj4ZHiMk
JUT4d/VUfsUnfWv59S8I9AyupcpvEFQnMW7r/RGJL3M9vNV3YVo4SEAlllmtTnA0
l9Gi9o78iAc8vCdu5s+BWLyOe0rGkER1yAHJq+5LYWRpB+FWVIjcwS24JoBs9P15
6Ba2dhHeN2/mljk/QD8HQrGrvWJPj+x9jY/YyZYETnwRQaFZnCtZeldoFh2WIvZb
4YVxdUuDvOSuzYwIXWWaV+t17+iWBkk6yTyWzC1hO4vDosoMtQw=
=LMkp
-----END PGP SIGNATURE-----

--Sig_/_cBaQ_yD9IwDg/Rsy2Dl+2I--