xref: /freebsd/sys/contrib/device-tree/Bindings/reserved-memory/reserved-memory.yaml (revision a90b9d0159070121c221b966469c3e36d912bf82) 
1# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/reserved-memory/reserved-memory.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: /reserved-memory Child Node Common
8
9maintainers:
10  - devicetree-spec@vger.kernel.org
11
12description: >
13  Reserved memory is specified as a node under the /reserved-memory node. The
14  operating system shall exclude reserved memory from normal usage one can
15  create child nodes describing particular reserved (excluded from normal use)
16  memory regions. Such memory regions are usually designed for the special
17  usage by various device drivers.
18
19  Each child of the reserved-memory node specifies one or more regions
20  of reserved memory. Each child node may either use a 'reg' property to
21  specify a specific range of reserved memory, or a 'size' property with
22  optional constraints to request a dynamically allocated block of
23  memory.
24
25  Following the generic-names recommended practice, node names should
26  reflect the purpose of the node (ie. "framebuffer" or "dma-pool").
27  Unit address (@<address>) should be appended to the name if the node
28  is a static allocation.
29
30properties:
31  reg: true
32
33  size:
34    oneOf:
35      - $ref: /schemas/types.yaml#/definitions/uint32
36      - $ref: /schemas/types.yaml#/definitions/uint64
37    description: >
38      Length based on parent's \#size-cells. Size in bytes of memory to
39      reserve.
40
41  alignment:
42    oneOf:
43      - $ref: /schemas/types.yaml#/definitions/uint32
44      - $ref: /schemas/types.yaml#/definitions/uint64
45    description: >
46      Length based on parent's \#size-cells. Address boundary for
47      alignment of allocation.
48
49  alloc-ranges:
50    $ref: /schemas/types.yaml#/definitions/uint32-array
51    description: >
52      Address and Length pairs. Specifies regions of memory that are
53      acceptable to allocate from.
54
55  iommu-addresses:
56    $ref: /schemas/types.yaml#/definitions/phandle-array
57    description: >
58      A list of phandle and specifier pairs that describe static IO virtual
59      address space mappings and carveouts associated with a given reserved
60      memory region. The phandle in the first cell refers to the device for
61      which the mapping or carveout is to be created.
62
63      The specifier consists of an address/size pair and denotes the IO
64      virtual address range of the region for the given device. The exact
65      format depends on the values of the "#address-cells" and "#size-cells"
66      properties of the device referenced via the phandle.
67
68      When used in combination with a "reg" property, an IOVA mapping is to
69      be established for this memory region. One example where this can be
70      useful is to create an identity mapping for physical memory that the
71      firmware has configured some hardware to access (such as a bootsplash
72      framebuffer).
73
74      If no "reg" property is specified, the "iommu-addresses" property
75      defines carveout regions in the IOVA space for the given device. This
76      can be useful if a certain memory region should not be mapped through
77      the IOMMU.
78
79  no-map:
80    type: boolean
81    description: >
82      Indicates the operating system must not create a virtual mapping
83      of the region as part of its standard mapping of system memory,
84      nor permit speculative access to it under any circumstances other
85      than under the control of the device driver using the region.
86
87  reusable:
88    type: boolean
89    description: >
90      The operating system can use the memory in this region with the
91      limitation that the device driver(s) owning the region need to be
92      able to reclaim it back. Typically that means that the operating
93      system can use that region to store volatile or cached data that
94      can be otherwise regenerated or migrated elsewhere.
95
96allOf:
97  - if:
98      required:
99        - no-map
100
101    then:
102      not:
103        required:
104          - reusable
105
106  - if:
107      required:
108        - reusable
109
110    then:
111      not:
112        required:
113          - no-map
114
115oneOf:
116  - oneOf:
117      - required:
118          - reg
119
120      - required:
121          - size
122
123  - oneOf:
124      # IOMMU reservations
125      - required:
126          - iommu-addresses
127
128      # IOMMU mappings
129      - required:
130          - reg
131          - iommu-addresses
132
133additionalProperties: true
134
135examples:
136  - |
137    / {
138      compatible = "foo";
139      model = "foo";
140
141      #address-cells = <2>;
142      #size-cells = <2>;
143
144      reserved-memory {
145        #address-cells = <2>;
146        #size-cells = <2>;
147        ranges;
148
149        adsp_resv: reservation-adsp {
150          /*
151           * Restrict IOVA mappings for ADSP buffers to the 512 MiB region
152           * from 0x40000000 - 0x5fffffff. Anything outside is reserved by
153           * the ADSP for I/O memory and private memory allocations.
154           */
155          iommu-addresses = <&adsp 0x0 0x00000000 0x00 0x40000000>,
156                            <&adsp 0x0 0x60000000 0xff 0xa0000000>;
157        };
158
159        fb: framebuffer@90000000 {
160          reg = <0x0 0x90000000 0x0 0x00800000>;
161          iommu-addresses = <&dc0 0x0 0x90000000 0x0 0x00800000>;
162        };
163      };
164
165      bus@0 {
166        #address-cells = <1>;
167        #size-cells = <1>;
168        ranges = <0x0 0x0 0x0 0x40000000>;
169
170        adsp: adsp@2990000 {
171          reg = <0x2990000 0x2000>;
172          memory-region = <&adsp_resv>;
173        };
174
175        dc0: display@15200000 {
176          reg = <0x15200000 0x10000>;
177          memory-region = <&fb>;
178        };
179      };
180    };
181...
182