diff mbox series

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

Message ID 20240930144057.453751-1-mripard@kernel.org (mailing list archive)
State New
Headers show
Series Documentation: dma-buf: heaps: Add heap name definitions | expand

Commit Message

Maxime Ripard Sept. 30, 2024, 2:40 p.m. UTC 
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.

Signed-off-by: Maxime Ripard <mripard@kernel.org>

---

To: Jonathan Corbet <corbet@lwn.net>
To: Sumit Semwal <sumit.semwal@linaro.org>
Cc: Benjamin Gaignard <benjamin.gaignard@collabora.com>
Cc: Brian Starkey <Brian.Starkey@arm.com>
Cc: John Stultz <jstultz@google.com>
Cc: "T.J. Mercier" <tjmercier@google.com>
Cc: "Christian König" <christian.koenig@amd.com>
Cc: dri-devel@lists.freedesktop.org
Cc: linaro-mm-sig@lists.linaro.org
Cc: linux-media@vger.kernel.org
Cc: linux-doc@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

Comments

T.J. Mercier Oct. 1, 2024, 9:03 p.m. UTC | #1 
On Mon, Sep 30, 2024 at 4:41 PM Maxime Ripard <mripard@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@kernel.org>
>
> ---
>
> To: Jonathan Corbet <corbet@lwn.net>
> To: Sumit Semwal <sumit.semwal@linaro.org>
> Cc: Benjamin Gaignard <benjamin.gaignard@collabora.com>
> Cc: Brian Starkey <Brian.Starkey@arm.com>
> Cc: John Stultz <jstultz@google.com>
> Cc: "T.J. Mercier" <tjmercier@google.com>
> Cc: "Christian König" <christian.koenig@amd.com>
> Cc: dri-devel@lists.freedesktop.org
> Cc: linaro-mm-sig@lists.linaro.org
> Cc: linux-media@vger.kernel.org
> Cc: linux-doc@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
>
diff mbox series

Patch

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
+following heaps:
+
+ - The ``system`` heap allocates virtually contiguous, cacheable, buffers
+
+ - 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``
+
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