[PATCH] Documentation: dma-buf: heaps: Add heap name definitions

Tue Oct 1 21:03:41 UTC 2024

On Mon, Sep 30, 2024 at 4:41 PM Maxime Ripard <mripard at kernel.org> wrote:
>
> 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.

Hey, thanks for sending this!

> Signed-off-by: Maxime Ripard <mripard at kernel.org>
>
> ---
>
> To: Jonathan Corbet <corbet at lwn.net>
> To: Sumit Semwal <sumit.semwal at linaro.org>
> Cc: Benjamin Gaignard <benjamin.gaignard at collabora.com>
> Cc: Brian Starkey <Brian.Starkey at arm.com>
> Cc: John Stultz <jstultz at google.com>
> Cc: "T.J. Mercier" <tjmercier at google.com>
> Cc: "Christian König" <christian.koenig at amd.com>
> Cc: dri-devel at lists.freedesktop.org
> Cc: linaro-mm-sig at lists.linaro.org
> Cc: linux-media at vger.kernel.org
> Cc: linux-doc at vger.kernel.org
> ---
>  Documentation/userspace-api/dma-buf-heaps.rst | 71 +++++++++++++++++++
>  Documentation/userspace-api/index.rst         |  1 +
>  2 files changed, 72 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..00436227b542
> --- /dev/null
> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> @@ -0,0 +1,71 @@
> +.. 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 represent a specific allocator. The Linux kernel currently supports the

"represents"

> +following heaps:
> +
> + - The ``system`` heap allocates virtually contiguous, cacheable, buffers

Virtually contiguous sounds a little weird to me here. Sure, that's
what userspace will get when it maps the buffer (and I guess this *is*
UAPI documentation after all), but I'm not sure it's correct to say
that's a property of the buffer itself? What if we invert this and
instead say that there is NO guarantee that the memory for the buffer:
 - is physically contiguous
 - has any particular alignment (greater than page aligned)
 - has any particular page size (large order allocations are attempted
first, but not guaranteed or even likely on some systems)
 - has bounds on physical addresses

Maybe that is too much detail here...

> +
> + - The ``reserved`` heap allocates physically contiguous, cacheable, buffers.
> +   Depending on the platform, it might be called differently:
> +
> +    - Acer Iconia Tab A500: ``linux,cma``
> +    - Allwinner sun4i, sun5i and sun7i families: ``default-pool``
> +    - Amlogic A1: ``linux,cma``
> +    - Amlogic G12A/G12B/SM1: ``linux,cma``
> +    - Amlogic GXBB/GXL: ``linux,cma``
> +    - ASUS EeePad Transformer TF101: ``linux,cma``
> +    - ASUS Google Nexus 7 (Project Bach / ME370TG) E1565: ``linux,cma``
> +    - ASUS Google Nexus 7 (Project Nakasi / ME370T) E1565: ``linux,cma``
> +    - ASUS Google Nexus 7 (Project Nakasi / ME370T) PM269: ``linux,cma``
> +    - Asus Transformer Infinity TF700T: ``linux,cma``
> +    - Asus Transformer Pad 3G TF300TG: ``linux,cma``
> +    - Asus Transformer Pad TF300T: ``linux,cma``
> +    - Asus Transformer Pad TF701T: ``linux,cma``
> +    - Asus Transformer Prime TF201: ``linux,cma``
> +    - ASUS Vivobook S 15: ``linux,cma``
> +    - Cadence KC705: ``linux,cma``
> +    - Digi International ConnectCore 6UL: ``linux,cma``
> +    - Freescale i.MX8DXL EVK: ``linux,cma``
> +    - Freescale TQMa8Xx: ``linux,cma``
> +    - Hisilicon Hikey: ``linux,cma``
> +    - Lenovo ThinkPad T14s Gen 6: ``linux,cma``
> +    - Lenovo ThinkPad X13s: ``linux,cma``
> +    - Lenovo Yoga Slim 7x: ``linux,cma``
> +    - LG Optimus 4X HD P880: ``linux,cma``
> +    - LG Optimus Vu P895: ``linux,cma``
> +    - Loongson 2k0500, 2k1000 and 2k2000: ``linux,cma``
> +    - Microsoft Romulus: ``linux,cma``
> +    - NXP i.MX8ULP EVK: ``linux,cma``
> +    - NXP i.MX93 9x9 QSB: ``linux,cma``
> +    - NXP i.MX93 11X11 EVK: ``linux,cma``
> +    - NXP i.MX93 14X14 EVK: ``linux,cma``
> +    - NXP i.MX95 19X19 EVK: ``linux,cma``
> +    - Ouya Game Console: ``linux,cma``
> +    - Pegatron Chagall: ``linux,cma``
> +    - PHYTEC phyCORE-AM62A SOM: ``linux,cma``
> +    - PHYTEC phyCORE-i.MX93 SOM: ``linux,cma``
> +    - Qualcomm SC8280XP CRD: ``linux,cma``
> +    - Qualcomm X1E80100 CRD: ``linux,cma``
> +    - Qualcomm X1E80100 QCP: ``linux,cma``
> +    - RaspberryPi: ``linux,cma``
> +    - Texas Instruments AM62x SK board family: ``linux,cma``
> +    - Texas Instruments AM62A7 SK: ``linux,cma``
> +    - Toradex Apalis iMX8: ``linux,cma``
> +    - TQ-Systems i.MX8MM TQMa8MxML: ``linux,cma``
> +    - TQ-Systems i.MX8MN TQMa8MxNL: ``linux,cma``
> +    - TQ-Systems i.MX8MPlus TQMa8MPxL: ``linux,cma``
> +    - TQ-Systems i.MX8MQ TQMa8MQ: ``linux,cma``
> +    - TQ-Systems i.MX93 TQMa93xxLA/TQMa93xxCA SOM: ``linux,cma``
> +    - TQ-Systems MBA6ULx Baseboard: ``linux,cma``
> +

This part LGTM. Might be worth it to document that a CMA region must
be specified on the kernel command line. Otherwise this heap won't
show up at runtime by only enabling the kernel configs necessary to
build it.

> diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
> index 274cc7546efc..4901ce7c6cb7 100644
> --- a/Documentation/userspace-api/index.rst
> +++ b/Documentation/userspace-api/index.rst
> @@ -41,10 +41,11 @@ Devices and I/O
>
>  .. toctree::
>     :maxdepth: 1
>
>     accelerators/ocxl
> +   dma-buf-heaps
>     dma-buf-alloc-exchange
>     gpio/index
>     iommufd
>     media/index
>     dcdbas
> --
> 2.46.1
>