Heaps¶

A heap represents a specific allocator. The Linux kernel currently supports thefollowing heaps:

• Thesystem heap allocates virtually contiguous, cacheable, buffers.

• Thedefault_cma_region heap allocates physically contiguous,cacheable, buffers. Only present if a CMA region is present. Such aregion is usually created either through the kernel commandlinethrough thecma parameter, a memory region Device-Tree node withthelinux,cma-default property set, or through theCMA_SIZE_MBYTES orCMA_SIZE_PERCENTAGE Kconfig options. Priorto Linux 6.17, its name wasn’t stable and could be calledreserved,linux,cma, ordefault-pool, depending on theplatform.

• A heap will be created for each reusable region in the device treewith theshared-dma-pool compatible, using the full device treenode name as its name. The buffer semantics are identical todefault-cma-region.

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, wewould be likely to introduce regressions.

• The name must describe the memory region the heap will allocate from, andmust uniquely identify it in a given platform. Since userspace applicationsuse the heap name as the discriminant, it must be able to tell which heap itwants to use reliably if there’s multiple heaps.

• The name must not mention implementation details, such as the allocator. Theheap driver will change over time, and implementation details when it wasintroduced 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 propertiesare:

  • contiguous for physically contiguous buffers;

  • protected for encrypted buffers not accessible the OS;

• The name may describe intended usage. Doing so will make heap identificationeasier for userspace applications and users.

For example, assuming a platform with a reserved memory region locatedat the RAM address 0x42000000, intended to allocate video framebuffers,physically contiguous, and backed by the CMA kernel allocator, goodnames would bememory@42000000-contiguous orvideo@42000000, butcma-video wouldn’t.