From: Maxime Ripard Date: Mon, 28 Jul 2025 08:21:23 +0000 (+0200) Subject: Documentation: dma-buf: heaps: Add naming guidelines X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=507211e3c7a110c3f48cd8c731ddc748fe215ec8;p=thirdparty%2Fkernel%2Flinux.git Documentation: dma-buf: heaps: Add naming guidelines 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: Andrew Davis Reviewed-by: Bagas Sanjaya Signed-off-by: Maxime Ripard Link: https://lore.kernel.org/all/20250728-dma-buf-heap-names-doc-v4-1-f73f71cf0dfd@kernel.org/ Signed-off-by: Sumit Semwal --- diff --git a/Documentation/userspace-api/dma-buf-heaps.rst b/Documentation/userspace-api/dma-buf-heaps.rst index 1dfe5e7acd5a3..a0979440d2a42 100644 --- a/Documentation/userspace-api/dma-buf-heaps.rst +++ b/Documentation/userspace-api/dma-buf-heaps.rst @@ -26,3 +26,37 @@ following heaps: ``DMABUF_HEAPS_CMA_LEGACY`` Kconfig option is set, a duplicate node is created following legacy naming conventions; the legacy name might be ``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-contiguous`` or ``video@42000000``, but +``cma-video`` wouldn't.