From dri-devel Wed Jul 19 08:15:41 2023 From: Pekka Paalanen Date: Wed, 19 Jul 2023 08:15:41 +0000 To: dri-devel Subject: Re: [PATCH v5 9/9] drm: Introduce documentation for hotspot properties Message-Id: <20230719111541.33c05b14 () eldfell> X-MARC-Message: https://marc.info/?l=dri-devel&m=168975447519863 MIME-Version: 1 Content-Type: multipart/mixed; boundary="--Sig_/EiONIKEiq87f3GRwr6btSXQ" --Sig_/EiONIKEiq87f3GRwr6btSXQ Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable On Tue, 18 Jul 2023 21:42:18 -0400 Zack Rusin wrote: > From: Michael Banack >=20 > To clarify the intent and reasoning behind the hotspot properties > introduce userspace documentation that goes over cursor handling > in para-virtualized environments. >=20 > The documentation is generic enough to not special case for any > specific hypervisor and should apply equally to all. >=20 > Signed-off-by: Zack Rusin > --- > Documentation/gpu/drm-kms.rst | 6 ++++ > drivers/gpu/drm/drm_plane.c | 58 ++++++++++++++++++++++++++++++++++- > 2 files changed, 63 insertions(+), 1 deletion(-) >=20 > diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst > index c92d425cb2dd..7159b3e90a8a 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 > =20 > +Cursor Hotspot Properties > +--------------------------- > + > +.. kernel-doc:: drivers/gpu/drm/drm_plane.c > + :doc: hotspot properties > + > Existing KMS Properties > ----------------------- > =20 > diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c > index 1dc00ad4c33c..f3f2eae83cca 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; > } > =20 > +/** > + * 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 poi= nter, > + * 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 curs= or > + * 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-virtuali= zed > + * drivers (eg qxl, vbox, virtio, vmwgfx), that are attached to a user c= onsole > + * with a mouse pointer. Since these consoles are often being remoted o= ver a > + * network, they would otherwise have to wait to display the pointer mov= ement to > + * the user until a full network round-trip has occurred. New mouse eve= nts have > + * to be sent from the user's console, over the network to the virtual i= nput > + * 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 com= es in. > + * To do that correctly, the user's console must be able predict how the > + * desktop will process mouse events, which normally requires the deskto= p's > + * mouse topology information, ie where each CRTC sits in the mouse coor= dinate > + * space. This is typically sent to the para-virtualized drivers using = some > + * driver-specific method, and the driver then forwards it to the consol= e 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 de= vices > + * 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 pointer= s. > + * If the hotspot properties are set, the cursor plane is therefore assu= med to be > + * used only for displaying a mouse cursor image, and the position of th= e combined > + * cursor plane + offset can therefore be used for coordinating with inp= ut 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_HOTSP= OT. > + * 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. Advert= ising > + * DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT implies that the userspace client= will be > + * correctly setting the hotspot properties. > + */ Yes! This is exactly what I was after. Thank you! > + > /** > * 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 *d= ev, 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. I haven't seen the rendered HTML, but is there a hyperlink from here to the hotspot property doc? I think a link would be neat. > * > * RETURNS: > * Zero for success or -errno Anyway: Acked-by: Pekka Paalanen Thanks, pq --Sig_/EiONIKEiq87f3GRwr6btSXQ Content-Type: application/pgp-signature Content-Description: OpenPGP digital signature -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEJQjwWQChkWOYOIONI1/ltBGqqqcFAmS3m60ACgkQI1/ltBGq qqeWhA/+INvIt3UzSeaoyb+RxUcogyfCYo/BBTwuy+kOwhhgK0W0WNNKldfBLWTj 4iXSLe9QEpbm52//MEMhuoias3znGGuc/76Hxe1L0ccPr0gcwVZkIUDAGkWIGfJe 6bFdjFAu1MhLT97jCsnHdliUUS64rCnAU+VNEc00snynONYvWvhAwxO3Q8NNvp5i WKVE4B2GD6C69QjAl4PWrIc/hpxhjFj6Dvw7gALmHS4qT325LF/+9p/1+ECbGhID gdbTBFaJEcm5khhnrwJqk944qRLstDgYKErfuFI7TBUNlpSDe1ERcbib3DoTaWt6 gjnXqJGLkmdHnr1dGaIhVMsM9FUI0V002UGwDz3RdqxBckLIdNWdLg9iFJGweEdH 6A7ELCOCfqWdqCcpEGi2zg9eQkGeVBYtWpwMitl8HMZ00RDpuSpwWq7/FCTiQEpO NzGP98Btd7DT50COrKEaEyLW4Zgonmkxmn6UW3Zzo6pMbm9++l2i40QAbUcVd1Ym 47SwWGyDKxXB4MBfYKZHvrUunXoOOpGKcwwlH6iSej/mBzrBKR1dBu3sjaZ54ZRJ NXDBi7M6s7mqAwO8ulznDF30LwN3k5MxEhQ3FBpg3j5hVtWF55mCledlPO+5c3MO 0fPNR9/Xae9lEt6SuiCCcOxUYGI1unJwo+/b03f4N9DGn95XyL0= =+giF -----END PGP SIGNATURE----- --Sig_/EiONIKEiq87f3GRwr6btSXQ--