Pekka Paalanen
2023-Oct-23 08:23 UTC
[PATCH v6 9/9] drm: Introduce documentation for hotspot properties
On Mon, 23 Oct 2023 09:46:13 +0200 Albert Esteve <aesteve at redhat.com> wrote:> From: Michael Banack <banackm at 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 at vmware.com>Hi, the below doc text: Acked-by: Pekka Paalanen <pekka.paalanen at 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-------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 833 bytes Desc: OpenPGP digital signature URL: <http://lists.linuxfoundation.org/pipermail/virtualization/attachments/20231023/549981a0/attachment.sig>