# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/reserved-memory/shared-dma-pool.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: /reserved-memory DMA pool node bindings

maintainers:
  - devicetree-spec@vger.kernel.org

allOf:
  - $ref: "reserved-memory.yaml"

properties:
  compatible:
    oneOf:
      - const: shared-dma-pool
        description: >
          This indicates a region of memory meant to be used as a shared
          pool of DMA buffers for a set of devices. It can be used by an
          operating system to instantiate the necessary pool management
          subsystem if necessary.

      - const: restricted-dma-pool
        description: >
          This indicates a region of memory meant to be used as a pool
          of restricted DMA buffers for a set of devices. The memory
          region would be the only region accessible to those devices.
          When using this, the no-map and reusable properties must not
          be set, so the operating system can create a virtual mapping
          that will be used for synchronization. The main purpose for
          restricted DMA is to mitigate the lack of DMA access control
          on systems without an IOMMU, which could result in the DMA
          accessing the system memory at unexpected times and/or
          unexpected addresses, possibly leading to data leakage or
          corruption. The feature on its own provides a basic level of
          protection against the DMA overwriting buffer contents at
          unexpected times. However, to protect against general data
          leakage and system memory corruption, the system needs to
          provide way to lock down the memory access, e.g., MPU. Note
          that since coherent allocation needs remapping, one must set
          up another device coherent pool by shared-dma-pool and use
          dma_alloc_from_dev_coherent instead for atomic coherent
          allocation.

  linux,cma-default:
    type: boolean
    description: >
      If this property is present, then Linux will use the region for
      the default pool of the contiguous memory allocator.

  linux,dma-default:
    type: boolean
    description: >
      If this property is present, then Linux will use the region for
      the default pool of the consistent DMA allocator.

unevaluatedProperties: false

examples:
  - |
      reserved-memory {
          #address-cells = <1>;
          #size-cells = <1>;
          ranges;

          /* global autoconfigured region for contiguous allocations */
          linux,cma {
              compatible = "shared-dma-pool";
              reusable;
              size = <0x4000000>;
              alignment = <0x2000>;
              linux,cma-default;
          };

          display_reserved: framebuffer@78000000 {
              reg = <0x78000000 0x800000>;
          };

          restricted_dma_reserved: restricted-dma-pool@50000000 {
              compatible = "restricted-dma-pool";
              reg = <0x50000000 0x4000000>;
          };
      };

...