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

Maxime Ripard mripard at kernel.org
Thu Jul 10 15:12:37 UTC 2025


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 at gmail.com>
> > > > Signed-off-by: Maxime Ripard <mripard at 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 273 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20250710/ee0f7e5d/attachment.sig>


More information about the dri-devel mailing list