mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: "André Almeida" <andrealmeid@igalia.com>
To: dri-devel@lists.freedesktop.org, amd-gfx@lists.freedesktop.org,
	linux-kernel@vger.kernel.org
Cc: 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>,
	"Pekka Paalanen" <ppaalanen@gmail.com>,
	daniel@ffwll.ch, "Daniel Stone" <daniel@fooishbar.org>,
	"'Marek Olšák'" <maraeo@gmail.com>,
	"Dave Airlie" <airlied@gmail.com>,
	"Michel Dänzer" <michel.daenzer@mailbox.org>,
	"Randy Dunlap" <rdunlap@infradead.org>,
	ville.syrjala@linux.intel.com, intel-gfx@lists.freedesktop.org,
	"Pekka Paalanen" <pekka.paalanen@collabora.com>,
	"André Almeida" <andrealmeid@igalia.com>
Subject: [PATCH v9 4/4] drm/doc: Define KMS atomic state set
Date: Wed, 22 Nov 2023 13:19:41 -0300	[thread overview]
Message-ID: <20231122161941.320564-5-andrealmeid@igalia.com> (raw)
In-Reply-To: <20231122161941.320564-1-andrealmeid@igalia.com>

From: Pekka Paalanen <pekka.paalanen@collabora.com>

Specify how the atomic state is maintained between userspace and
kernel, plus the special case for async flips.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Signed-off-by: André Almeida <andrealmeid@igalia.com>
---
v9:
- no changes
v8:
- no changes
v7:
- add a note that drivers can make exceptions for ad-hoc prop changes
- add a note about flipping the same FB_ID as a no-op
---
---
 Documentation/gpu/drm-uapi.rst | 47 ++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 370d820be248..d0693f902a5c 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -570,3 +570,50 @@ dma-buf interoperability
 
 Please see Documentation/userspace-api/dma-buf-alloc-exchange.rst for
 information on how dma-buf is integrated and exposed within DRM.
+
+KMS atomic state
+================
+
+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 is 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 unexpectedly
+fail, cause visible glitches, or delay reaching the final state.
+
+An atomic commit can be flagged with DRM_MODE_ATOMIC_TEST_ONLY, which means the
+complete state change is validated but not applied.  Userspace should use this
+flag to validate any state change before asking to apply it. If validation fails
+for any reason, userspace should attempt to fall back to another, perhaps
+simpler, final state.  This allows userspace to probe for various configurations
+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 state in
+the kernel. Hence, the complete new KMS state is the complete old KMS state with
+the committed property settings done on top. The kernel will try to avoid
+no-operation changes, so it is safe for userspace to send redundant property
+settings.  However, not every situation allows for no-op changes, due to the
+need to acquire locks for some attributes. Userspace needs to be aware that some
+redundant information might result in oversynchronization issues.  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. As a special exception for VRR needs, explicitly setting
+FB_ID to its current value is not a no-op.
+
+A "modeset" is a change in KMS state that might enable, disable, or temporarily
+disrupt the emitted video signal, possibly causing visible glitches on screen. A
+modeset may also take considerably more time to complete than other kinds of
+changes, and the video sink might also need time to adapt to the new signal
+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 change 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 changes
+are ignored as always. Changing any other property will cause the commit to be
+rejected. Each driver may relax this restriction if they have guarantees that
+such property change doesn't cause modesets. Userspace can use TEST_ONLY commits
+to query the driver about this.
-- 
2.42.1


  parent reply	other threads:[~2023-11-22 16:21 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-11-22 16:19 [PATCH v9 0/4] drm: Add support for atomic async page-flip André Almeida
2023-11-22 16:19 ` [PATCH v9 1/4] drm: Refuse to async flip with atomic prop changes André Almeida
2023-11-22 16:19 ` [PATCH v9 2/4] drm: allow DRM_MODE_PAGE_FLIP_ASYNC for atomic commits André Almeida
2023-11-22 16:19 ` [PATCH v9 3/4] drm: introduce DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP André Almeida
2023-11-22 16:19 ` André Almeida [this message]
2023-11-22 20:23 ` [PATCH v9 0/4] drm: Add support for atomic async page-flip Hamza Mahfooz
2023-11-22 20:28   ` André Almeida
2023-11-23 16:24     ` Simon Ser
2023-11-23 16:26       ` André Almeida

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20231122161941.320564-5-andrealmeid@igalia.com \
    --to=andrealmeid@igalia.com \
    --cc=airlied@gmail.com \
    --cc=alexander.deucher@amd.com \
    --cc=amd-gfx@lists.freedesktop.org \
    --cc=christian.koenig@amd.com \
    --cc=contact@emersion.fr \
    --cc=daniel@ffwll.ch \
    --cc=daniel@fooishbar.org \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=intel-gfx@lists.freedesktop.org \
    --cc=kernel-dev@igalia.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=maraeo@gmail.com \
    --cc=michel.daenzer@mailbox.org \
    --cc=pekka.paalanen@collabora.com \
    --cc=pierre-eric.pelloux-prayer@amd.com \
    --cc=ppaalanen@gmail.com \
    --cc=rdunlap@infradead.org \
    --cc=robdclark@gmail.com \
    --cc=ville.syrjala@linux.intel.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®