drm: Introduce documentation for hotspot 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

-----------------------

	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

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