%YAML 1.2
---
$id: "http://devicetree.org/schemas/arm/msm/msm_ion.yaml#"
$schema: "http://devicetree.org/meta-schemas/core.yaml#"

title: ION Memory Manager binding

maintainers:
  - Isaac J. Manjarres <isaacm@quicinc.com>

description: |
  ION is a memory manager that allows for sharing of buffers between different
  processes and between user space and kernel space. ION manages different
  memory spaces by separating the memory spaces into heaps.

  All child nodes of a qcom,msm-ion node are interpreted as ION heap
  configurations.

properties:
  $nodename:
    const: qcom,ion
    description: Container of ION heap nodes

  compatible:
    items:
      -const: qcom,msm-ion

  '#address-cells':
    const: 1

  '#size-cells':
    const: 0

patternProperties:
  '^qcom,ion-heap@[0-9]+$':
    properties:
      reg:
        maxItems: 1
        description: The ID assigned to this heap.

      memory-region:
        $ref: '/schemas/types.yaml#/definitions/phandle'
        maxItems: 1
        description: |
          Specifies the reserved memory region that this heap will allocate
          memory from. This property is only required for heaps that draw memory
          from a particular reserved memory region. Refer to
          Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
          for more information.

      qcom,ion-heap-type:
        $ref: '/schemas/types.yaml#/definitions/string'
        maxItems: 1
        items:
          - enum:
              - SYSTEM
              - CARVEOUT
              - SECURE_CARVEOUT
              - DMA
              - HYP_CMA
              - SYSTEM_SECURE
              - SECURE_DMA
        description: |
          The heap type to use for this heap. Heaps of type SECURE_CARVEOUT
          are expected to contain multiple child nodes, as seen below.

      qcom,dynamic-heap:
      Usage: optional
      Value type: <boolean>
      Definition: Denotes whether a heap can have memory dynamically added and
           subtracted from it. Heaps with this property are assumed to start off
           with no memory, and must have memory added to them prior to any use.

      $nodename:
        properties:
          memory-region:
            $ref: '/schemas/types.yaml#/definitions/phandle'
            maxItems: 1
            description: |
              Specifies the reserved memory region that this heap will allocate
              memory from. Refer to the reserved-memory binding documentation
              for more information.

          token:
            $ref: '/schemas/types.yaml#/definitions/uint32'
            minItems: 1
            description: |
              Specifies the set of secure domains which will be able to access
              the memory-region.

        required:
          - memory-region
          - token

    required:
      - reg
      - qcom,ion-heap-type

required:
  - compatible
  - '#address-cells'
  - '#size-cells'

examples:
  - |
    qcom,ion {
        compatible = "qcom,msm-ion";
        #address-cells = <1>;
        #size-cells = <0>;

        system_heap: qcom,ion-heap@25 {
            reg = <25>;
            qcom,ion-heap-type = "SYSTEM";
        };

        qcom,ion-heap@22 { /* ADSP HEAP */
            reg = <22>;
            memory-region = <&adsp_mem>;
            qcom,ion-heap-type = "DMA";
        };

        qcom,ion-heap@10 { /* SECURE DISPLAY HEAP */
            reg = <10>;
            memory-region = <&secure_display_memory>;
            qcom,ion-heap-type = "HYP_CMA";
        };

        qcom,ion-heap@9 {
            reg = <9>;
            qcom,ion-heap-type = "SYSTEM_SECURE";
        };

        qcom,ion-heap@14 {
            reg = <14>;
            qcom,ion-heap-type = "SECURE_CARVEOUT";
            node1 {
                memory-region = <&cp_region>;
                token = <ION_FLAG_CP_TOUCH>;
            };
        };
    };
