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

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

[Maxime Ripard]

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>

---
Changes from v1:
  - Add the mention that the cma / reserved heap is optional.

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 | 76 +++++++++++++++++++
 Documentation/userspace-api/index.rst         |  1 +
 2 files changed, 77 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..68be7ddea150
--- /dev/null
+++ b/Documentation/userspace-api/dma-buf-heaps.rst
@@ -0,0 +1,76 @@
+.. 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. 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 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
-- 
2.47.1

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

[John Stultz]

On Mon, Dec 2, 2024 at 3:58 AM 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.
>
> Signed-off-by: Maxime Ripard <mripard@kernel.org>
>
> ---
> Changes from v1:
>   - Add the mention that the cma / reserved heap is optional.
>
> 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 | 76 +++++++++++++++++++
>  Documentation/userspace-api/index.rst         |  1 +
>  2 files changed, 77 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..68be7ddea150
> --- /dev/null
> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> @@ -0,0 +1,76 @@
> +.. 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,

So, I think calling the heap name the "cma" heap might be clearer here?
On some platforms the chardev is "reserved" because the default cma
region is setup via dma_contiguous_reserve_area() (which calls it
"reserved"), but the dma heap is exporting cma.

Additionally, on some downstream devices there can be multiple purpose
separated CMA heaps. This hasn't made it upstream over objections to
how downstream devices were enumerating the separate cma regions in
their devicetrees. It was proposed to export all cma regions as
separate cma heaps, but there was reasonable concern over kernel
drivers not expecting userland to be able to allocate from special
reservations, so that seemed like a bad idea.

Ideally upstream drivers would want to explicitly export their special
CMA region themselves and we would export something like
add_cma_heap() to do so.

All to say: this document really only covers the naming of the
"default" CMA region that is exported via the cma heap.  Eventually
there may be other CMA heaps as well upstream.

> +   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 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``
>

Hrm. I'm not sure I see the value in enumerating things in this way,
it seems like it will be a nuisance to keep current?  Maybe something
like:

On most systems the default cma region is named "linux, cma" or
"reserved", with a few exceptions:
    - Allwinner sun4i, sun5i and sun7i families: ``default-pool``

thanks
-john

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

[Maxime Ripard]

[-- Attachment #1: Type: text/plain, Size: 7408 bytes --]

Hi John,

On Mon, Dec 02, 2024 at 11:12:23AM -0800, John Stultz wrote:
> On Mon, Dec 2, 2024 at 3:58 AM 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.
> >
> > Signed-off-by: Maxime Ripard <mripard@kernel.org>
> >
> > ---
> > Changes from v1:
> >   - Add the mention that the cma / reserved heap is optional.
> >
> > 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 | 76 +++++++++++++++++++
> >  Documentation/userspace-api/index.rst         |  1 +
> >  2 files changed, 77 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..68be7ddea150
> > --- /dev/null
> > +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> > @@ -0,0 +1,76 @@
> > +.. 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,
> 
> So, I think calling the heap name the "cma" heap might be clearer here?
> On some platforms the chardev is "reserved" because the default cma
> region is setup via dma_contiguous_reserve_area() (which calls it
> "reserved"), but the dma heap is exporting cma.

Ok, I'll change it

> Additionally, on some downstream devices there can be multiple purpose
> separated CMA heaps. This hasn't made it upstream over objections to
> how downstream devices were enumerating the separate cma regions in
> their devicetrees. It was proposed to export all cma regions as
> separate cma heaps, but there was reasonable concern over kernel
> drivers not expecting userland to be able to allocate from special
> reservations, so that seemed like a bad idea.
> 
> Ideally upstream drivers would want to explicitly export their special
> CMA region themselves and we would export something like
> add_cma_heap() to do so.
> 
> All to say: this document really only covers the naming of the
> "default" CMA region that is exported via the cma heap.  Eventually
> there may be other CMA heaps as well upstream.

Sure. My point was to follow-up on the discussion we had at Plumbers
that concluded by something along the lines of: heap names provide the
semantics and guarantee over how buffers are allocated, and thus we need
to document what each name is providing.

If we were to add new ones, we would obviously extend that list to
accomodate those changes.

> > +   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 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``
> >
> 
> Hrm. I'm not sure I see the value in enumerating things in this way,
> it seems like it will be a nuisance to keep current?  Maybe something
> like:
> 
> On most systems the default cma region is named "linux, cma" or
> "reserved", with a few exceptions:
>     - Allwinner sun4i, sun5i and sun7i families: ``default-pool``

I'm a bit worried about doing so. What if, on a "linux,cma" system, we
have another "reserved" heap created with different semantics?

Maxime

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 273 bytes --]

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

[Andrew Davis]

On 12/3/24 1:44 AM, Maxime Ripard wrote:
> Hi John,
> 
> On Mon, Dec 02, 2024 at 11:12:23AM -0800, John Stultz wrote:
>> On Mon, Dec 2, 2024 at 3:58 AM 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.
>>>
>>> Signed-off-by: Maxime Ripard <mripard@kernel.org>
>>>
>>> ---
>>> Changes from v1:
>>>    - Add the mention that the cma / reserved heap is optional.
>>>
>>> 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 | 76 +++++++++++++++++++
>>>   Documentation/userspace-api/index.rst         |  1 +
>>>   2 files changed, 77 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..68be7ddea150
>>> --- /dev/null
>>> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
>>> @@ -0,0 +1,76 @@
>>> +.. 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,
>>
>> So, I think calling the heap name the "cma" heap might be clearer here?
>> On some platforms the chardev is "reserved" because the default cma
>> region is setup via dma_contiguous_reserve_area() (which calls it
>> "reserved"), but the dma heap is exporting cma.
> 
> Ok, I'll change it
> 
>> Additionally, on some downstream devices there can be multiple purpose
>> separated CMA heaps. This hasn't made it upstream over objections to
>> how downstream devices were enumerating the separate cma regions in
>> their devicetrees. It was proposed to export all cma regions as
>> separate cma heaps, but there was reasonable concern over kernel
>> drivers not expecting userland to be able to allocate from special
>> reservations, so that seemed like a bad idea.
>>
>> Ideally upstream drivers would want to explicitly export their special
>> CMA region themselves and we would export something like
>> add_cma_heap() to do so.
>>
>> All to say: this document really only covers the naming of the
>> "default" CMA region that is exported via the cma heap.  Eventually
>> there may be other CMA heaps as well upstream.
> 
> Sure. My point was to follow-up on the discussion we had at Plumbers
> that concluded by something along the lines of: heap names provide the
> semantics and guarantee over how buffers are allocated, and thus we need
> to document what each name is providing.
> 
> If we were to add new ones, we would obviously extend that list to
> accomodate those changes.
> 
>>> +   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 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``
>>>
>>
>> Hrm. I'm not sure I see the value in enumerating things in this way,
>> it seems like it will be a nuisance to keep current?  Maybe something
>> like:
>>
>> On most systems the default cma region is named "linux, cma" or
>> "reserved", with a few exceptions:
>>      - Allwinner sun4i, sun5i and sun7i families: ``default-pool``
> 
> I'm a bit worried about doing so. What if, on a "linux,cma" system, we
> have another "reserved" heap created with different semantics?
> 

Having the "default CMA" heap get its dev name based on the method that
created it was arguably a mistake made when first upstreaming this heap.
We should fix this, then maybe add the old name as a link just for
backwards compat as needed.

exp_info.name = "default_cma";

All other CMA and carveout heaps will have names based on their
method of creation as there may be multiple of them, but there
will only every be one "default CMA" area, and its heap should
be named to match.

Andrew

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

[John Stultz]

On Tue, Dec 3, 2024 at 11:04 AM Andrew Davis <afd@ti.com> wrote:
> On 12/3/24 1:44 AM, Maxime Ripard wrote:
> > On Mon, Dec 02, 2024 at 11:12:23AM -0800, John Stultz wrote:
> >> Hrm. I'm not sure I see the value in enumerating things in this way,
> >> it seems like it will be a nuisance to keep current?  Maybe something
> >> like:
> >>
> >> On most systems the default cma region is named "linux, cma" or
> >> "reserved", with a few exceptions:
> >>      - Allwinner sun4i, sun5i and sun7i families: ``default-pool``
> >
> > I'm a bit worried about doing so. What if, on a "linux,cma" system, we
> > have another "reserved" heap created with different semantics?
> >
>
> Having the "default CMA" heap get its dev name based on the method that
> created it was arguably a mistake made when first upstreaming this heap.
> We should fix this, then maybe add the old name as a link just for
> backwards compat as needed.
>
> exp_info.name = "default_cma";
>
> All other CMA and carveout heaps will have names based on their
> method of creation as there may be multiple of them, but there
> will only every be one "default CMA" area, and its heap should
> be named to match.

This seems reasonable to me. Maybe putting the link creation behind a
compatibility config so they can be later deprecated?

That said, while I understand the impulse to want to fix the heap
names so applications can depend on them, I also want to caution it's
a little bit like trying to hard code eth0 as a network device name in
your scripts.  There are too many potential configurations, and any
fixed mapping is going to break in some cases.  I think there is just
going to have to be some (gralloc-like) device-specific configuration
glue to map a pipeline/use-case to the memory type (similar to fstab
for filesystem to mount points) in order to handle every case.

So if I'm being a little squirrely on fixed names, it's mostly due to
wanting to avoid anyone getting the mistaken impression that fixed
mappings will generally work.

thanks
-john

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

[Maxime Ripard]

[-- Attachment #1: Type: text/plain, Size: 2885 bytes --]

On Thu, Dec 05, 2024 at 03:17:57PM -0800, John Stultz wrote:
> On Tue, Dec 3, 2024 at 11:04 AM Andrew Davis <afd@ti.com> wrote:
> > On 12/3/24 1:44 AM, Maxime Ripard wrote:
> > > On Mon, Dec 02, 2024 at 11:12:23AM -0800, John Stultz wrote:
> > >> Hrm. I'm not sure I see the value in enumerating things in this way,
> > >> it seems like it will be a nuisance to keep current?  Maybe something
> > >> like:
> > >>
> > >> On most systems the default cma region is named "linux, cma" or
> > >> "reserved", with a few exceptions:
> > >>      - Allwinner sun4i, sun5i and sun7i families: ``default-pool``
> > >
> > > I'm a bit worried about doing so. What if, on a "linux,cma" system, we
> > > have another "reserved" heap created with different semantics?
> > >
> >
> > Having the "default CMA" heap get its dev name based on the method that
> > created it was arguably a mistake made when first upstreaming this heap.
> > We should fix this, then maybe add the old name as a link just for
> > backwards compat as needed.
> >
> > exp_info.name = "default_cma";
> >
> > All other CMA and carveout heaps will have names based on their
> > method of creation as there may be multiple of them, but there
> > will only every be one "default CMA" area, and its heap should
> > be named to match.
> 
> This seems reasonable to me. Maybe putting the link creation behind a
> compatibility config so they can be later deprecated?

That sounds reasonable to me too. However, I'm not sure how to create a
symlink in devtmpfs from the kernel. Or maybe we should create a second
device file with the same major / minor?

> That said, while I understand the impulse to want to fix the heap
> names so applications can depend on them, I also want to caution it's
> a little bit like trying to hard code eth0 as a network device name in
> your scripts.  There are too many potential configurations, and any
> fixed mapping is going to break in some cases.

I certainly don't want to spark *that* discussion again, but it's
exactly why I wasn't convinced about the names providing the guarantees
back in Plumbers. I definitely agree with you there that the situation
is kind of messy already, and it will only get worse.

It will be really hard to document, and if we can't document it,
userspace can't rely on guarantees either.

> I think there is just going to have to be some (gralloc-like)
> device-specific configuration glue to map a pipeline/use-case to the
> memory type (similar to fstab for filesystem to mount points) in order
> to handle every case.

That might work for Android, but it really doesn't for anything more
generic than that.

> So if I'm being a little squirrely on fixed names, it's mostly due to
> wanting to avoid anyone getting the mistaken impression that fixed
> mappings will generally work.

Ack :)
Maxime

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 273 bytes --]

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

[Maxime Ripard]

[-- Attachment #1: Type: text/plain, Size: 1953 bytes --]

Hi,

On Thu, Dec 05, 2024 at 03:17:57PM -0800, John Stultz wrote:
> On Tue, Dec 3, 2024 at 11:04 AM Andrew Davis <afd@ti.com> wrote:
> > On 12/3/24 1:44 AM, Maxime Ripard wrote:
> > > On Mon, Dec 02, 2024 at 11:12:23AM -0800, John Stultz wrote:
> > >> Hrm. I'm not sure I see the value in enumerating things in this way,
> > >> it seems like it will be a nuisance to keep current?  Maybe something
> > >> like:
> > >>
> > >> On most systems the default cma region is named "linux, cma" or
> > >> "reserved", with a few exceptions:
> > >>      - Allwinner sun4i, sun5i and sun7i families: ``default-pool``
> > >
> > > I'm a bit worried about doing so. What if, on a "linux,cma" system, we
> > > have another "reserved" heap created with different semantics?
> > >
> >
> > Having the "default CMA" heap get its dev name based on the method that
> > created it was arguably a mistake made when first upstreaming this heap.
> > We should fix this, then maybe add the old name as a link just for
> > backwards compat as needed.
> >
> > exp_info.name = "default_cma";
> >
> > All other CMA and carveout heaps will have names based on their
> > method of creation as there may be multiple of them, but there
> > will only every be one "default CMA" area, and its heap should
> > be named to match.
> 
> This seems reasonable to me. Maybe putting the link creation behind a
> compatibility config so they can be later deprecated?

I gave it a look, and while I'm not super experienced with fs in
general, it looks like there's no easy way to create a symbolic link
in devtmpfs from the kernel.

I also tried to cheat a little and create another device file with the
same major/minor, but that doesn't look trivial to me either.

Do you know how to do so, or are aware of any other part of the kernel
doing something similar?

Most importantly, do you consider it a requirement before merging that
patch?

Maxime

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 273 bytes --]