[PATCH v3] Documentation: dma-buf: heaps: Add naming guidelines

[PATCH v3] Documentation: dma-buf: heaps: Add naming guidelines

[Maxime Ripard]

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.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Maxime Ripard <mripard@kernel.org>
---
Changes in v3:
- Grammar, spelling fixes
- Remove the cacheable / uncacheable name suggestion
- Link to v2: https://lore.kernel.org/r/20250616-dma-buf-heap-names-doc-v2-1-8ae43174cdbf@kernel.org

Changes in v2:
- Added justifications for each requirement / suggestions
- Added a mention and example of buffer attributes
- Link to v1: https://lore.kernel.org/r/20250520-dma-buf-heap-names-doc-v1-1-ab31f74809ee@kernel.org
---
 Documentation/userspace-api/dma-buf-heaps.rst | 35 +++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
index 535f49047ce6450796bf4380c989e109355efc05..3ee4e7961fe390ba356a2125d53b060546c3e4a6 100644
--- a/Documentation/userspace-api/dma-buf-heaps.rst
+++ b/Documentation/userspace-api/dma-buf-heaps.rst
@@ -21,5 +21,40 @@ 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
+=================
+
+``dma-buf`` heaps name should meet a number of constraints:
+
+- The name must be stable, and must not change from one version to the other.
+  Userspace identifies heaps by their name, so if the names ever change, we
+  would be likely to introduce regressions.
+
+- The name must describe the memory region the heap will allocate from, and
+  must uniquely identify it in a given platform. Since userspace applications
+  use the heap name as the discriminant, it must be able to tell which heap it
+  wants to use reliably if there's multiple heaps.
+
+- The name must not mention implementation details, such as the allocator. The
+  heap driver will change over time, and implementation details when it was
+  introduced might not be relevant in the future.
+
+- The name should describe properties of the buffers that would be allocated.
+  Doing so will make heap identification easier for userspace. Such properties
+  are:
+
+  - ``contiguous`` for physically contiguous buffers;
+
+  - ``protected`` for encrypted buffers not accessible the OS;
+
+- The name may describe intended usage. Doing so will make heap identification
+  easier for userspace applications and users.
+
+For example, assuming a platform with a reserved memory region located at the
+RAM address 0x42000000, intended to allocate video framebuffers, physically
+contiguous, and backed by the CMA kernel allocator, good names would be
+``memory@42000000-cacheable-contiguous`` or ``video@42000000``, but
+``cma-video`` wouldn't.

---
base-commit: 19272b37aa4f83ca52bdf9c16d5d81bdd1354494
change-id: 20250520-dma-buf-heap-names-doc-31261aa0cfe6

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

Re: [PATCH v3] Documentation: dma-buf: heaps: Add naming guidelines

[Andrew Davis]

On 7/17/25 3:10 AM, Maxime Ripard 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.
> 
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Signed-off-by: Maxime Ripard <mripard@kernel.org>
> ---
> Changes in v3:
> - Grammar, spelling fixes
> - Remove the cacheable / uncacheable name suggestion
> - Link to v2: https://lore.kernel.org/r/20250616-dma-buf-heap-names-doc-v2-1-8ae43174cdbf@kernel.org
> 
> Changes in v2:
> - Added justifications for each requirement / suggestions
> - Added a mention and example of buffer attributes
> - Link to v1: https://lore.kernel.org/r/20250520-dma-buf-heap-names-doc-v1-1-ab31f74809ee@kernel.org
> ---
>   Documentation/userspace-api/dma-buf-heaps.rst | 35 +++++++++++++++++++++++++++
>   1 file changed, 35 insertions(+)
> 
> diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
> index 535f49047ce6450796bf4380c989e109355efc05..3ee4e7961fe390ba356a2125d53b060546c3e4a6 100644
> --- a/Documentation/userspace-api/dma-buf-heaps.rst
> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> @@ -21,5 +21,40 @@ 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
> +=================
> +
> +``dma-buf`` heaps name should meet a number of constraints:
> +
> +- The name must be stable, and must not change from one version to the other.
> +  Userspace identifies heaps by their name, so if the names ever change, we
> +  would be likely to introduce regressions.
> +
> +- The name must describe the memory region the heap will allocate from, and
> +  must uniquely identify it in a given platform. Since userspace applications
> +  use the heap name as the discriminant, it must be able to tell which heap it
> +  wants to use reliably if there's multiple heaps.
> +
> +- The name must not mention implementation details, such as the allocator. The
> +  heap driver will change over time, and implementation details when it was
> +  introduced might not be relevant in the future.
> +
> +- The name should describe properties of the buffers that would be allocated.
> +  Doing so will make heap identification easier for userspace. Such properties
> +  are:
> +
> +  - ``contiguous`` for physically contiguous buffers;
> +
> +  - ``protected`` for encrypted buffers not accessible the OS;
> +
> +- The name may describe intended usage. Doing so will make heap identification
> +  easier for userspace applications and users.
> +
> +For example, assuming a platform with a reserved memory region located at the
> +RAM address 0x42000000, intended to allocate video framebuffers, physically
> +contiguous, and backed by the CMA kernel allocator, good names would be
> +``memory@42000000-cacheable-contiguous`` or ``video@42000000``, but

You dropped "cacheable" but left it here in the suggested names, maybe
replace with "protected" here. Otherwise, LGTM,

Reviewed-by: Andrew Davis <afd@ti.com>

> +``cma-video`` wouldn't.
> 
> ---
> base-commit: 19272b37aa4f83ca52bdf9c16d5d81bdd1354494
> change-id: 20250520-dma-buf-heap-names-doc-31261aa0cfe6
> 
> Best regards,

Re: [PATCH v3] Documentation: dma-buf: heaps: Add naming guidelines

[Maxime Ripard]

[-- Attachment #1: Type: text/plain, Size: 3920 bytes --]

Hi Andrew,

Thanks for your review.

On Fri, Jul 25, 2025 at 12:49:37PM -0500, Andrew Davis wrote:
> On 7/17/25 3:10 AM, Maxime Ripard 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.
> > 
> > Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > Signed-off-by: Maxime Ripard <mripard@kernel.org>
> > ---
> > Changes in v3:
> > - Grammar, spelling fixes
> > - Remove the cacheable / uncacheable name suggestion
> > - Link to v2: https://lore.kernel.org/r/20250616-dma-buf-heap-names-doc-v2-1-8ae43174cdbf@kernel.org
> > 
> > Changes in v2:
> > - Added justifications for each requirement / suggestions
> > - Added a mention and example of buffer attributes
> > - Link to v1: https://lore.kernel.org/r/20250520-dma-buf-heap-names-doc-v1-1-ab31f74809ee@kernel.org
> > ---
> >   Documentation/userspace-api/dma-buf-heaps.rst | 35 +++++++++++++++++++++++++++
> >   1 file changed, 35 insertions(+)
> > 
> > diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
> > index 535f49047ce6450796bf4380c989e109355efc05..3ee4e7961fe390ba356a2125d53b060546c3e4a6 100644
> > --- a/Documentation/userspace-api/dma-buf-heaps.rst
> > +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> > @@ -21,5 +21,40 @@ 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
> > +=================
> > +
> > +``dma-buf`` heaps name should meet a number of constraints:
> > +
> > +- The name must be stable, and must not change from one version to the other.
> > +  Userspace identifies heaps by their name, so if the names ever change, we
> > +  would be likely to introduce regressions.
> > +
> > +- The name must describe the memory region the heap will allocate from, and
> > +  must uniquely identify it in a given platform. Since userspace applications
> > +  use the heap name as the discriminant, it must be able to tell which heap it
> > +  wants to use reliably if there's multiple heaps.
> > +
> > +- The name must not mention implementation details, such as the allocator. The
> > +  heap driver will change over time, and implementation details when it was
> > +  introduced might not be relevant in the future.
> > +
> > +- The name should describe properties of the buffers that would be allocated.
> > +  Doing so will make heap identification easier for userspace. Such properties
> > +  are:
> > +
> > +  - ``contiguous`` for physically contiguous buffers;
> > +
> > +  - ``protected`` for encrypted buffers not accessible the OS;
> > +
> > +- The name may describe intended usage. Doing so will make heap identification
> > +  easier for userspace applications and users.
> > +
> > +For example, assuming a platform with a reserved memory region located at the
> > +RAM address 0x42000000, intended to allocate video framebuffers, physically
> > +contiguous, and backed by the CMA kernel allocator, good names would be
> > +``memory@42000000-cacheable-contiguous`` or ``video@42000000``, but
> 
> You dropped "cacheable" but left it here in the suggested names, maybe
> replace with "protected" here. Otherwise, LGTM,

Replacing it with protected would create an example where we have CMA
allocating protected buffers, which is pretty weird.

So I've only removed the cacheable mention, and will send a new version
shortly.

> Reviewed-by: Andrew Davis <afd@ti.com>

Thanks!
Maxime

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 273 bytes --]