On Mon, Sep 30, 2024 at 4:41 PM Maxime Ripard <mripard@xxxxxxxxxx> 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@xxxxxxxxxx> > > --- > > To: Jonathan Corbet <corbet@xxxxxxx> > To: Sumit Semwal <sumit.semwal@xxxxxxxxxx> > Cc: Benjamin Gaignard <benjamin.gaignard@xxxxxxxxxxxxx> > Cc: Brian Starkey <Brian.Starkey@xxxxxxx> > Cc: John Stultz <jstultz@xxxxxxxxxx> > Cc: "T.J. Mercier" <tjmercier@xxxxxxxxxx> > Cc: "Christian König" <christian.koenig@xxxxxxx> > Cc: dri-devel@xxxxxxxxxxxxxxxxxxxxx > Cc: linaro-mm-sig@xxxxxxxxxxxxxxxx > Cc: linux-media@xxxxxxxxxxxxxxx > Cc: linux-doc@xxxxxxxxxxxxxxx > --- > 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 >
