On Mon, Oct 21, 2024 at 9:30 AM Maxime Ripard <mripard@xxxxxxxxxx> wrote: > > 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@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... > > 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? You're right, I'm being too picky here. Virtually contiguous is as reasonable as anything else I can come up with. > > > + > > > + - 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? Ok yes, these too. :) > > Maxime
