Bsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget//translations/zh_CN/userspace-api/dma-buf-heapsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/zh_TW/userspace-api/dma-buf-heapsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/it_IT/userspace-api/dma-buf-heapsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/ja_JP/userspace-api/dma-buf-heapsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/ko_KR/userspace-api/dma-buf-heapsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/sp_SP/userspace-api/dma-buf-heapsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhI/var/lib/git/docbuild/linux/Documentation/userspace-api/dma-buf-heaps.rsthKubhsection)}(hhh](htitle)}(hAllocating dma-buf using heapsh]hAllocating dma-buf using heaps}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hDma-buf Heaps are a way for userspace to allocate dma-buf objects. They are typically used to allocate buffers from a specific allocation pool, or to share buffers across frameworks.h]hDma-buf Heaps are a way for userspace to allocate dma-buf objects. They are typically used to allocate buffers from a specific allocation pool, or to share buffers across frameworks.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hHeapsh]hHeaps}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh)}(h`A heap represents a specific allocator. The Linux kernel currently supports the following heaps:h]h`A heap represents a specific allocator. The Linux kernel currently supports the following heaps:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh block_quote)}(hXP- The ``system`` heap allocates virtually contiguous, cacheable, buffers. - The ``default_cma_region`` heap allocates physically contiguous, cacheable, buffers. Only present if a CMA region is present. Such a region is 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. Prior to Linux 6.17, its name wasn't stable and could be called ``reserved``, ``linux,cma``, or ``default-pool``, depending on the platform. - A heap will be created for each reusable region in the device tree with the ``shared-dma-pool`` compatible, using the full device tree node name as its name. The buffer semantics are identical to ``default-cma-region``. h]h bullet_list)}(hhh](h list_item)}(hHThe ``system`` heap allocates virtually contiguous, cacheable, buffers. h]h)}(hGThe ``system`` heap allocates virtually contiguous, cacheable, buffers.h](hThe }(hj hhhNhNubhliteral)}(h ``system``h]hsystem}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh9 heap allocates virtually contiguous, cacheable, buffers.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hXThe ``default_cma_region`` heap allocates physically contiguous, cacheable, buffers. Only present if a CMA region is present. Such a region is 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. Prior to Linux 6.17, its name wasn't stable and could be called ``reserved``, ``linux,cma``, or ``default-pool``, depending on the platform. h]h)}(hX The ``default_cma_region`` heap allocates physically contiguous, cacheable, buffers. Only present if a CMA region is present. Such a region is 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. Prior to Linux 6.17, its name wasn't stable and could be called ``reserved``, ``linux,cma``, or ``default-pool``, depending on the platform.h](hThe }(hj5hhhNhNubj)}(h``default_cma_region``h]hdefault_cma_region}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh heap allocates physically contiguous, cacheable, buffers. Only present if a CMA region is present. Such a region is usually created either through the kernel commandline through the }(hj5hhhNhNubj)}(h``cma``h]hcma}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh6 parameter, a memory region Device-Tree node with the }(hj5hhhNhNubj)}(h``linux,cma-default``h]hlinux,cma-default}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh property set, or through the }(hj5hhhNhNubj)}(h``CMA_SIZE_MBYTES``h]hCMA_SIZE_MBYTES}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh or }(hj5hhhNhNubj)}(h``CMA_SIZE_PERCENTAGE``h]hCMA_SIZE_PERCENTAGE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubhT Kconfig options. Prior to Linux 6.17, its name wasn’t stable and could be called }(hj5hhhNhNubj)}(h ``reserved``h]hreserved}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh, }(hj5hhhNhNubj)}(h ``linux,cma``h]h linux,cma}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh, or }(hj5hhhNhNubj)}(h``default-pool``h]h default-pool}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubh, depending on the platform.}(hj5hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj1ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hA heap will be created for each reusable region in the device tree with the ``shared-dma-pool`` compatible, using the full device tree node name as its name. The buffer semantics are identical to ``default-cma-region``. h]h)}(hA heap will be created for each reusable region in the device tree with the ``shared-dma-pool`` compatible, using the full device tree node name as its name. The buffer semantics are identical to ``default-cma-region``.h](hLA heap will be created for each reusable region in the device tree with the }(hjhhhNhNubj)}(h``shared-dma-pool``h]hshared-dma-pool}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhe compatible, using the full device tree node name as its name. The buffer semantics are identical to }(hjhhhNhNubj)}(h``default-cma-region``h]hdefault-cma-region}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]bullet-uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]heapsah ]h"]heapsah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hNaming Conventionh]hNaming Convention}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj+hhhhhK#ubh)}(h;``dma-buf`` heaps name should meet a number of constraints:h](j)}(h ``dma-buf``h]hdma-buf}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj<ubh0 heaps name should meet a number of constraints:}(hj<hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK%hj+hhubh)}(hhh](j)}(hThe 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, we would be likely to introduce regressions. h]h)}(hThe 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, we would be likely to introduce regressions.h]hThe 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, we would be likely to introduce regressions.}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hj[ubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hXThe 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. h]h)}(hXThe 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.h]hXThe 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.}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK+hjsubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hThe 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. h]h)}(hThe 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.h]hThe 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjubah}(h]h ]h"]h$]h&]uh1jhjXhhhhhNubj)}(hXThe name should describe properties of the buffers that would be allocated. Doing so will make heap identification easier for userspace. Such properties are: - ``contiguous`` for physically contiguous buffers; - ``protected`` for encrypted buffers not accessible the OS; h](h)}(hThe name should describe properties of the buffers that would be allocated. Doing so will make heap identification easier for userspace. Such properties are:h]hThe name should describe properties of the buffers that would be allocated. Doing so will make heap identification easier for userspace. Such properties are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK4hjubh)}(hhh](j)}(h2``contiguous`` for physically contiguous buffers; h]h)}(h1``contiguous`` for physically contiguous buffers;h](j)}(h``contiguous``h]h contiguous}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh# for physically contiguous buffers;}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK8hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h;``protected`` for encrypted buffers not accessible the OS; h]h)}(h:``protected`` for encrypted buffers not accessible the OS;h](j)}(h ``protected``h]h protected}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh- for encrypted buffers not accessible the OS;}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK:hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhK8hjubeh}(h]h ]h"]h$]h&]uh1jhjXhhhNhNubj)}(hzThe name may describe intended usage. Doing so will make heap identification easier for userspace applications and users. h]h)}(hyThe name may describe intended usage. Doing so will make heap identification easier for userspace applications and users.h]hyThe name may describe intended usage. Doing so will make heap identification easier for userspace applications and users.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK