xref: /freebsd/sys/contrib/device-tree/Bindings/reserved-memory/shared-dma-pool.yaml (revision f81cdf24ba5436367377f7c8e8f51f6df2a75ca7) 
1# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/reserved-memory/shared-dma-pool.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: /reserved-memory DMA pool
8
9maintainers:
10  - devicetree-spec@vger.kernel.org
11
12allOf:
13  - $ref: reserved-memory.yaml
14
15properties:
16  compatible:
17    oneOf:
18      - const: shared-dma-pool
19        description: >
20          This indicates a region of memory meant to be used as a shared
21          pool of DMA buffers for a set of devices. It can be used by an
22          operating system to instantiate the necessary pool management
23          subsystem if necessary.
24
25      - const: restricted-dma-pool
26        description: >
27          This indicates a region of memory meant to be used as a pool
28          of restricted DMA buffers for a set of devices. The memory
29          region would be the only region accessible to those devices.
30          When using this, the no-map and reusable properties must not
31          be set, so the operating system can create a virtual mapping
32          that will be used for synchronization. The main purpose for
33          restricted DMA is to mitigate the lack of DMA access control
34          on systems without an IOMMU, which could result in the DMA
35          accessing the system memory at unexpected times and/or
36          unexpected addresses, possibly leading to data leakage or
37          corruption. The feature on its own provides a basic level of
38          protection against the DMA overwriting buffer contents at
39          unexpected times. However, to protect against general data
40          leakage and system memory corruption, the system needs to
41          provide way to lock down the memory access, e.g., MPU. Note
42          that since coherent allocation needs remapping, one must set
43          up another device coherent pool by shared-dma-pool and use
44          dma_alloc_from_dev_coherent instead for atomic coherent
45          allocation.
46
47  linux,cma-default:
48    type: boolean
49    description: >
50      If this property is present, then Linux will use the region for
51      the default pool of the contiguous memory allocator.
52
53  linux,dma-default:
54    type: boolean
55    description: >
56      If this property is present, then Linux will use the region for
57      the default pool of the consistent DMA allocator.
58
59if:
60  properties:
61    compatible:
62      contains:
63        const: restricted-dma-pool
64then:
65  properties:
66    no-map: false
67    reusable: false
68
69unevaluatedProperties: false
70
71examples:
72  - |
73      reserved-memory {
74          #address-cells = <1>;
75          #size-cells = <1>;
76          ranges;
77
78          /* global autoconfigured region for contiguous allocations */
79          linux,cma {
80              compatible = "shared-dma-pool";
81              reusable;
82              size = <0x4000000>;
83              alignment = <0x2000>;
84              linux,cma-default;
85          };
86
87          display_reserved: framebuffer@78000000 {
88              reg = <0x78000000 0x800000>;
89          };
90
91          restricted_dma_reserved: restricted-dma-pool@50000000 {
92              compatible = "restricted-dma-pool";
93              reg = <0x50000000 0x4000000>;
94          };
95      };
96
97...
98