€•mKŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ//translations/zh_CN/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ//translations/zh_TW/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ//translations/it_IT/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ//translations/ja_JP/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ//translations/ko_KR/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ//translations/pt_BR/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ//translations/sp_SP/userspace-api/dma-buf-heaps”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh·sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1hµhhh²hh³ŒI/var/lib/git/docbuild/linux/Documentation/userspace-api/dma-buf-heaps.rst”h´KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒAllocating dma-buf using heaps”h]”hŒAllocating dma-buf using heaps”…””}”(hhÏh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhhÊh²hh³hÇh´KubhŒ paragraph”“”)”}”(hŒ¶Dma-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]”hŒ¶Dma-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.”…””}”(hhßh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KhhÊh²hubhÉ)”}”(hhh]”(hÎ)”}”(hŒHeaps”h]”hŒHeaps”…””}”(hhðh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhhíh²hh³hÇh´K 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:”…””}”(hhþh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khhíh²hubhŒ block_quote”“”)”}”(hXó- The ``system`` heap allocates virtually contiguous, cacheable, buffers. - The ``system_cc_shared`` heap allocates virtually contiguous, cacheable, buffers using shared (decrypted) memory. It is only present on confidential computing (CoCo) VMs where memory encryption is active (e.g., AMD SEV, Intel TDX). The allocated pages have the encryption bit cleared, making them accessible for device DMA without TDISP support. On non-CoCo VM configurations, this heap is not registered. - 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”“”)”}”(hŒHThe ``system`` heap allocates virtually contiguous, cacheable, buffers. ”h]”hÞ)”}”(hŒGThe ``system`` heap allocates virtually contiguous, cacheable, buffers.”h]”(hŒThe ”…””}”(hjh²hh³Nh´NubhŒliteral”“”)”}”(hŒ ``system``”h]”hŒsystem”…””}”(hj'h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjubhŒ9 heap allocates virtually contiguous, cacheable, buffers.”…””}”(hjh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubj)”}”(hX–The ``system_cc_shared`` heap allocates virtually contiguous, cacheable, buffers using shared (decrypted) memory. It is only present on confidential computing (CoCo) VMs where memory encryption is active (e.g., AMD SEV, Intel TDX). The allocated pages have the encryption bit cleared, making them accessible for device DMA without TDISP support. On non-CoCo VM configurations, this heap is not registered. ”h]”hÞ)”}”(hX•The ``system_cc_shared`` heap allocates virtually contiguous, cacheable, buffers using shared (decrypted) memory. It is only present on confidential computing (CoCo) VMs where memory encryption is active (e.g., AMD SEV, Intel TDX). The allocated pages have the encryption bit cleared, making them accessible for device DMA without TDISP support. On non-CoCo VM configurations, this heap is not registered.”h]”(hŒThe ”…””}”(hjIh²hh³Nh´Nubj&)”}”(hŒ``system_cc_shared``”h]”hŒsystem_cc_shared”…””}”(hjQh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjIubhX} heap allocates virtually contiguous, cacheable, buffers using shared (decrypted) memory. It is only present on confidential computing (CoCo) VMs where memory encryption is active (e.g., AMD SEV, Intel TDX). The allocated pages have the encryption bit cleared, making them accessible for device DMA without TDISP support. On non-CoCo VM configurations, this heap is not registered.”…””}”(hjIh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KhjEubah}”(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]”(hŒThe ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ``default_cma_region``”h]”hŒdefault_cma_region”…””}”(hj{h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ· 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 ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ``cma``”h]”hŒcma”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ6 parameter, a memory region Device-Tree node with the ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ``linux,cma-default``”h]”hŒlinux,cma-default”…””}”(hjŸh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ property set, or through the ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ``CMA_SIZE_MBYTES``”h]”hŒCMA_SIZE_MBYTES”…””}”(hj±h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ or ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ``CMA_SIZE_PERCENTAGE``”h]”hŒCMA_SIZE_PERCENTAGE”…””}”(hjÃh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒT Kconfig options. Prior to Linux 6.17, its name wasn’t stable and could be called ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ ``reserved``”h]”hŒreserved”…””}”(hjÕh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ, ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ ``linux,cma``”h]”hŒ linux,cma”…””}”(hjçh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ, or ”…””}”(hjsh²hh³Nh´Nubj&)”}”(hŒ``default-pool``”h]”hŒ default-pool”…””}”(hjùh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjsubhŒ, depending on the platform.”…””}”(hjsh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´Khjoubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubj)”}”(hŒÜ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Þ)”}”(hŒÛ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ŒLA heap will be created for each reusable region in the device tree with the ”…””}”(hjh²hh³Nh´Nubj&)”}”(hŒ``shared-dma-pool``”h]”hŒshared-dma-pool”…””}”(hj#h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjubhŒe compatible, using the full device tree node name as its name. The buffer semantics are identical to ”…””}”(hjh²hh³Nh´Nubj&)”}”(hŒ``default-cma-region``”h]”hŒdefault-cma-region”…””}”(hj5h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjubhŒ.”…””}”(hjh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K$hjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jh³hÇh´Khjubah}”(h]”h ]”h"]”h$]”h&]”uh1j h³hÇh´Khhíh²hubeh}”(h]”Œheaps”ah ]”h"]”Œheaps”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´K ubhÉ)”}”(hhh]”(hÎ)”}”(hŒNaming Convention”h]”hŒNaming Convention”…””}”(hjlh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÍhjih²hh³hÇh´K*ubhÞ)”}”(hŒ;``dma-buf`` heaps name should meet a number of constraints:”h]”(j&)”}”(hŒ ``dma-buf``”h]”hŒdma-buf”…””}”(hj~h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjzubhŒ0 heaps name should meet a number of constraints:”…””}”(hjzh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K,hjih²hubj)”}”(hhh]”(j)”}”(hŒÀ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, we would be likely to introduce regressions. ”h]”hÞ)”}”(hŒ¿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, we would be likely to introduce regressions.”h]”hŒ¿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, we would be likely to introduce regressions.”…””}”(hjh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K.hj™ubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj–h²hh³hÇh´Nubj)”}”(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.”…””}”(hjµh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K2hj±ubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj–h²hh³hÇh´Nubj)”}”(hŒÇThe 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Þ)”}”(hŒÆThe 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ŒÆThe 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.”…””}”(hjÍh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K7hjÉubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj–h²hh³hÇh´Nubj)”}”(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Þ)”}”(hŒThe name should describe properties of the buffers that would be allocated. Doing so will make heap identification easier for userspace. Such properties are:”h]”hŒThe name should describe properties of the buffers that would be allocated. Doing so will make heap identification easier for userspace. Such properties are:”…””}”(hjåh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K;hjáubj)”}”(hhh]”(j)”}”(hŒ2``contiguous`` for physically contiguous buffers; ”h]”hÞ)”}”(hŒ1``contiguous`` for physically contiguous buffers;”h]”(j&)”}”(hŒ``contiguous``”h]”hŒ contiguous”…””}”(hjþh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjúubhŒ# for physically contiguous buffers;”…””}”(hjúh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´K?hjöubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjóubj)”}”(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”…””}”(hj$h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hj ubhŒ- for encrypted buffers not accessible the OS;”…””}”(hj h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KAhjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjóubeh}”(h]”h ]”h"]”h$]”h&]”jYjZuh1jh³hÇh´K?hjáubeh}”(h]”h ]”h"]”h$]”h&]”uh1jhj–h²hh³Nh´Nubj)”}”(hŒzThe name may describe intended usage. Doing so will make heap identification easier for userspace applications and users. ”h]”hÞ)”}”(hŒyThe name may describe intended usage. Doing so will make heap identification easier for userspace applications and users.”h]”hŒyThe name may describe intended usage. Doing so will make heap identification easier for userspace applications and users.”…””}”(hjRh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KChjNubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj–h²hh³hÇh´Nubeh}”(h]”h ]”h"]”h$]”h&]”jYjZuh1jh³hÇh´K.hjih²hubhÞ)”}”(hX3For example, assuming a platform with a reserved memory region located at the RAM address 0x42000000, intended to allocate video framebuffers, physically contiguous, and backed by the CMA kernel allocator, good names would be ``memory@42000000-contiguous`` or ``video@42000000``, but ``cma-video`` wouldn't.”h]”(hŒâFor example, assuming a platform with a reserved memory region located at the RAM address 0x42000000, intended to allocate video framebuffers, physically contiguous, and backed by the CMA kernel allocator, good names would be ”…””}”(hjlh²hh³Nh´Nubj&)”}”(hŒ``memory@42000000-contiguous``”h]”hŒmemory@42000000-contiguous”…””}”(hjth²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjlubhŒ or ”…””}”(hjlh²hh³Nh´Nubj&)”}”(hŒ``video@42000000``”h]”hŒvideo@42000000”…””}”(hj†h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjlubhŒ, but ”…””}”(hjlh²hh³Nh´Nubj&)”}”(hŒ ``cma-video``”h]”hŒ cma-video”…””}”(hj˜h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%hjlubhŒ wouldn’t.”…””}”(hjlh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÝh³hÇh´KFhjih²hubeh}”(h]”Œnaming-convention”ah ]”h"]”Œnaming convention”ah$]”h&]”uh1hÈhhÊh²hh³hÇh´K*ubeh}”(h]”Œallocating-dma-buf-using-heaps”ah ]”h"]”Œallocating dma-buf using heaps”ah$]”h&]”uh1hÈhhh²hh³hÇh´Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÇuh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hÍNŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jãŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÇŒ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j½jºjfjcjµj²uŒ nametypes”}”(j½‰jf‰jµ‰uh}”(jºhÊjchíj²jiuŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œ transformer”NŒ include_log”]”Œ decoration”Nh²hub.