/* * Copyright (c) 2016 Intel Corporation * * Permission to use, copy, modify, distribute, and sell this software and its * documentation for any purpose is hereby granted without fee, provided that * the above copyright notice appear in all copies and that both that copyright * notice and this permission notice appear in supporting documentation, and * that the name of the copyright holders not be used in advertising or * publicity pertaining to distribution of the software without specific, * written prior permission. The copyright holders make no representations * about the suitability of this software for any purpose. It is provided "as * is" without express or implied warranty. * * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE * OF THIS SOFTWARE. */ #include <linux/slab.h> #include <linux/uaccess.h> #include <drm/drm_plane.h> #include <drm/drm_drv.h> #include <drm/drm_print.h> #include <drm/drm_framebuffer.h> #include <drm/drm_file.h> #include <drm/drm_crtc.h> #include <drm/drm_fourcc.h> #include <drm/drm_managed.h> #include <drm/drm_vblank.h> #include "drm_crtc_internal.h" /** * DOC: overview * * A plane represents an image source that can be blended with or overlaid on * top of a CRTC during the scanout process. Planes take their input data from a * &drm_framebuffer object. The plane itself specifies the cropping and scaling * of that image, and where it is placed on the visible area of a display * pipeline, represented by &drm_crtc. A plane can also have additional * properties that specify how the pixels are positioned and blended, like * rotation or Z-position. All these properties are stored in &drm_plane_state. * * Unless explicitly specified (via CRTC property or otherwise), the active area * of a CRTC will be black by default. This means portions of the active area * which are not covered by a plane will be black, and alpha blending of any * planes with the CRTC background will blend with black at the lowest zpos. * * To create a plane, a KMS drivers allocates and zeroes an instances of * &struct drm_plane (possibly as part of a larger structure) and registers it * with a call to drm_universal_plane_init(). * * Each plane has a type, see enum drm_plane_type. A plane can be compatible * with multiple CRTCs, see &drm_plane.possible_crtcs. * * Each CRTC must have a unique primary plane userspace can attach to enable * the CRTC. In other words, userspace must be able to attach a different * primary plane to each CRTC at the same time. Primary planes can still be * compatible with multiple CRTCs. There must be exactly as many primary planes * as there are CRTCs. * * Legacy uAPI doesn't expose the primary and cursor planes directly. DRM core * relies on the driver to set the primary and optionally the cursor plane used * for legacy IOCTLs. This is done by calling drm_crtc_init_with_planes(). All * drivers must provide one primary plane per CRTC to avoid surprising legacy * userspace too much. */ /** * DOC: standard plane properties * * DRM planes have a few standardized properties: * * type: * Immutable property describing the type of the plane. * * For user-space which has enabled the &DRM_CLIENT_CAP_ATOMIC capability, * the plane type is just a hint and is mostly superseded by atomic * test-only commits. The type hint can still be used to come up more * easily with a plane configuration accepted by the driver. * * The value of this property can be one of the following: * * "Primary": * To light up a CRTC, attaching a primary plane is the most likely to * work if it covers the whole CRTC and doesn't have scaling or * cropping set up. * * Drivers may support more features for the primary plane, user-space * can find out with test-only atomic commits. * * Some primary planes are implicitly used by the kernel in the legacy * IOCTLs &DRM_IOCTL_MODE_SETCRTC and &DRM_IOCTL_MODE_PAGE_FLIP. * Therefore user-space must not mix explicit usage of any primary * plane (e.g. through an atomic commit) with these legacy IOCTLs. * * "Cursor": * To enable this plane, using a framebuffer configured without scaling * or cropping and with the following properties is the most likely to * work: * * - If the driver provides the capabilities &DRM_CAP_CURSOR_WIDTH and * &DRM_CAP_CURSOR_HEIGHT, create the framebuffer with this size. * Otherwise, create a framebuffer with the size 64x64. * - If the driver doesn't support modifiers, create a framebuffer with * a linear layout. Otherwise, use the IN_FORMATS plane property. * * Drivers may support more features for the cursor plane, user-space * can find out with test-only atomic commits. * * Some cursor planes are implicitly used by the kernel in the legacy * IOCTLs &DRM_IOCTL_MODE_CURSOR and &DRM_IOCTL_MODE_CURSOR2. * Therefore user-space must not mix explicit usage of any cursor * plane (e.g. through an atomic commit) with these legacy IOCTLs. * * Some drivers may support cursors even if no cursor plane is exposed. * In this case, the legacy cursor IOCTLs can be used to configure the * cursor. * * "Overlay": * Neither primary nor cursor. * * Overlay planes are the only planes exposed when the * &DRM_CLIENT_CAP_UNIVERSAL_PLANES capability is disabled. * * IN_FORMATS: * Blob property which contains the set of buffer format and modifier * pairs supported by this plane. The blob is a struct * drm_format_modifier_blob. Without this property the plane doesn't * support buffers with modifiers. Userspace cannot change this property. * * Note that userspace can check the &DRM_CAP_ADDFB2_MODIFIERS driver * capability for general modifier support. If this flag is set then every * plane will have the IN_FORMATS property, even when it only supports * DRM_FORMAT_MOD_LINEAR. Before linux kernel release v5.1 there have been * various bugs in this area with inconsistencies between the capability * flag and per-plane properties. * * SIZE_HINTS: * Blob property which contains the set of recommended plane size * which can used for simple "cursor like" use cases (eg. no scaling). * Using these hints frees userspace from extensive probing of * supported plane sizes through atomic/setcursor ioctls. * * The blob contains an array of struct drm_plane_size_hint, in * order of preference. For optimal usage userspace should pick * the first size that satisfies its own requirements. * * Drivers should only attach this property to planes that * support a very limited set of sizes. * * Note that property value 0 (ie. no blob) is reserved for potential * future use. Current userspace is expected to ignore the property * if the value is 0, and fall back to some other means (eg. * &DRM_CAP_CURSOR_WIDTH and &DRM_CAP_CURSOR_HEIGHT) to determine * the appropriate plane size to use. */ static unsigned int drm_num_planes(struct drm_device *dev) { … } static inline u32 * formats_ptr(struct drm_format_modifier_blob *blob) { … } static inline struct drm_format_modifier * modifiers_ptr(struct drm_format_modifier_blob *blob) { … } static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane) { … } /** * 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. Look at the documentation for hotspot properties * to get a better understanding for what they're used for. * * RETURNS: * Zero for success or -errno */ static int drm_plane_create_hotspot_properties(struct drm_plane *plane) { … } __printf(9, 0) static int __drm_universal_plane_init(struct drm_device *dev, struct drm_plane *plane, uint32_t possible_crtcs, const struct drm_plane_funcs *funcs, const uint32_t *formats, unsigned int format_count, const uint64_t *format_modifiers, enum drm_plane_type type, const char *name, va_list ap) { … } /** * drm_universal_plane_init - Initialize a new universal plane object * @dev: DRM device * @plane: plane object to init * @possible_crtcs: bitmask of possible CRTCs * @funcs: callbacks for the new plane * @formats: array of supported formats (DRM_FORMAT\_\*) * @format_count: number of elements in @formats * @format_modifiers: array of struct drm_format modifiers terminated by * DRM_FORMAT_MOD_INVALID * @type: type of plane (overlay, primary, cursor) * @name: printf style format string for the plane name, or NULL for default name * * Initializes a plane object of type @type. The &drm_plane_funcs.destroy hook * should call drm_plane_cleanup() and kfree() the plane structure. The plane * structure should not be allocated with devm_kzalloc(). * * Note: consider using drmm_universal_plane_alloc() instead of * drm_universal_plane_init() to let the DRM managed resource infrastructure * take care of cleanup and deallocation. * * Drivers that only support the DRM_FORMAT_MOD_LINEAR modifier support may set * @format_modifiers to NULL. The plane will advertise the linear modifier. * * Returns: * Zero on success, error code on failure. */ int drm_universal_plane_init(struct drm_device *dev, struct drm_plane *plane, uint32_t possible_crtcs, const struct drm_plane_funcs *funcs, const uint32_t *formats, unsigned int format_count, const uint64_t *format_modifiers, enum drm_plane_type type, const char *name, ...) { … } EXPORT_SYMBOL(…); static void drmm_universal_plane_alloc_release(struct drm_device *dev, void *ptr) { … } void *__drmm_universal_plane_alloc(struct drm_device *dev, size_t size, size_t offset, uint32_t possible_crtcs, const struct drm_plane_funcs *funcs, const uint32_t *formats, unsigned int format_count, const uint64_t *format_modifiers, enum drm_plane_type type, const char *name, ...) { … } EXPORT_SYMBOL(…); void *__drm_universal_plane_alloc(struct drm_device *dev, size_t size, size_t offset, uint32_t possible_crtcs, const struct drm_plane_funcs *funcs, const uint32_t *formats, unsigned int format_count, const uint64_t *format_modifiers, enum drm_plane_type type, const char *name, ...) { … } EXPORT_SYMBOL(…); int drm_plane_register_all(struct drm_device *dev) { … } void drm_plane_unregister_all(struct drm_device *dev) { … } /** * drm_plane_cleanup - Clean up the core plane usage * @plane: plane to cleanup * * This function cleans up @plane and removes it from the DRM mode setting * core. Note that the function does *not* free the plane structure itself, * this is the responsibility of the caller. */ void drm_plane_cleanup(struct drm_plane *plane) { … } EXPORT_SYMBOL(…); /** * drm_plane_from_index - find the registered plane at an index * @dev: DRM device * @idx: index of registered plane to find for * * Given a plane index, return the registered plane from DRM device's * list of planes with matching index. This is the inverse of drm_plane_index(). */ struct drm_plane * drm_plane_from_index(struct drm_device *dev, int idx) { … } EXPORT_SYMBOL(…); /** * drm_plane_force_disable - Forcibly disable a plane * @plane: plane to disable * * Forces the plane to be disabled. * * Used when the plane's current framebuffer is destroyed, * and when restoring fbdev mode. * * Note that this function is not suitable for atomic drivers, since it doesn't * wire through the lock acquisition context properly and hence can't handle * retries or driver private locks. You probably want to use * drm_atomic_helper_disable_plane() or * drm_atomic_helper_disable_planes_on_crtc() instead. */ void drm_plane_force_disable(struct drm_plane *plane) { … } EXPORT_SYMBOL(…); /** * drm_mode_plane_set_obj_prop - set the value of a property * @plane: drm plane object to set property value for * @property: property to set * @value: value the property should be set to * * This functions sets a given property on a given plane object. This function * calls the driver's ->set_property callback and changes the software state of * the property if the callback succeeds. * * Returns: * Zero on success, error code on failure. */ int drm_mode_plane_set_obj_prop(struct drm_plane *plane, struct drm_property *property, uint64_t value) { … } EXPORT_SYMBOL(…); int drm_mode_getplane_res(struct drm_device *dev, void *data, struct drm_file *file_priv) { … } int drm_mode_getplane(struct drm_device *dev, void *data, struct drm_file *file_priv) { … } /** * drm_plane_has_format - Check whether the plane supports this format and modifier combination * @plane: drm plane * @format: pixel format (DRM_FORMAT_*) * @modifier: data layout modifier * * Returns: * Whether the plane supports the specified format and modifier combination. */ bool drm_plane_has_format(struct drm_plane *plane, u32 format, u64 modifier) { … } EXPORT_SYMBOL(…); static int __setplane_check(struct drm_plane *plane, struct drm_crtc *crtc, struct drm_framebuffer *fb, int32_t crtc_x, int32_t crtc_y, uint32_t crtc_w, uint32_t crtc_h, uint32_t src_x, uint32_t src_y, uint32_t src_w, uint32_t src_h) { … } /** * drm_any_plane_has_format - Check whether any plane supports this format and modifier combination * @dev: DRM device * @format: pixel format (DRM_FORMAT_*) * @modifier: data layout modifier * * Returns: * Whether at least one plane supports the specified format and modifier combination. */ bool drm_any_plane_has_format(struct drm_device *dev, u32 format, u64 modifier) { … } EXPORT_SYMBOL(…); /* * __setplane_internal - setplane handler for internal callers * * This function will take a reference on the new fb for the plane * on success. * * src_{x,y,w,h} are provided in 16.16 fixed point format */ static int __setplane_internal(struct drm_plane *plane, struct drm_crtc *crtc, struct drm_framebuffer *fb, int32_t crtc_x, int32_t crtc_y, uint32_t crtc_w, uint32_t crtc_h, /* src_{x,y,w,h} values are 16.16 fixed point */ uint32_t src_x, uint32_t src_y, uint32_t src_w, uint32_t src_h, struct drm_modeset_acquire_ctx *ctx) { … } static int __setplane_atomic(struct drm_plane *plane, struct drm_crtc *crtc, struct drm_framebuffer *fb, int32_t crtc_x, int32_t crtc_y, uint32_t crtc_w, uint32_t crtc_h, uint32_t src_x, uint32_t src_y, uint32_t src_w, uint32_t src_h, struct drm_modeset_acquire_ctx *ctx) { … } static int setplane_internal(struct drm_plane *plane, struct drm_crtc *crtc, struct drm_framebuffer *fb, int32_t crtc_x, int32_t crtc_y, uint32_t crtc_w, uint32_t crtc_h, /* src_{x,y,w,h} values are 16.16 fixed point */ uint32_t src_x, uint32_t src_y, uint32_t src_w, uint32_t src_h) { … } int drm_mode_setplane(struct drm_device *dev, void *data, struct drm_file *file_priv) { … } static int drm_mode_cursor_universal(struct drm_crtc *crtc, struct drm_mode_cursor2 *req, struct drm_file *file_priv, struct drm_modeset_acquire_ctx *ctx) { … } static int drm_mode_cursor_common(struct drm_device *dev, struct drm_mode_cursor2 *req, struct drm_file *file_priv) { … } int drm_mode_cursor_ioctl(struct drm_device *dev, void *data, struct drm_file *file_priv) { … } /* * Set the cursor configuration based on user request. This implements the 2nd * version of the cursor ioctl, which allows userspace to additionally specify * the hotspot of the pointer. */ int drm_mode_cursor2_ioctl(struct drm_device *dev, void *data, struct drm_file *file_priv) { … } int drm_mode_page_flip_ioctl(struct drm_device *dev, void *data, struct drm_file *file_priv) { … } /** * DOC: damage tracking * * FB_DAMAGE_CLIPS is an optional plane property which provides a means to * specify a list of damage rectangles on a plane in framebuffer coordinates of * the framebuffer attached to the plane. In current context damage is the area * of plane framebuffer that has changed since last plane update (also called * page-flip), irrespective of whether currently attached framebuffer is same as * framebuffer attached during last plane update or not. * * FB_DAMAGE_CLIPS is a hint to kernel which could be helpful for some drivers * to optimize internally especially for virtual devices where each framebuffer * change needs to be transmitted over network, usb, etc. * * Since FB_DAMAGE_CLIPS is a hint so it is an optional property. User-space can * ignore damage clips property and in that case driver will do a full plane * update. In case damage clips are provided then it is guaranteed that the area * inside damage clips will be updated to plane. For efficiency driver can do * full update or can update more than specified in damage clips. Since driver * is free to read more, user-space must always render the entire visible * framebuffer. Otherwise there can be corruptions. Also, if a user-space * provides damage clips which doesn't encompass the actual damage to * framebuffer (since last plane update) can result in incorrect rendering. * * FB_DAMAGE_CLIPS is a blob property with the layout of blob data is simply an * array of &drm_mode_rect. Unlike plane &drm_plane_state.src coordinates, * damage clips are not in 16.16 fixed point. Similar to plane src in * framebuffer, damage clips cannot be negative. In damage clip, x1/y1 are * inclusive and x2/y2 are exclusive. While kernel does not error for overlapped * damage clips, it is strongly discouraged. * * Drivers that are interested in damage interface for plane should enable * FB_DAMAGE_CLIPS property by calling drm_plane_enable_fb_damage_clips(). * Drivers implementing damage can use drm_atomic_helper_damage_iter_init() and * drm_atomic_helper_damage_iter_next() helper iterator function to get damage * rectangles clipped to &drm_plane_state.src. * * Note that there are two types of damage handling: frame damage and buffer * damage, the type of damage handling implemented depends on a driver's upload * target. Drivers implementing a per-plane or per-CRTC upload target need to * handle frame damage, while drivers implementing a per-buffer upload target * need to handle buffer damage. * * The existing damage helpers only support the frame damage type, there is no * buffer age support or similar damage accumulation algorithm implemented yet. * * Only drivers handling frame damage can use the mentioned damage helpers to * iterate over the damaged regions. Drivers that handle buffer damage, must set * &drm_plane_state.ignore_damage_clips for drm_atomic_helper_damage_iter_init() * to know that damage clips should be ignored and return &drm_plane_state.src * as the damage rectangle, to force a full plane update. * * Drivers with a per-buffer upload target could compare the &drm_plane_state.fb * of the old and new plane states to determine if the framebuffer attached to a * plane has changed or not since the last plane update. If &drm_plane_state.fb * has changed, then &drm_plane_state.ignore_damage_clips must be set to true. * * That is because drivers with a per-plane upload target, expect the backing * storage buffer to not change for a given plane. If the upload buffer changes * between page flips, the new upload buffer has to be updated as a whole. This * can be improved in the future if support for frame damage is added to the DRM * damage helpers, similarly to how user-space already handle this case as it is * explained in the following documents: * * https://registry.khronos.org/EGL/extensions/KHR/EGL_KHR_swap_buffers_with_damage.txt * https://emersion.fr/blog/2019/intro-to-damage-tracking/ */ /** * drm_plane_enable_fb_damage_clips - Enables plane fb damage clips property. * @plane: Plane on which to enable damage clips property. * * This function lets driver to enable the damage clips property on a plane. */ void drm_plane_enable_fb_damage_clips(struct drm_plane *plane) { … } EXPORT_SYMBOL(…); /** * drm_plane_get_damage_clips_count - Returns damage clips count. * @state: Plane state. * * Simple helper to get the number of &drm_mode_rect clips set by user-space * during plane update. * * Return: Number of clips in plane fb_damage_clips blob property. */ unsigned int drm_plane_get_damage_clips_count(const struct drm_plane_state *state) { … } EXPORT_SYMBOL(…); struct drm_mode_rect * __drm_plane_get_damage_clips(const struct drm_plane_state *state) { … } /** * drm_plane_get_damage_clips - Returns damage clips. * @state: Plane state. * * Note that this function returns uapi type &drm_mode_rect. Drivers might want * to use the helper functions drm_atomic_helper_damage_iter_init() and * drm_atomic_helper_damage_iter_next() or drm_atomic_helper_damage_merged() if * the driver can only handle a single damage region at most. * * Return: Damage clips in plane fb_damage_clips blob property. */ struct drm_mode_rect * drm_plane_get_damage_clips(const struct drm_plane_state *state) { … } EXPORT_SYMBOL(…); struct drm_property * drm_create_scaling_filter_prop(struct drm_device *dev, unsigned int supported_filters) { … } /** * drm_plane_create_scaling_filter_property - create a new scaling filter * property * * @plane: drm plane * @supported_filters: bitmask of supported scaling filters, must include * BIT(DRM_SCALING_FILTER_DEFAULT). * * This function lets driver to enable the scaling filter property on a given * plane. * * RETURNS: * Zero for success or -errno */ int drm_plane_create_scaling_filter_property(struct drm_plane *plane, unsigned int supported_filters) { … } EXPORT_SYMBOL(…); /** * drm_plane_add_size_hints_property - create a size hints property * * @plane: drm plane * @hints: size hints * @num_hints: number of size hints * * Create a size hints property for the plane. * * RETURNS: * Zero for success or -errno */ int drm_plane_add_size_hints_property(struct drm_plane *plane, const struct drm_plane_size_hint *hints, int num_hints) { … } EXPORT_SYMBOL(…);
Codebase Browser
linux