Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 ``system_cc_shared`` heap allocates virtually contiguous, cacheable,
20 buffers using shared (decrypted) memory. It is only present on
21 confidential computing (CoCo) VMs where memory encryption is active
22 (e.g., AMD SEV, Intel TDX). The allocated pages have the encryption
23 bit cleared, making them accessible for device DMA without TDISP
24 support. On non-CoCo VM configurations, this heap is not registered.
25
26 - The ``default_cma_region`` heap allocates physically contiguous,
27 cacheable, buffers. Only present if a CMA region is present. Such a
28 region is usually created either through the kernel commandline
29 through the ``cma`` parameter, a memory region Device-Tree node with
30 the ``linux,cma-default`` property set, or through the
31 ``CMA_SIZE_MBYTES`` or ``CMA_SIZE_PERCENTAGE`` Kconfig options. Prior
32 to Linux 6.17, its name wasn't stable and could be called
33 ``reserved``, ``linux,cma``, or ``default-pool``, depending on the
34 platform.
35
36 - A heap will be created for each reusable region in the device tree
37 with the ``shared-dma-pool`` compatible, using the full device tree
38 node name as its name. The buffer semantics are identical to
39 ``default-cma-region``.
40
41Naming Convention
42=================
43
44``dma-buf`` heaps name should meet a number of constraints:
45
46- The name must be stable, and must not change from one version to the other.
47 Userspace identifies heaps by their name, so if the names ever change, we
48 would be likely to introduce regressions.
49
50- The name must describe the memory region the heap will allocate from, and
51 must uniquely identify it in a given platform. Since userspace applications
52 use the heap name as the discriminant, it must be able to tell which heap it
53 wants to use reliably if there's multiple heaps.
54
55- The name must not mention implementation details, such as the allocator. The
56 heap driver will change over time, and implementation details when it was
57 introduced might not be relevant in the future.
58
59- The name should describe properties of the buffers that would be allocated.
60 Doing so will make heap identification easier for userspace. Such properties
61 are:
62
63 - ``contiguous`` for physically contiguous buffers;
64
65 - ``protected`` for encrypted buffers not accessible the OS;
66
67- The name may describe intended usage. Doing so will make heap identification
68 easier for userspace applications and users.
69
70For example, assuming a platform with a reserved memory region located
71at the RAM address 0x42000000, intended to allocate video framebuffers,
72physically contiguous, and backed by the CMA kernel allocator, good
73names would be ``memory@42000000-contiguous`` or ``video@42000000``, but
74``cma-video`` wouldn't.