linux-kernel - Re: [PATCH v4] Documentation: dma-buf: heaps: Add naming guidelines

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CAO_48GHsteXa9vu5n8FyuWYGOK7yMBhz3ppQeO=CtxTdcM+K8g@mail.gmail.com>
Date: Wed, 10 Sep 2025 11:40:11 +0530
From: Sumit Semwal <sumit.semwal@...aro.org>
To: Maxime Ripard <mripard@...nel.org>
Cc: Benjamin Gaignard <benjamin.gaignard@...labora.com>, Brian Starkey <Brian.Starkey@....com>, 
	John Stultz <jstultz@...gle.com>, "T.J. Mercier" <tjmercier@...gle.com>, 
	Jonathan Corbet <corbet@....net>, Andrew Davis <afd@...com>, Jared Kangas <jkangas@...hat.com>, 
	Mattijs Korpershoek <mkorpershoek@...nel.org>, linux-media@...r.kernel.org, 
	dri-devel@...ts.freedesktop.org, linaro-mm-sig@...ts.linaro.org, 
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, 
	Bagas Sanjaya <bagasdotme@...il.com>
Subject: Re: [PATCH v4] Documentation: dma-buf: heaps: Add naming guidelines

Hello Maxime,


On Mon, 28 Jul 2025 at 13:51, Maxime Ripard <mripard@...nel.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.
Thank you for the patch. In principle, I'm ok to take this patch, with
the obvious understanding that if there are future heap name
requirements that can't be satisfied with these rules, we will discuss
and adapt the rules accordingly.

I hope this sounds reasonable to all.

If I don't hear any objections, I'll merge this by this weekend.
>
> Reviewed-by: Andrew Davis <afd@...com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@...il.com>
> Signed-off-by: Maxime Ripard <mripard@...nel.org>

Best.
Sumit.

> ---
> Changes in v4:
> - Dropped *all* the cacheable mentions
> - Link to v3: https://lore.kernel.org/r/20250717-dma-buf-heap-names-doc-v3-1-d2dbb4b95ef6@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..1ced2720f929432661182f1a3a88aa1ff80bd6af 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@...00000-contiguous`` or ``video@...00000``, but
> +``cma-video`` wouldn't.
>
> ---
> base-commit: 038d61fd642278bab63ee8ef722c50d10ab01e8f
> change-id: 20250520-dma-buf-heap-names-doc-31261aa0cfe6
>
> Best regards,
> --
> Maxime Ripard <mripard@...nel.org>
>


-- 
Thanks and regards,

Sumit Semwal (he / him)
Senior Tech Lead - Android, Platforms and Virtualisation
Linaro.org │ Arm Solutions at Light Speed