tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
of: document bindings for reserved-memory nodes
Reserved memory nodes allow for the reservation of static (fixed
address) regions, or dynamically allocated regions for a specific
purpose.
[joshc: Based on binding document proposed (in non-patch form) here:
http://lkml.kernel.org/g/20131030134702.19B57C402A0@trevor.secretlab.ca
adapted to support #memory-region-cells]
Signed-off-by: Josh Cartwright <joshc@codeaurora.org>
[mszyprow: removed #memory-region-cells property]
Signed-off-by: Marek Szyprowski <m.szyprowski@samsung.com>
[grant.likely: removed residual #memory-region-cells example]
Signed-off-by: Grant Likely <grant.likely@linaro.org>
+133
+133
Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt
+133
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 instanciate the necessary pool
53
+
management subsystem if necessary.
54
+
- vendor specific string in the form <vendor>,[<device>-]<usage>
55
+
no-map (optional) - empty property
56
+
- Indicates the operating system must not create a virtual mapping
57
+
of the region as part of its standard mapping of system memory,
58
+
nor permit speculative access to it under any circumstances other
59
+
than under the control of the device driver using the region.
60
+
reusable (optional) - empty property
61
+
- The operating system can use the memory in this region with the
62
+
limitation that the device driver(s) owning the region need to be
63
+
able to reclaim it back. Typically that means that the operating
64
+
system can use that region to store volatile or cached data that
65
+
can be otherwise regenerated or migrated elsewhere.
66
+
67
+
Linux implementation note:
68
+
- If a "linux,cma-default" property is present, then Linux will use the
69
+
region for the default pool of the contiguous memory allocator.
70
+
71
+
Device node references to reserved memory
72
+
-----------------------------------------
73
+
Regions in the /reserved-memory node may be referenced by other device
74
+
nodes by adding a memory-region property to the device node.
75
+
76
+
memory-region (optional) - phandle, specifier pairs to children of /reserved-memory
77
+
78
+
Example
79
+
-------
80
+
This example defines 3 contiguous regions are defined for Linux kernel:
81
+
one default of all device drivers (named linux,cma@72000000 and 64MiB in size),
82
+
one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and
83
+
one for multimedia processing (named multimedia-memory@77000000, 64MiB).
84
+
85
+
/ {
86
+
#address-cells = <1>;
87
+
#size-cells = <1>;
88
+
89
+
memory {
90
+
reg = <0x40000000 0x40000000>;
91
+
};
92
+
93
+
reserved-memory {
94
+
#address-cells = <1>;
95
+
#size-cells = <1>;
96
+
ranges;
97
+
98
+
/* global autoconfigured region for contiguous allocations */
99
+
linux,cma {
100
+
compatible = "shared-dma-pool";
101
+
reusable;
102
+
size = <0x4000000>;
103
+
alignment = <0x2000>;
104
+
linux,cma-default;
105
+
};
106
+
107
+
display_reserved: framebuffer@78000000 {
108
+
reg = <0x78000000 0x800000>;
109
+
};
110
+
111
+
multimedia_reserved: multimedia@77000000 {
112
+
compatible = "acme,multimedia-memory";
113
+
reg = <0x77000000 0x4000000>;
114
+
};
115
+
};
116
+
117
+
/* ... */
118
+
119
+
fb0: video@12300000 {
120
+
memory-region = <&display_reserved>;
121
+
/* ... */
122
+
};
123
+
124
+
scaler: scaler@12500000 {
125
+
memory-region = <&multimedia_reserved>;
126
+
/* ... */
127
+
};
128
+
129
+
codec: codec@12600000 {
130
+
memory-region = <&multimedia_reserved>;
131
+
/* ... */
132
+
};
133
+
};