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

Mon Oct 21 16:30:15 UTC 2024

Hi TJ,

Thanks for your review

On Tue, Oct 01, 2024 at 11:03:41PM +0200, T.J. Mercier wrote:
> 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...

Yeah, I don't know.

It's getting philosophical, but I guess there's an infinite number of
guarantees we wouldn't provide. It seems easier for me to maintain a
list of the things a buffer is/has rather than the opposite.

But maybe we can rephrase virtually contiguous if it's weird to you?

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

Really? My understanding was that you need a default CMA region, which
happens either if you have cma= on the kernel command line, a default
CMA pool in the DT, or if CMA_SIZE_MBYTES isn't set to 0?

Maxime
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 273 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20241021/99f831d2/attachment.sig>