diff options
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 42 | ||||
| -rw-r--r-- | drivers/gpu/drm/drm_dumb_buffers.c | 46 | ||||
| -rw-r--r-- | include/drm/drm_drv.h | 48 |
3 files changed, 67 insertions, 69 deletions
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index cb0d3537b705..4edfb6d91250 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -72,46 +72,8 @@ DRM Format Handling 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 :c:type:`struct drm_mode_create_dumb - <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 - :c:func:`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. +.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c + :doc: overview Plane Abstraction ================= diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c index cd291b538f5a..8ac5a1c1d811 100644 --- a/drivers/gpu/drm/drm_dumb_buffers.c +++ b/drivers/gpu/drm/drm_dumb_buffers.c @@ -28,24 +28,29 @@ #include "drm_crtc_internal.h" /** - * drm_mode_create_dumb_ioctl - create a dumb backing storage buffer - * @dev: DRM device - * @data: ioctl data - * @file_priv: DRM file info + * DOC: overview * - * This creates a new dumb buffer in the driver's backing storage manager (GEM, - * TTM or something else entirely) and returns the resulting buffer handle. This - * handle can then be wrapped up into a framebuffer modeset object. + * 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. * - * Note that userspace is not allowed to use such objects for render - * acceleration - drivers must create their own private ioctls for such a use - * case. + * 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. * - * Called by the user via ioctl. + * To support dumb objects drivers must implement the dumb_create, + * dumb_destroy and dumb_map_offset operations from struct &drm_driver. See + * there for further details. * - * Returns: - * Zero on success, negative errno on failure. + * 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. */ + int drm_mode_create_dumb_ioctl(struct drm_device *dev, void *data, struct drm_file *file_priv) { @@ -110,21 +115,6 @@ int drm_mode_mmap_dumb_ioctl(struct drm_device *dev, return dev->driver->dumb_map_offset(file_priv, dev, args->handle, &args->offset); } -/** - * drm_mode_destroy_dumb_ioctl - destroy a dumb backing strage buffer - * @dev: DRM device - * @data: ioctl data - * @file_priv: DRM file info - * - * This destroys the userspace handle for the given dumb backing storage buffer. - * Since buffer objects must be reference counted in the kernel a buffer object - * won't be immediately freed if a framebuffer modeset object still uses it. - * - * Called by the user via ioctl. - * - * Returns: - * Zero on success, negative errno on failure. - */ int drm_mode_destroy_dumb_ioctl(struct drm_device *dev, void *data, struct drm_file *file_priv) { diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h index 048086e38ef6..aad8bbacd1f0 100644 --- a/include/drm/drm_drv.h +++ b/include/drm/drm_drv.h @@ -328,13 +328,59 @@ struct drm_driver { /* vga arb irq handler */ void (*vgaarb_irq)(struct drm_device *dev, bool state); - /* dumb alloc support */ + /** + * @dumb_create: + * + * This creates a new dumb buffer in the driver's backing storage manager (GEM, + * TTM or something else entirely) and returns the resulting buffer handle. This + * handle can then be wrapped up into a framebuffer modeset object. + * + * Note that userspace is not allowed to use such objects for render + * acceleration - drivers must create their own private ioctls for such a use + * case. + * + * Width, height and depth are specified in the &drm_mode_create_dumb + * argument. The callback needs to fill the handle, pitch and size for + * the created buffer. + * + * Called by the user via ioctl. + * + * Returns: + * + * Zero on success, negative errno on failure. + */ int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, struct drm_mode_create_dumb *args); + /** + * @dumb_map_offset: + * + * Allocate an offset in the drm device node's address space to be able to + * memory map a dumb buffer. GEM-based drivers must use + * drm_gem_create_mmap_offset() to implement this. + * + * Called by the user via ioctl. + * + * Returns: + * + * Zero on success, negative errno on failure. + */ int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, uint32_t handle, uint64_t *offset); + /** + * @dumb_destroy: + * + * This destroys the userspace handle for the given dumb backing storage buffer. + * Since buffer objects must be reference counted in the kernel a buffer object + * won't be immediately freed if a framebuffer modeset object still uses it. + * + * Called by the user via ioctl. + * + * Returns: + * + * Zero on success, negative errno on failure. + */ int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, uint32_t handle); |