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@kernel.org>
---
 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.
+
+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.

---
base-commit: 92a09c47464d040866cf2b4cd052bc60555185fb
change-id: 20250520-dma-buf-heap-names-doc-31261aa0cfe6

Best regards,
-- 
Maxime Ripard <mripard@kernel.org>

On Tue, May 20, 2025 at 3:00 AM Maxime Ripard <mripard@kernel.org> 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@kernel.org>
> ---
>  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 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.

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

thanks
-john

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@kernel.org> 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@kernel.org>
> > ---
> >  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

On Tue, May 20, 2025 at 12:00:53PM +0200, Maxime Ripard wrote:
> +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.
> +
> +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.

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara