From patchwork Thu Aug 3 10:00:44 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Ser X-Patchwork-Id: 13339648 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 21E86C001DF for ; Thu, 3 Aug 2023 10:01:01 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 6A5BE10E1EC; Thu, 3 Aug 2023 10:01:00 +0000 (UTC) Received: from mail-4323.proton.ch (mail-4323.proton.ch [185.70.43.23]) by gabe.freedesktop.org (Postfix) with ESMTPS id E86CC10E1EC for ; Thu, 3 Aug 2023 10:00:57 +0000 (UTC) Date: Thu, 03 Aug 2023 10:00:44 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=emersion.fr; s=protonmail2; t=1691056855; x=1691316055; bh=Hdh/Bqt+51KexXaKf0kDJwkPb5E1pWzqPB5wYpJIKh8=; h=Date:To:From:Cc:Subject:Message-ID:Feedback-ID:From:To:Cc:Date: Subject:Reply-To:Feedback-ID:Message-ID:BIMI-Selector; b=lBYtYJ/TpVU7VIJdd7Wis8eoF7NLxKZwDFaqei7gra6TppFsRx93pMpszcIhF6J63 t21eCWA3sn4qYhqqji4evt9hcMiUWSTSyzfJLv/ijZNIZASzpECr+xXVkIo+uLgX29 5HQfKYGXSv7EtL+DtnxxqM+dV0JYxlJq5kcBY3uvVgi8F2nRjdDIW07f7dSTEdZ7YU zZYzUKwvyPdGoGIT1pfw8hSPQURzOnFCBwa4Gzx/dhZ9nLeexYzwzsB9QKfr+P7juP 08eOoGtZVO9fHo1ZayS1qvFW93/kVXn7oiwMr3fcy5Yy8DpdT/TNAMBLkgE/F1mNWG +nE+kImOTbImA== To: dri-devel@lists.freedesktop.org From: Simon Ser Subject: [PATCH] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB Message-ID: <20230803100041.387404-1-contact@emersion.fr> Feedback-ID: 1358184:user:proton MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Daniel Vetter , Pekka Paalanen Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" The main motivation is to repeat that dumb buffers should not be abused for anything else than basic software rendering with KMS. User-space devs are more likely to look at the IOCTL docs than to actively search for the driver-oriented "Dumb Buffer Objects" section. Signed-off-by: Simon Ser Cc: Daniel Vetter Cc: Pekka Paalanen Acked-by: Pekka Paalanen --- Documentation/gpu/drm-kms.rst | 2 ++ include/uapi/drm/drm.h | 15 +++++++++++++++ include/uapi/drm/drm_mode.h | 16 ++++++++++++++-- 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index c92d425cb2dd..ca9210e47266 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -360,6 +360,8 @@ Format Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export: +.. _kms_dumb_buffer_objects: + Dumb Buffer Objects =================== diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h index 863e47200911..625dba7ddbfe 100644 --- a/include/uapi/drm/drm.h +++ b/include/uapi/drm/drm.h @@ -1128,6 +1128,21 @@ extern "C" { #define DRM_IOCTL_MODE_PAGE_FLIP DRM_IOWR(0xB0, struct drm_mode_crtc_page_flip) #define DRM_IOCTL_MODE_DIRTYFB DRM_IOWR(0xB1, struct drm_mode_fb_dirty_cmd) +/** + * DRM_IOCTL_MODE_CREATE_DUMB - Create a new dumb buffer object. + * + * KMS dumb buffers provide a very primitive way to allocate a buffer object + * suitable for scanout and map it for software rendering. KMS dumb buffers are + * not suitable for hardware-accelerated rendering nor video decoding. KMS dumb + * buffers are not suitable to be displayed without KMS. Also see + * :ref:`kms_dumb_buffer_objects`. + * + * The IOCTL argument is a struct drm_mode_create_dumb. + * + * User-space is expected to create a KMS dumb buffer via this IOCTL, then add + * it as a KMS framebuffer via &DRM_IOCTL_MODE_ADDFB and map it via + * &DRM_IOCTL_MODE_MAP_DUMB. + */ #define DRM_IOCTL_MODE_CREATE_DUMB DRM_IOWR(0xB2, struct drm_mode_create_dumb) #define DRM_IOCTL_MODE_MAP_DUMB DRM_IOWR(0xB3, struct drm_mode_map_dumb) #define DRM_IOCTL_MODE_DESTROY_DUMB DRM_IOWR(0xB4, struct drm_mode_destroy_dumb) diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h index 92d96a2b6763..8a7e747f0564 100644 --- a/include/uapi/drm/drm_mode.h +++ b/include/uapi/drm/drm_mode.h @@ -1029,13 +1029,25 @@ struct drm_mode_crtc_page_flip_target { __u64 user_data; }; -/* create a dumb scanout buffer */ +/** + * struct drm_mode_create_dumb - Create a KMS dumb buffer for scanout. + * @height: buffer height in pixels + * @width: buffer width in pixels + * @bpp: bits per pixel + * @flags: must be zero + * @handle: buffer object handle + * @pitch: number of bytes between two consecutive lines + * @size: size of the whole buffer in bytes + * + * User-space fills @height, @width, @bpp and @flags. If the IOCTL succeeds, + * the kernel fills @handle, @pitch and @size. + */ struct drm_mode_create_dumb { __u32 height; __u32 width; __u32 bpp; __u32 flags; - /* handle, pitch, size will be returned */ + __u32 handle; __u32 pitch; __u64 size;