drm_atomic_uapi.c

This flag tells core to jump ahead the queued update if the conditions
in drm_atomic_amend_check() are met. That means we are only able to do an
amend update if no modeset is pending and update for the same plane is
not queued.

It uses the already in place infrastructure for amend updates.

It is useful for cursor updates over the atomic ioctl.
Otherwise in some cases updates may be delayed to the point the
user will notice it.
Note that for now it's only enabled for cursor planes.

DRM_MODE_ATOMIC_AMEND should be passed to the Atomic IOCTL to use this
feature.

Signed-off-by: Gustavo Padovan <gustavo.padovan@collabora.com>
Signed-off-by: Enric Balletbo i Serra <enric.balletbo@collabora.com>
[updated for upstream]
Signed-off-by: Helen Koike <helen.koike@collabora.com>
Series-to: David Airlie <airlied@linux.ie>
Series-cc: dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org, kernel@collabora.com, Gustavo Padovan <gustavo.padovan@collabora.com>, Stéphane Marchesin <marcheu@google.com>, tomasz Figa <tfiga@chromium.org>, Sean Paul <seanpaul@google.com>, alexandros.frantzis@collabora.com, dnicoara@chromium.org, daniels@collabora.com

Series-version: 3

Series-changes: 3
- rebase tree
- rebase on top of renaming async_update to amend_update
- improve documentation
- don't fall back to a normal commit if amend is not possible when
requested through the atomic api

Series-changes: 2
- rebase tree
- do not fall back to a non-async update if if there isn't any
pending commit to amend

Series-changes: 1
- https://patchwork.freedesktop.org/patch/243088/
- Only enable it if userspace requests it.
- Only allow async update for cursor type planes.
- Rename ASYNC_UPDATE for ATOMIC_AMEND.

Cover-letter:
async vs amend - UAPI

Hi,

This patch series is an attempt to clarify some concepts and how things
are hooked inside drm.

There are two main concepts that are similar but different and are
causing some confusion:

    - Asynchronous update: is the ability change the hw state at any time, not
    only during vblank.

    - Amend update: is the ability to perform 1000 commits to be applied as soon
    as possible without waiting for 1000 vblanks.

async updates can be seen as amend, but the opposite is not true.
Please see documentation on the commit
	"drm/atomic: rename async_{update,check} to amend_{update,check}"
for a more detailed explanation.

To perform an async update, we already have the DRM_MODE_PAGE_FLIP_ASYNC
flag in the atomic API and it is already being used by amdgpu in the
atomic path.

The first two commits clarifies these differences. The last two are
RFCs that exposes new async and amend features to userspace.

We introduce in this series the flag DRM_MODE_ATOMIC_AMEND to expose
the amend feature to userspace.
The main reasons to expose this through atomic api is to avoid mixing legacy
with modern/atomic API (since their interactions are not well defined)
and to be able to explicitly manage the cursor plane.

And the last commit hooks the current async implementations with the
DRM_MODE_PAGE_FLIP_ASYNC flag.

Please, see the message in each commit and the documentation that was
added for more details and let me know what you think.

Thanks
Helen
END

Commit-notes:
Hi,

This is the third attempt to introduce the new ATOMIC_AMEND flag for atomic
operations, see the commit message for a more detailed description.
I am sending this patch in the series as an RFC as I still have things
to define/discuss.

The main reasons to expose this through atomic api is to avoid mixing legacy
with modern/atomic API (since their interactions are not well defined)
and to be able to explicitly manage the cursor plane.

The way I envision it working is:

1) userspace just use DRM_MODE_PAGE_FLIP_ASYNC if true async is desired.
2) if it fails, then userspace can try DRM_MODE_ATOMIC_AMEND if true async is
not required, but a legacy cursor behavior is required
3) if amend is not possible, we can or:
	A) fallback to a non amend update
	B) fail
	C) add another flag to define what it should do.

Right now the code does A for legacy cursor and B for atomic api using
the DRM_MODE_ATOMIC_AMEND flag.
Discussing with some people it seems that failing is better for Xorg,
but Ozone (chrome compositor) doesn't expect the amend to fail, but I
think it could just retry the same atomic commit without the AMEND flag
if it wants to fallback.

Alexandros also did a proof-of-concept to use this flag and draw cursors
using atomic if possible on ozone (Chrome compositor) [1].

I'm sending this as an RFC for now as I still need to verify the
requirements from other compositors and make some tests (and also to
justify the s/async/amend renaming).

Please, let me know if you detect issues with this.
If not, I'll start implementing tests in igt and push the adoption in
other compositors.

Thanks
Helen

[1] https://chromium-review.googlesource.com/c/chromium/src/+/1092711
[2] https://gitlab.collabora.com/eballetbo/drm-cursor/commits/async-capability

END