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

[PATCH v2] 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 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 | 38 +++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
index 535f49047ce6450796bf4380c989e109355efc05..835ad1c3a65bc07b6f41d387d85c57162909e859 100644
--- a/Documentation/userspace-api/dma-buf-heaps.rst
+++ b/Documentation/userspace-api/dma-buf-heaps.rst
@@ -21,5 +21,43 @@ 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:
+
+- That 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
+  changes, we would be likely to introduce regressions.
+
+- That 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.
+
+- That 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:
+
+  - ``cacheable`` / ``uncacheable`` for buffers with CPU caches enabled
+    or disabled;
+
+  - ``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 v2] Documentation: dma-buf: heaps: Add naming guidelines

[Randy Dunlap]

On 6/16/25 8:21 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 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 | 38 +++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
> 
> diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
> index 535f49047ce6450796bf4380c989e109355efc05..835ad1c3a65bc07b6f41d387d85c57162909e859 100644
> --- a/Documentation/userspace-api/dma-buf-heaps.rst
> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> @@ -21,5 +21,43 @@ 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:
> +

For these points below, I would s/That name/The name/ (3 places).

> +- That 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
> +  changes, we would be likely to introduce regressions.

     change,

> +
> +- That 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.

                                              if there are

> +
> +- That 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:
> +
> +  - ``cacheable`` / ``uncacheable`` for buffers with CPU caches enabled
> +    or disabled;
> +
> +  - ``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

   ^^^ Not a complete sentence. Change '.' to ',':     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,

-- 
~Randy

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

[Andrew Davis]

On 6/16/25 10:21 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 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 | 38 +++++++++++++++++++++++++++
>   1 file changed, 38 insertions(+)
> 
> diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
> index 535f49047ce6450796bf4380c989e109355efc05..835ad1c3a65bc07b6f41d387d85c57162909e859 100644
> --- a/Documentation/userspace-api/dma-buf-heaps.rst
> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> @@ -21,5 +21,43 @@ 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:
> +
> +- That 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
> +  changes, we would be likely to introduce regressions.
> +
> +- That 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.
> +
> +- That 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:
> +
> +  - ``cacheable`` / ``uncacheable`` for buffers with CPU caches enabled
> +    or disabled;
> +

We should avoid exposing cacheability to userspace. What users care about
is if writes are readable by the other side (and vice versa) without SYNC
operations in-between. This property is "coherency". Being non-cached
is just one way to achieve coherency on some systems. For many systems
even cached buffers are still coherent and manually specifying "non-cached"
causes unneeded performance issues.

DMA-BUFs are default assumed to be non-coherent and sync operations should
be always be performed (if the buffer is actually coherent these operations
are turned into NOPs and no harm done). If sync operations cannot be done
(for instance small multi-writer ring-buffers), then the property can
be simply:

- ``coherent`` for buffers which do not require sync operations

Andrew

> +  - ``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,

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

[Maxime Ripard]

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

On Wed, Jul 09, 2025 at 12:39:15PM -0500, Andrew Davis wrote:
> On 6/16/25 10:21 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 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 | 38 +++++++++++++++++++++++++++
> >   1 file changed, 38 insertions(+)
> > 
> > diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
> > index 535f49047ce6450796bf4380c989e109355efc05..835ad1c3a65bc07b6f41d387d85c57162909e859 100644
> > --- a/Documentation/userspace-api/dma-buf-heaps.rst
> > +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> > @@ -21,5 +21,43 @@ 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:
> > +
> > +- That 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
> > +  changes, we would be likely to introduce regressions.
> > +
> > +- That 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.
> > +
> > +- That 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:
> > +
> > +  - ``cacheable`` / ``uncacheable`` for buffers with CPU caches enabled
> > +    or disabled;
> > +
> 
> We should avoid exposing cacheability to userspace. What users care about
> is if writes are readable by the other side (and vice versa) without SYNC
> operations in-between. This property is "coherency". Being non-cached
> is just one way to achieve coherency on some systems. For many systems
> even cached buffers are still coherent and manually specifying "non-cached"
> causes unneeded performance issues.

I disagree. If you want to do any kind of software rendering, the
buffers being cached is absolutely critical to having decent
performance.

> DMA-BUFs are default assumed to be non-coherent and sync operations should
> be always be performed (if the buffer is actually coherent these operations
> are turned into NOPs and no harm done). If sync operations cannot be done
> (for instance small multi-writer ring-buffers), then the property can
> be simply:
> 
> - ``coherent`` for buffers which do not require sync operations

That would be a change in the uAPI which, so far, requires sync
operations to be performed. I'm not necessarily agaisnt it, but handling
coherency in general is not what this patch is about.

Maxime

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

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

[Andrew Davis]

On 7/10/25 2:06 AM, Maxime Ripard wrote:
> On Wed, Jul 09, 2025 at 12:39:15PM -0500, Andrew Davis wrote:
>> On 6/16/25 10:21 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 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 | 38 +++++++++++++++++++++++++++
>>>    1 file changed, 38 insertions(+)
>>>
>>> diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
>>> index 535f49047ce6450796bf4380c989e109355efc05..835ad1c3a65bc07b6f41d387d85c57162909e859 100644
>>> --- a/Documentation/userspace-api/dma-buf-heaps.rst
>>> +++ b/Documentation/userspace-api/dma-buf-heaps.rst
>>> @@ -21,5 +21,43 @@ 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:
>>> +
>>> +- That 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
>>> +  changes, we would be likely to introduce regressions.
>>> +
>>> +- That 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.
>>> +
>>> +- That 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:
>>> +
>>> +  - ``cacheable`` / ``uncacheable`` for buffers with CPU caches enabled
>>> +    or disabled;
>>> +
>>
>> We should avoid exposing cacheability to userspace. What users care about
>> is if writes are readable by the other side (and vice versa) without SYNC
>> operations in-between. This property is "coherency". Being non-cached
>> is just one way to achieve coherency on some systems. For many systems
>> even cached buffers are still coherent and manually specifying "non-cached"
>> causes unneeded performance issues.
> 
> I disagree. If you want to do any kind of software rendering, the
> buffers being cached is absolutely critical to having decent
> performance.
> 

I think we are saying the same thing, the default should be cached.
If the user doesn't have an option for specifying "non-cached" then
they will always get the better performing cached buffers.

>> DMA-BUFs are default assumed to be non-coherent and sync operations should
>> be always be performed (if the buffer is actually coherent these operations
>> are turned into NOPs and no harm done). If sync operations cannot be done
>> (for instance small multi-writer ring-buffers), then the property can
>> be simply:
>>
>> - ``coherent`` for buffers which do not require sync operations
> 
> That would be a change in the uAPI which, so far, requires sync
> operations to be performed. I'm not necessarily agaisnt it, but handling
> coherency in general is not what this patch is about.

Agree, so then let's just drop the line about cacheable/coherent from
this doc, we can deal with those properties and document them when/if
they are ever needed.

Andrew

> 
> Maxime

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

[Maxime Ripard]

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

On Thu, Jul 10, 2025 at 09:34:12AM -0500, Andrew Davis wrote:
> On 7/10/25 2:06 AM, Maxime Ripard wrote:
> > On Wed, Jul 09, 2025 at 12:39:15PM -0500, Andrew Davis wrote:
> > > On 6/16/25 10:21 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 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 | 38 +++++++++++++++++++++++++++
> > > >    1 file changed, 38 insertions(+)
> > > > 
> > > > diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst
> > > > index 535f49047ce6450796bf4380c989e109355efc05..835ad1c3a65bc07b6f41d387d85c57162909e859 100644
> > > > --- a/Documentation/userspace-api/dma-buf-heaps.rst
> > > > +++ b/Documentation/userspace-api/dma-buf-heaps.rst
> > > > @@ -21,5 +21,43 @@ 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:
> > > > +
> > > > +- That 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
> > > > +  changes, we would be likely to introduce regressions.
> > > > +
> > > > +- That 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.
> > > > +
> > > > +- That 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:
> > > > +
> > > > +  - ``cacheable`` / ``uncacheable`` for buffers with CPU caches enabled
> > > > +    or disabled;
> > > > +
> > > 
> > > We should avoid exposing cacheability to userspace. What users care about
> > > is if writes are readable by the other side (and vice versa) without SYNC
> > > operations in-between. This property is "coherency". Being non-cached
> > > is just one way to achieve coherency on some systems. For many systems
> > > even cached buffers are still coherent and manually specifying "non-cached"
> > > causes unneeded performance issues.
> > 
> > I disagree. If you want to do any kind of software rendering, the
> > buffers being cached is absolutely critical to having decent
> > performance.
> > 
> 
> I think we are saying the same thing, the default should be cached.
> If the user doesn't have an option for specifying "non-cached" then
> they will always get the better performing cached buffers.

Oh, I see what you mean now. Yeah, I agree. I'll drop that part from the
doc then.

Maxime

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