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 <bagasdo...@gmail.com> > > > > Signed-off-by: Maxime Ripard <mrip...@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-ab31f7480...@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
signature.asc
Description: PGP signature
