tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
dt-bindings: Convert Reserved Memory binding to a schema
Convert the reserved memory bindings to DT schema format. The bindings
are split into schemas for clients, common reserved memory node
properties and a specific binding for shared-dma-pool.
Cc: devicetree-spec@vger.kernel.org
Signed-off-by: Maxime Ripard <maxime@cerno.tech>
Signed-off-by: Rob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20210901091852.479202-6-maxime@cerno.tech
authored by
Maxime Ripard
and committed by
Rob Herring
bf99826f
0e3e0fa7
+228
-171
+40
Documentation/devicetree/bindings/reserved-memory/memory-region.yaml
+40
Documentation/devicetree/bindings/reserved-memory/memory-region.yaml
···
1
+
# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
2
+
%YAML 1.2
3
+
---
4
+
$id: http://devicetree.org/schemas/reserved-memory/memory-region.yaml#
5
+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6
+
7
+
title: Reserved Memory Region Device Tree Binding
8
+
9
+
maintainers:
10
+
- devicetree-spec@vger.kernel.org
11
+
12
+
description: |
13
+
Regions in the /reserved-memory node may be referenced by other device
14
+
nodes by adding a memory-region property to the device node.
15
+
16
+
select: true
17
+
18
+
properties:
19
+
memory-region:
20
+
$ref: /schemas/types.yaml#/definitions/phandle-array
21
+
description: >
22
+
Phandle to a /reserved-memory child node assigned to the device.
23
+
24
+
memory-region-names:
25
+
$ref: /schemas/types.yaml#/definitions/string-array
26
+
description: >
27
+
A list of names, one for each corresponding entry in the
28
+
memory-region property
29
+
30
+
additionalProperties: true
31
+
32
+
examples:
33
+
- |
34
+
fb0: video@12300000 {
35
+
/* ... */
36
+
reg = <0x12300000 0x1000>;
37
+
memory-region = <&display_reserved>;
38
+
};
39
+
40
+
...
+1
-171
Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
+1
-171
Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
···
1
-
*** Reserved memory regions ***
2
-
3
-
Reserved memory is specified as a node under the /reserved-memory node.
4
-
The operating system shall exclude reserved memory from normal usage
5
-
one can create child nodes describing particular reserved (excluded from
6
-
normal use) memory regions. Such memory regions are usually designed for
7
-
the special usage by various device drivers.
8
-
9
-
Parameters for each memory region can be encoded into the device tree
10
-
with the following nodes:
11
-
12
-
/reserved-memory node
13
-
---------------------
14
-
#address-cells, #size-cells (required) - standard definition
15
-
- Should use the same values as the root node
16
-
ranges (required) - standard definition
17
-
- Should be empty
18
-
19
-
/reserved-memory/ child nodes
20
-
-----------------------------
21
-
Each child of the reserved-memory node specifies one or more regions of
22
-
reserved memory. Each child node may either use a 'reg' property to
23
-
specify a specific range of reserved memory, or a 'size' property with
24
-
optional constraints to request a dynamically allocated block of memory.
25
-
26
-
Following the generic-names recommended practice, node names should
27
-
reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). Unit
28
-
address (@<address>) should be appended to the name if the node is a
29
-
static allocation.
30
-
31
-
Properties:
32
-
Requires either a) or b) below.
33
-
a) static allocation
34
-
reg (required) - standard definition
35
-
b) dynamic allocation
36
-
size (required) - length based on parent's #size-cells
37
-
- Size in bytes of memory to reserve.
38
-
alignment (optional) - length based on parent's #size-cells
39
-
- Address boundary for alignment of allocation.
40
-
alloc-ranges (optional) - prop-encoded-array (address, length pairs).
41
-
- Specifies regions of memory that are
42
-
acceptable to allocate from.
43
-
44
-
If both reg and size are present, then the reg property takes precedence
45
-
and size is ignored.
46
-
47
-
Additional properties:
48
-
compatible (optional) - standard definition
49
-
- may contain the following strings:
50
-
- shared-dma-pool: This indicates a region of memory meant to be
51
-
used as a shared pool of DMA buffers for a set of devices. It can
52
-
be used by an operating system to instantiate the necessary pool
53
-
management subsystem if necessary.
54
-
- restricted-dma-pool: This indicates a region of memory meant to be
55
-
used as a pool of restricted DMA buffers for a set of devices. The
56
-
memory region would be the only region accessible to those devices.
57
-
When using this, the no-map and reusable properties must not be set,
58
-
so the operating system can create a virtual mapping that will be used
59
-
for synchronization. The main purpose for restricted DMA is to
60
-
mitigate the lack of DMA access control on systems without an IOMMU,
61
-
which could result in the DMA accessing the system memory at
62
-
unexpected times and/or unexpected addresses, possibly leading to data
63
-
leakage or corruption. The feature on its own provides a basic level
64
-
of protection against the DMA overwriting buffer contents at
65
-
unexpected times. However, to protect against general data leakage and
66
-
system memory corruption, the system needs to provide way to lock down
67
-
the memory access, e.g., MPU. Note that since coherent allocation
68
-
needs remapping, one must set up another device coherent pool by
69
-
shared-dma-pool and use dma_alloc_from_dev_coherent instead for atomic
70
-
coherent allocation.
71
-
- vendor specific string in the form <vendor>,[<device>-]<usage>
72
-
no-map (optional) - empty property
73
-
- Indicates the operating system must not create a virtual mapping
74
-
of the region as part of its standard mapping of system memory,
75
-
nor permit speculative access to it under any circumstances other
76
-
than under the control of the device driver using the region.
77
-
reusable (optional) - empty property
78
-
- The operating system can use the memory in this region with the
79
-
limitation that the device driver(s) owning the region need to be
80
-
able to reclaim it back. Typically that means that the operating
81
-
system can use that region to store volatile or cached data that
82
-
can be otherwise regenerated or migrated elsewhere.
83
-
84
-
A node must not carry both the no-map and the reusable property as these are
85
-
logically contradictory.
86
-
87
-
Linux implementation note:
88
-
- If a "linux,cma-default" property is present, then Linux will use the
89
-
region for the default pool of the contiguous memory allocator.
90
-
91
-
- If a "linux,dma-default" property is present, then Linux will use the
92
-
region for the default pool of the consistent DMA allocator.
93
-
94
-
Device node references to reserved memory
95
-
-----------------------------------------
96
-
Regions in the /reserved-memory node may be referenced by other device
97
-
nodes by adding a memory-region property to the device node.
98
-
99
-
memory-region (optional) - phandle, specifier pairs to children of /reserved-memory
100
-
memory-region-names (optional) - a list of names, one for each corresponding
101
-
entry in the memory-region property
102
-
103
-
Example
104
-
-------
105
-
This example defines 4 contiguous regions for Linux kernel:
106
-
one default of all device drivers (named linux,cma@72000000 and 64MiB in size),
107
-
one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB),
108
-
one for multimedia processing (named multimedia-memory@77000000, 64MiB), and
109
-
one for restricted dma pool (named restricted_dma_reserved@0x50000000, 64MiB).
110
-
111
-
/ {
112
-
#address-cells = <1>;
113
-
#size-cells = <1>;
114
-
115
-
memory {
116
-
reg = <0x40000000 0x40000000>;
117
-
};
118
-
119
-
reserved-memory {
120
-
#address-cells = <1>;
121
-
#size-cells = <1>;
122
-
ranges;
123
-
124
-
/* global autoconfigured region for contiguous allocations */
125
-
linux,cma {
126
-
compatible = "shared-dma-pool";
127
-
reusable;
128
-
size = <0x4000000>;
129
-
alignment = <0x2000>;
130
-
linux,cma-default;
131
-
};
132
-
133
-
display_reserved: framebuffer@78000000 {
134
-
reg = <0x78000000 0x800000>;
135
-
};
136
-
137
-
multimedia_reserved: multimedia@77000000 {
138
-
compatible = "acme,multimedia-memory";
139
-
reg = <0x77000000 0x4000000>;
140
-
};
141
-
142
-
restricted_dma_reserved: restricted_dma_reserved {
143
-
compatible = "restricted-dma-pool";
144
-
reg = <0x50000000 0x4000000>;
145
-
};
146
-
};
147
-
148
-
/* ... */
149
-
150
-
fb0: video@12300000 {
151
-
memory-region = <&display_reserved>;
152
-
/* ... */
153
-
};
154
-
155
-
scaler: scaler@12500000 {
156
-
memory-region = <&multimedia_reserved>;
157
-
/* ... */
158
-
};
159
-
160
-
codec: codec@12600000 {
161
-
memory-region = <&multimedia_reserved>;
162
-
/* ... */
163
-
};
164
-
165
-
pcie_device: pcie_device@0,0 {
166
-
reg = <0x83010000 0x0 0x00000000 0x0 0x00100000
167
-
0x83010000 0x0 0x00100000 0x0 0x00100000>;
168
-
memory-region = <&restricted_dma_reserved>;
169
-
/* ... */
170
-
};
171
-
};
1
+
This file has been moved to reserved-memory.yaml.
+100
Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml
+100
Documentation/devicetree/bindings/reserved-memory/reserved-memory.yaml
···
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
+
7
+
title: /reserved-memory Child Node Common Device Tree Bindings
8
+
9
+
maintainers:
10
+
- devicetree-spec@vger.kernel.org
11
+
12
+
description: >
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
+
30
+
properties:
31
+
reg: true
32
+
33
+
size:
34
+
$ref: /schemas/types.yaml#/definitions/uint32-array
35
+
minItems: 1
36
+
maxItems: 2
37
+
description: >
38
+
Length based on parent's \#size-cells. Size in bytes of memory to
39
+
reserve.
40
+
41
+
alignment:
42
+
$ref: /schemas/types.yaml#/definitions/uint32-array
43
+
minItems: 1
44
+
maxItems: 2
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
+
no-map:
56
+
type: boolean
57
+
description: >
58
+
Indicates the operating system must not create a virtual mapping
59
+
of the region as part of its standard mapping of system memory,
60
+
nor permit speculative access to it under any circumstances other
61
+
than under the control of the device driver using the region.
62
+
63
+
reusable:
64
+
type: boolean
65
+
description: >
66
+
The operating system can use the memory in this region with the
67
+
limitation that the device driver(s) owning the region need to be
68
+
able to reclaim it back. Typically that means that the operating
69
+
system can use that region to store volatile or cached data that
70
+
can be otherwise regenerated or migrated elsewhere.
71
+
72
+
allOf:
73
+
- if:
74
+
required:
75
+
- no-map
76
+
77
+
then:
78
+
not:
79
+
required:
80
+
- reusable
81
+
82
+
- if:
83
+
required:
84
+
- reusable
85
+
86
+
then:
87
+
not:
88
+
required:
89
+
- no-map
90
+
91
+
oneOf:
92
+
- required:
93
+
- reg
94
+
95
+
- required:
96
+
- size
97
+
98
+
additionalProperties: true
99
+
100
+
...