Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-14 16:12:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

drm: Introduce documentation for hotspot properties

Browse Source 
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>
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Reviewed-by: Javier Martinez Canillas <javierm@redhat.com>
Signed-off-by: Michael Banack <banackm@vmware.com>
Signed-off-by: Javier Martinez Canillas <javierm@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20231023074613.41327-10-aesteve@redhat.com
This commit is contained in:
Michael Banack 2023-10-23 09:46:13 +02:00 committed by Javier Martinez Canillas
parent 9724ed6c1b
commit 4653f9d014
No known key found for this signature in database
GPG Key ID: C751E590D63F3D69
2 changed files with 63 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Documentation/gpu/drm-kms.rst
View File

@ -579,6 +579,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
-----------------------

58
drivers/gpu/drm/drm_plane.c
View File

@ -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