From patchwork Thu Mar 6 13:51:14 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Ripard X-Patchwork-Id: 14004523 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 540EEC282D1 for ; Thu, 6 Mar 2025 13:51:21 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id BAE2610E98B; Thu, 6 Mar 2025 13:51:20 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (2048-bit key; unprotected) header.d=kernel.org header.i=@kernel.org header.b="PfZHbCsG"; dkim-atps=neutral Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by gabe.freedesktop.org (Postfix) with ESMTPS id 9661F10E98B for ; Thu, 6 Mar 2025 13:51:18 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 38C985C5752; Thu, 6 Mar 2025 13:49:01 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 63F30C4CEE0; Thu, 6 Mar 2025 13:51:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1741269077; bh=xMq/gXwuGbOwdPZKg7OBqBV81DdiKtrLBRNuI+qJwjc=; h=From:To:Cc:Subject:Date:From; b=PfZHbCsGmbNbw3l6km+Hk/s/99YLXQIB10uxwOjopesXwDCt52NATDEW9Gx1Kp0Qa dmhV1g09jA9sCfaVNdq2C+bY4hQK2Hh7JyZLoo4IHVwMwLs4unG94Xj7a+MdLDp0xJ zGCHbo1rKEDpu54xGOlwxFmHCuH7IwxFHZCgGcNbz70Y12Y3y6G/BEAypXnm8Xigma fBYprMIew0gE417YJe6fkMKrpJKOrqRC0oEImHCxHP4s7TCSydEsfOUTshPebJbqZ+ B1Q5bhSTTzpaHvdg/whFGG1IjVIniSQ4by83SDauPrKKYyW7CJYhiRHUoearz2Sobi Ifv8T8P6oLIMQ== From: Maxime Ripard To: Jonathan Corbet , Sumit Semwal Cc: Benjamin Gaignard , Brian Starkey , John Stultz , "T . J . Mercier" , =?utf-8?q?Christian_K=C3=B6nig?= , dri-devel@lists.freedesktop.org, linaro-mm-sig@lists.linaro.org, linux-media@vger.kernel.org, linux-doc@vger.kernel.org, Maxime Ripard Subject: [PATCH v4] Documentation: dma-buf: heaps: Add heap name definitions Date: Thu, 6 Mar 2025 14:51:14 +0100 Message-ID: <20250306135114.1943738-1-mripard@kernel.org> X-Mailer: git-send-email 2.48.1 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: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Following a recent discussion at last Plumbers, John Stultz, Sumit Sewal, TJ Mercier and I came to an agreement that we should document what the dma-buf heaps names are expected to be, and what the buffers attributes you'll get should be documented. Let's create that doc to make sure those attributes and names are guaranteed going forward. Reviewed-by: T.J. Mercier Signed-off-by: Maxime Ripard --- Changes from v3: - Add TJ RB - Fix a few typos. Changes from v2: - Remove exhaustive list of names for platforms, and just mention the alternatives. - Add MAINTAINERS entry Changes from v1: - Add the mention that the cma / reserved heap is optional. --- Documentation/userspace-api/dma-buf-heaps.rst | 25 +++++++++++++++++++ Documentation/userspace-api/index.rst | 1 + MAINTAINERS | 1 + 3 files changed, 27 insertions(+) create mode 100644 Documentation/userspace-api/dma-buf-heaps.rst diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst new file mode 100644 index 000000000000..535f49047ce6 --- /dev/null +++ b/Documentation/userspace-api/dma-buf-heaps.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Allocating dma-buf using heaps +============================== + +Dma-buf Heaps are a way for userspace to allocate dma-buf objects. They are +typically used to allocate buffers from a specific allocation pool, or to share +buffers across frameworks. + +Heaps +===== + +A heap represents a specific allocator. The Linux kernel currently supports the +following heaps: + + - The ``system`` heap allocates virtually contiguous, cacheable, buffers. + + - The ``cma`` heap allocates physically contiguous, cacheable, + buffers. Only present if a CMA region is present. Such a region is + usually created either through the kernel commandline through the + `cma` parameter, a memory region Device-Tree node with the + `linux,cma-default` property set, or through the `CMA_SIZE_MBYTES` or + `CMA_SIZE_PERCENTAGE` Kconfig options. Depending on the platform, it + might be called ``reserved``, ``linux,cma``, or ``default-pool``. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index b1395d94b3fd..9cbe4390c872 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -42,10 +42,11 @@ Devices and I/O .. toctree:: :maxdepth: 1 accelerators/ocxl + dma-buf-heaps dma-buf-alloc-exchange gpio/index iommufd media/index dcdbas diff --git a/MAINTAINERS b/MAINTAINERS index 8e0736dc2ee0..ef0364e65aef 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6911,10 +6911,11 @@ R: T.J. Mercier L: linux-media@vger.kernel.org L: dri-devel@lists.freedesktop.org L: linaro-mm-sig@lists.linaro.org (moderated for non-subscribers) S: Maintained T: git https://gitlab.freedesktop.org/drm/misc/kernel.git +F: Documentation/userspace-api/dma-buf-heaps.rst F: drivers/dma-buf/dma-heap.c F: drivers/dma-buf/heaps/* F: include/linux/dma-heap.h F: include/uapi/linux/dma-heap.h F: tools/testing/selftests/dmabuf-heaps/