From: Pekka Paalanen <ppaalanen@gmail.com>
To: Albert Esteve <aesteve@redhat.com>
Cc: linux-doc@vger.kernel.org, qemu-devel@nongnu.org,
banackm@vmware.com, virtualization@lists.linux-foundation.org,
Gerd Hoffmann <kraxel@redhat.com>,
mombasawalam@vmware.com, iforbes@vmware.com,
Jonathan Corbet <corbet@lwn.net>,
javierm@redhat.com,
VMware Graphics Reviewers <linux-graphics-maintainer@vmware.com>,
David Airlie <airlied@redhat.com>,
Maxime Ripard <mripard@kernel.org>,
Hans de Goede <hdegoede@redhat.com>,
dri-devel@lists.freedesktop.org,
spice-devel@lists.freedesktop.org,
Gurchetan Singh <gurchetansingh@chromium.org>,
Matt Roper <matthew.d.roper@intel.com>,
linux-kernel@vger.kernel.org, krastevm@vmware.com,
Thomas Zimmermann <tzimmermann@suse.de>
Subject: Re: [PATCH v6 9/9] drm: Introduce documentation for hotspot properties
Date: Mon, 23 Oct 2023 11:23:00 +0300 [thread overview]
Message-ID: <20231023112300.732e18fa@eldfell> (raw)
In-Reply-To: <20231023074613.41327-10-aesteve@redhat.com>
[-- Attachment #1: Type: text/plain, Size: 5598 bytes --]
On Mon, 23 Oct 2023 09:46:13 +0200
Albert Esteve <aesteve@redhat.com> wrote:
> From: Michael Banack <banackm@vmware.com>
>
> To clarify the intent and reasoning behind the hotspot properties
> introduce userspace documentation that goes over cursor handling
> in para-virtualized environments.
>
> The documentation is generic enough to not special case for any
> specific hypervisor and should apply equally to all.
>
> Signed-off-by: Zack Rusin <zackr@vmware.com>
Hi,
the below doc text:
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Thanks,
pq
> ---
> Documentation/gpu/drm-kms.rst | 6 ++++
> drivers/gpu/drm/drm_plane.c | 58 ++++++++++++++++++++++++++++++++++-
> 2 files changed, 63 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index a0c83fc481264..158cdcc9351f9 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -577,6 +577,12 @@ Variable Refresh Properties
> .. kernel-doc:: drivers/gpu/drm/drm_connector.c
> :doc: Variable refresh properties
>
> +Cursor Hotspot Properties
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_plane.c
> + :doc: hotspot properties
> +
> Existing KMS Properties
> -----------------------
>
> diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c
> index 1dc00ad4c33c3..f3f2eae83cca8 100644
> --- a/drivers/gpu/drm/drm_plane.c
> +++ b/drivers/gpu/drm/drm_plane.c
> @@ -230,6 +230,61 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
> return 0;
> }
>
> +/**
> + * DOC: hotspot properties
> + *
> + * HOTSPOT_X: property to set mouse hotspot x offset.
> + * HOTSPOT_Y: property to set mouse hotspot y offset.
> + *
> + * When the plane is being used as a cursor image to display a mouse pointer,
> + * the "hotspot" is the offset within the cursor image where mouse events
> + * are expected to go.
> + *
> + * Positive values move the hotspot from the top-left corner of the cursor
> + * plane towards the right and bottom.
> + *
> + * Most display drivers do not need this information because the
> + * hotspot is not actually connected to anything visible on screen.
> + * However, this is necessary for display drivers like the para-virtualized
> + * drivers (eg qxl, vbox, virtio, vmwgfx), that are attached to a user console
> + * with a mouse pointer. Since these consoles are often being remoted over a
> + * network, they would otherwise have to wait to display the pointer movement to
> + * the user until a full network round-trip has occurred. New mouse events have
> + * to be sent from the user's console, over the network to the virtual input
> + * devices, forwarded to the desktop for processing, and then the cursor plane's
> + * position can be updated and sent back to the user's console over the network.
> + * Instead, with the hotspot information, the console can anticipate the new
> + * location, and draw the mouse cursor there before the confirmation comes in.
> + * To do that correctly, the user's console must be able predict how the
> + * desktop will process mouse events, which normally requires the desktop's
> + * mouse topology information, ie where each CRTC sits in the mouse coordinate
> + * space. This is typically sent to the para-virtualized drivers using some
> + * driver-specific method, and the driver then forwards it to the console by
> + * way of the virtual display device or hypervisor.
> + *
> + * The assumption is generally made that there is only one cursor plane being
> + * used this way at a time, and that the desktop is feeding all mouse devices
> + * into the same global pointer. Para-virtualized drivers that require this
> + * should only be exposing a single cursor plane, or find some other way
> + * to coordinate with a userspace desktop that supports multiple pointers.
> + * If the hotspot properties are set, the cursor plane is therefore assumed to be
> + * used only for displaying a mouse cursor image, and the position of the combined
> + * cursor plane + offset can therefore be used for coordinating with input from a
> + * mouse device.
> + *
> + * The cursor will then be drawn either at the location of the plane in the CRTC
> + * console, or as a free-floating cursor plane on the user's console
> + * corresponding to their desktop mouse position.
> + *
> + * DRM clients which would like to work correctly on drivers which expose
> + * hotspot properties should advertise DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT.
> + * Setting this property on drivers which do not special case
> + * cursor planes will return EOPNOTSUPP, which can be used by userspace to
> + * gauge requirements of the hardware/drivers they're running on. Advertising
> + * DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT implies that the userspace client will be
> + * correctly setting the hotspot properties.
> + */
> +
> /**
> * drm_plane_create_hotspot_properties - creates the mouse hotspot
> * properties and attaches them to the given cursor plane
> @@ -237,7 +292,8 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
> * @plane: drm cursor plane
> *
> * This function enables the mouse hotspot property on a given
> - * cursor plane.
> + * cursor plane. Look at the documentation for hotspot properties
> + * to get a better understanding for what they're used for.
> *
> * RETURNS:
> * Zero for success or -errno
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2023-10-23 8:23 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-23 7:46 [PATCH v6 0/9] Fix cursor planes with virtualized drivers Albert Esteve
2023-10-23 7:46 ` [PATCH v6 1/9] drm: Disable the cursor plane on atomic contexts " Albert Esteve
2023-10-23 7:53 ` Simon Ser
2023-10-23 7:46 ` [PATCH v6 2/9] drm/atomic: Add support for mouse hotspots Albert Esteve
2023-10-23 7:46 ` [PATCH v6 3/9] drm/vmwgfx: Use the hotspot properties from cursor planes Albert Esteve
2023-10-23 7:46 ` [PATCH v6 4/9] drm/qxl: " Albert Esteve
2023-10-23 7:46 ` [PATCH v6 5/9] drm/vboxvideo: " Albert Esteve
2023-10-23 7:46 ` [PATCH v6 6/9] drm/virtio: " Albert Esteve
2023-10-23 7:46 ` [PATCH v6 7/9] drm: Remove legacy cursor hotspot code Albert Esteve
2023-10-23 7:46 ` [PATCH v6 8/9] drm: Introduce DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT Albert Esteve
2023-10-23 7:46 ` [PATCH v6 9/9] drm: Introduce documentation for hotspot properties Albert Esteve
2023-10-23 8:23 ` Pekka Paalanen [this message]
2023-10-23 21:29 ` Javier Martinez Canillas
2023-10-24 19:34 ` Michael Banack
2023-10-25 6:36 ` Javier Martinez Canillas
2023-10-23 7:55 ` [PATCH v6 0/9] Fix cursor planes with virtualized drivers Simon Ser
2023-10-23 8:14 ` Albert Esteve
2023-10-23 8:19 ` Simon Ser
2023-11-22 12:49 ` Javier Martinez Canillas
2023-11-23 22:11 ` Simon Ser
2023-11-24 10:56 ` Javier Martinez Canillas
2023-11-24 14:41 ` Javier Martinez Canillas
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=20231023112300.732e18fa@eldfell \
--to=ppaalanen@gmail.com \
--cc=aesteve@redhat.com \
--cc=airlied@redhat.com \
--cc=banackm@vmware.com \
--cc=corbet@lwn.net \
--cc=dri-devel@lists.freedesktop.org \
--cc=gurchetansingh@chromium.org \
--cc=hdegoede@redhat.com \
--cc=iforbes@vmware.com \
--cc=javierm@redhat.com \
--cc=krastevm@vmware.com \
--cc=kraxel@redhat.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-graphics-maintainer@vmware.com \
--cc=linux-kernel@vger.kernel.org \
--cc=matthew.d.roper@intel.com \
--cc=mombasawalam@vmware.com \
--cc=mripard@kernel.org \
--cc=qemu-devel@nongnu.org \
--cc=spice-devel@lists.freedesktop.org \
--cc=tzimmermann@suse.de \
--cc=virtualization@lists.linux-foundation.org \
/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;
as well as URLs for NNTP newsgroup(s).