From 065a5027dca8e9383ac308de4310e8e850b0cafb Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Tue, 21 Jan 2014 12:01:41 +0100 Subject: [PATCH] drm/doc: Clarify the dumb object interfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - This is _not_ a generic interface to create gem objects, but just an interface to make early boot services (like boot splash) with a generic KMS userspace driver possible. Hence it's better to move the documentation for this from the GEM section to the KMS section, next to the creation of framebuffer objects. - Make it really clear that the returned handle isn't necessarily a GEM object (it can also be e.g. a TTM handle when running on top of vmwgfx). - Add a paragraph to make it clear that this is just for unaccelarated userspace - gpu drivers need to have their own buffer object creation ioctl which is hardware specific. v2: Clarify that the documentation doesn't just apply to GEM-based drivers only but is now generally valid, as suggested by David. v3: Polish the intro sentence a bit and one s/objects/handles/ for clarification, both suggested by Laurent. v4: More text polish from Laurent's review. v5: More typo fixes from Dieter. Cc: Dieter Nützel Cc: David Herrmann Cc: Laurent Pinchart Acked-by: Laurent Pinchart Reviewed-by: Alex Deucher Signed-off-by: Daniel Vetter --- Documentation/DocBook/drm.tmpl | 133 ++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 61 deletions(-) diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index ed1d6d289022..f2d0f5b89194 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -829,62 +829,6 @@ char *date; faults can implement their own mmap file operation handler. - - Dumb GEM Objects - - The GEM API doesn't standardize GEM objects creation and leaves it to - driver-specific ioctls. While not an issue for full-fledged graphics - stacks that include device-specific userspace components (in libdrm for - instance), this limit makes DRM-based early boot graphics unnecessarily - complex. - - - Dumb GEM objects partly alleviate the problem by providing a standard - API to create dumb buffers suitable for scanout, which can then be used - to create KMS frame buffers. - - - To support dumb GEM objects drivers must implement the - dumb_create, - dumb_destroy and - dumb_map_offset operations. - - - - int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, - struct drm_mode_create_dumb *args); - - The dumb_create operation creates a GEM - object suitable for scanout based on the width, height and depth - from the struct drm_mode_create_dumb - argument. It fills the argument's handle, - pitch and size - fields with a handle for the newly created GEM object and its line - pitch and size in bytes. - - - - int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle); - - The dumb_destroy operation destroys a dumb - GEM object created by dumb_create. - - - - int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, - uint32_t handle, uint64_t *offset); - - The dumb_map_offset operation associates an - mmap fake offset with the GEM object given by the handle and returns - it. Drivers must use the - drm_gem_create_mmap_offset function to - associate the fake offset as described in - . - - - - Memory Coherency @@ -968,9 +912,11 @@ int max_width, max_height; Frame buffers rely on the underneath memory manager for low-level memory operations. When creating a frame buffer applications pass a memory handle (or a list of memory handles for multi-planar formats) through - the drm_mode_fb_cmd2 argument. This document - assumes that the driver uses GEM, those handles thus reference GEM - objects. + the drm_mode_fb_cmd2 argument. For drivers using + GEM as their userspace buffer management interface this would be a GEM + handle. Drivers are however free to use their own backing storage object + handles, e.g. vmwgfx directly exposes special TTM handles to userspace + and so expects TTM handles in the create ioctl and not GEM handles. Drivers must first validate the requested frame buffer parameters passed @@ -992,7 +938,7 @@ int max_width, max_height; - The initailization of the new framebuffer instance is finalized with a + The initialization of the new framebuffer instance is finalized with a call to drm_framebuffer_init which takes a pointer to DRM frame buffer operations (struct drm_framebuffer_funcs). Note that this function @@ -1051,6 +997,71 @@ int max_width, max_height; unload time with drm_framebuffer_unregister_private. + + Dumb Buffer Objects + + The KMS API doesn't standardize backing storage object creation and + leaves it to driver-specific ioctls. Furthermore actually creating a + buffer object even for GEM-based drivers is done through a + driver-specific ioctl - GEM only has a common userspace interface for + sharing and destroying objects. While not an issue for full-fledged + graphics stacks that include device-specific userspace components (in + libdrm for instance), this limit makes DRM-based early boot graphics + unnecessarily complex. + + + Dumb objects partly alleviate the problem by providing a standard + API to create dumb buffers suitable for scanout, which can then be used + to create KMS frame buffers. + + + To support dumb objects drivers must implement the + dumb_create, + dumb_destroy and + dumb_map_offset operations. + + + + int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, + struct drm_mode_create_dumb *args); + + The dumb_create operation creates a driver + object (GEM or TTM handle) suitable for scanout based on the + width, height and depth from the struct + drm_mode_create_dumb argument. It fills the + argument's handle, + pitch and size + fields with a handle for the newly created object and its line + pitch and size in bytes. + + + + int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle); + + The dumb_destroy operation destroys a dumb + object created by dumb_create. + + + + int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle, uint64_t *offset); + + The dumb_map_offset operation associates an + mmap fake offset with the object given by the handle and returns + it. Drivers must use the + drm_gem_create_mmap_offset function to + associate the fake offset as described in + . + + + + + Note that dumb objects may not be used for gpu acceleration, as has been + attempted on some ARM embedded platforms. Such drivers really must have + a hardware-specific ioctl to allocate suitable buffer objects. + + Output Polling void (*output_poll_changed)(struct drm_device *dev); @@ -2134,7 +2145,7 @@ void intel_crt_init(struct drm_device *dev) set the display_info width_mm and height_mm fields if they haven't been set - already (for instance at initilization time when a fixed-size panel is + already (for instance at initialization time when a fixed-size panel is attached to the connector). The mode width_mm and height_mm fields are only used internally during EDID parsing and should not be set when creating modes manually.