On Tue, May 20, 2025 at 07:46:39PM -0700, John Stultz wrote: > On Tue, May 20, 2025 at 3:00 AM Maxime Ripard <mripard@xxxxxxxxxx> wrote: > > > > We've discussed a number of times of how some heap names are bad, but > > not really what makes a good heap name. > > > > Let's document what we expect the heap names to look like. > > > > Signed-off-by: Maxime Ripard <mripard@xxxxxxxxxx> > > --- > > Documentation/userspace-api/dma-buf-heaps.rst | 19 +++++++++++++++++++ > > 1 file changed, 19 insertions(+) > > > > diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst > > index 535f49047ce6450796bf4380c989e109355efc05..b24618e360a9a9ba0bd85135d8c1760776f1a37f 100644 > > --- a/Documentation/userspace-api/dma-buf-heaps.rst > > +++ b/Documentation/userspace-api/dma-buf-heaps.rst > > @@ -21,5 +21,24 @@ following heaps: > > 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 ``reserved``, ``linux,cma``, or ``default-pool``. > > + > > +Naming Convention > > +================= > > + > > +A good heap name is a name that: > > + > > +- Is stable, and won't change from one version to the other; > > + > > +- Describes the memory region the heap will allocate from, and will > > + uniquely identify it in a given platform; > > + > > +- Doesn't use implementation details, such as the allocator; > > + > > +- Can describe intended usage. > > + > > Thanks again for sending this out. Sorry I've been spotty in some of > the discussions (I'm really trying to step back from this area). I wasn't aware, so sorry I keep dragging you into it :) I guess it's in part due to the historical background, but also because you've been the only one who answer consistently. I wonder though, do you need help with the maintenance? We plan to rely a fair bit on dma-buf heaps to implement cgroup device memory accounting, so I'd be happy to help if I can. > I might only suggest you provide a bit more "why" to the list of > qualities you highlight here, just to communicate more of the > spirit/philosophy of how these might be judged or reviewed in the > future. Ack, I'll do it in the next version. > > +For example, assuming a platform with a reserved memory region located > > +at the RAM address 0x42000000, intended to allocate video framebuffers, > > +and backed by the CMA kernel allocator. Good names would be > > +`memory@42000000` or `video@42000000`, but `cma-video` wouldn't. > > The point about avoiding the allocator details, just so I better > understand the criteria: Would distinguishing from a contiguous pool > vs non-contiguous in the name be considered ok? As it's a property of > the buffer returned, and one that is critically important for some > devices. Or do you intend that to be opaque, and the usage->heap > mapping logic to provide that itself? (Effectively avoiding folks from > being able to make potentially problematic assumptions from the name?) > > Similarly, how would you suggest naming a heap that provides 32bit > allocations? Similarly for "protected' allocations, which are being > proposed? I'll also add a section about that. Thanks for the review! Maxime
Attachment:
signature.asc
Description: PGP signature
