1.. SPDX-License-Identifier: GPL-2.0 2 3============================== 4Allocating dma-buf using heaps 5============================== 6 7Dma-buf Heaps are a way for userspace to allocate dma-buf objects. They are 8typically used to allocate buffers from a specific allocation pool, or to share 9buffers across frameworks. 10 11Heaps 12===== 13 14A heap represents a specific allocator. The Linux kernel currently supports the 15following heaps: 16 17 - The ``system`` heap allocates virtually contiguous, cacheable, buffers. 18 19 - The ``cma`` heap allocates physically contiguous, cacheable, 20 buffers. Only present if a CMA region is present. Such a region is 21 usually created either through the kernel commandline through the 22 ``cma`` parameter, a memory region Device-Tree node with the 23 ``linux,cma-default`` property set, or through the ``CMA_SIZE_MBYTES`` or 24 ``CMA_SIZE_PERCENTAGE`` Kconfig options. The heap's name in devtmpfs is 25 ``default_cma_region``. For backwards compatibility, when the 26 ``DMABUF_HEAPS_CMA_LEGACY`` Kconfig option is set, a duplicate node is 27 created following legacy naming conventions; the legacy name might be 28 ``reserved``, ``linux,cma``, or ``default-pool``. 29Naming Convention 30================= 31 32``dma-buf`` heaps name should meet a number of constraints: 33 34- The name must be stable, and must not change from one version to the other. 35 Userspace identifies heaps by their name, so if the names ever change, we 36 would be likely to introduce regressions. 37 38- The name must describe the memory region the heap will allocate from, and 39 must uniquely identify it in a given platform. Since userspace applications 40 use the heap name as the discriminant, it must be able to tell which heap it 41 wants to use reliably if there's multiple heaps. 42 43- The name must not mention implementation details, such as the allocator. The 44 heap driver will change over time, and implementation details when it was 45 introduced might not be relevant in the future. 46 47- The name should describe properties of the buffers that would be allocated. 48 Doing so will make heap identification easier for userspace. Such properties 49 are: 50 51 - ``contiguous`` for physically contiguous buffers; 52 53 - ``protected`` for encrypted buffers not accessible the OS; 54 55- The name may describe intended usage. Doing so will make heap identification 56 easier for userspace applications and users. 57 58For example, assuming a platform with a reserved memory region located 59at the RAM address 0x42000000, intended to allocate video framebuffers, 60physically contiguous, and backed by the CMA kernel allocator, good 61names would be ``memory@42000000-contiguous`` or ``video@42000000``, but 62``cma-video`` wouldn't. 63