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@...
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