On Tue, Dec 22, 2020 at 02:35:21PM +0100, Simon Ser wrote:
Add a new entry for "type" in the section for standard plane properties.
v3: improve paragraph about mixing legacy IOCTLs with explicit usage, not that a driver may support cursors without cursor planes (Daniel)
s/not/note/
v4: fixing rebase gone wrong
Signed-off-by: Simon Ser contact@emersion.fr Cc: Daniel Vetter daniel@ffwll.ch Cc: Pekka Paalanen ppaalanen@gmail.com
drivers/gpu/drm/drm_plane.c | 58 ++++++++++++++++++++++++++++++++++--- 1 file changed, 54 insertions(+), 4 deletions(-)
diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c index b15b65e48555..9dce5be5780c 100644 --- a/drivers/gpu/drm/drm_plane.c +++ b/drivers/gpu/drm/drm_plane.c @@ -49,10 +49,8 @@
- &struct drm_plane (possibly as part of a larger structure) and registers it
- with a call to drm_universal_plane_init().
- The type of a plane is exposed in the immutable "type" enumeration property,
- which has one of the following values: "Overlay", "Primary", "Cursor" (see
- enum drm_plane_type). A plane can be compatible with multiple CRTCs, see
- &drm_plane.possible_crtcs.
- 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
@@ -72,6 +70,58 @@
- 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_UNIVERSAL_PLANES
s/UNIVERSAL_PLANES/ATOMIC/ here?
With just universal planes you don't have atomic test-only. But I guess it also works as-is, I'm just not entirely clear what you want to state here.
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. Note that
&DRM_CLIENT_CAP_UNIVERSAL_PLANES is implicitly enabled by
&DRM_CLIENT_CAP_ATOMIC.
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.
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.
Empty line here for reading comfort in plain text? Same below.
Since you mention formats below, I also wonder whether we should state here that xrgb8888 is generally supported, worst case through software emulation. That's defacto the uapi we have to adhere to.
"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.
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.
Just some thoughts about, feel free to merge as-is.
Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch
- IN_FORMATS:
Blob property which contains the set of buffer format and modifierpairs supported by this plane. The blob is a struct-- 2.29.2