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,
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
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
linaro-mm-sig@lists.linaro.org
-
Bagas Sanjaya -
John Stultz -
Maxime Ripard