Commit 2d38f5fe authored by Maxime Ripard's avatar Maxime Ripard Committed by Jonathan Corbet
Browse files

Documentation: dma-buf: heaps: Add heap name definitions 



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: default avatarT.J. Mercier <tjmercier@google.com>
Signed-off-by: default avatarMaxime Ripard <mripard@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250306135114.1943738-1-mripard@kernel.org
parent 5a63f036

Documentation/userspace-api/dma-buf-heaps.rst

0 → 100644
+25 −0
Original line number Diff line number Diff line 
.. 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``.

Documentation/userspace-api/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -44,6 +44,7 @@ Devices and I/O 
   :maxdepth: 1



   accelerators/ocxl

   dma-buf-heaps

   dma-buf-alloc-exchange

   gpio/index

   iommufd

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -6913,6 +6913,7 @@ 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