summaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/memory.txt
blob: eb24693655935fdd1df97803bab69a9d5314fbde (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
*** Memory binding ***

The /memory node provides basic information about the address and size
of the physical memory. This node is usually filled or updated by the
bootloader, depending on the actual memory configuration of the given
hardware.

The memory layout is described by the following node:

/ {
	#address-cells = <(n)>;
	#size-cells = <(m)>;
	memory {
		device_type = "memory";
		reg =  <(baseaddr1) (size1)
			(baseaddr2) (size2)
			...
			(baseaddrN) (sizeN)>;
	};
	...
};

A memory node follows the typical device tree rules for "reg" property:
n:		number of cells used to store base address value
m:		number of cells used to store size value
baseaddrX:	defines a base address of the defined memory bank
sizeX:		the size of the defined memory bank


More than one memory bank can be defined.


*** Reserved memory regions ***

In /memory/reserved-memory node one can create child nodes describing
particular reserved (excluded from normal use) memory regions. Such
memory regions are usually designed for the special usage by various
device drivers. A good example are contiguous memory allocations or
memory sharing with other operating system on the same hardware board.
Those special memory regions might depend on the board configuration and
devices used on the target system.

Parameters for each memory region can be encoded into the device tree
with the following convention:

[(label):] (name) {
	compatible = "linux,contiguous-memory-region", "reserved-memory-region";
	reg = <(address) (size)>;
	(linux,default-contiguous-region);
};

compatible:	one or more of:
	- "linux,contiguous-memory-region" - enables binding of this
	  region to Contiguous Memory Allocator (special region for
	  contiguous memory allocations, shared with movable system
	  memory, Linux kernel-specific).
	- "reserved-memory-region" - compatibility is defined, given
	  region is assigned for exclusive usage for by the respective
	  devices.

reg:	standard property defining the base address and size of
	the memory region

linux,default-contiguous-region: property indicating that the region
	is the default region for all contiguous memory
	allocations, Linux specific (optional)

It is optional to specify the base address, so if one wants to use
autoconfiguration of the base address, '0' can be specified as a base
address in the 'reg' property.

The /memory/reserved-memory node must contain the same #address-cells
and #size-cells value as the root node.


*** Device node's properties ***

Once regions in the /memory/reserved-memory node have been defined, they
may be referenced by other device nodes. Bindings that wish to reference
memory regions should explicitly document their use of the following
property:

memory-region = <&phandle_to_defined_region>;

This property indicates that the device driver should use the memory
region pointed by the given phandle.


*** Example ***

This example defines a memory consisting of 4 memory banks. 3 contiguous
regions are defined for Linux kernel, one default of all device drivers
(named contig_mem, placed at 0x72000000, 64MiB), one dedicated to the
framebuffer device (labelled display_mem, placed at 0x78000000, 8MiB)
and one for multimedia processing (labelled multimedia_mem, placed at
0x77000000, 64MiB). 'display_mem' region is then assigned to fb@12300000
device for DMA memory allocations (Linux kernel drivers will use CMA is
available or dma-exclusive usage otherwise). 'multimedia_mem' is
assigned to scaler@12500000 and codec@12600000 devices for contiguous
memory allocations when CMA driver is enabled.

The reason for creating a separate region for framebuffer device is to
match the framebuffer base address to the one configured by bootloader,
so once Linux kernel drivers starts no glitches on the displayed boot
logo appears. Scaller and codec drivers should share the memory
allocations.

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	/* ... */

	memory {
		reg =  <0x40000000 0x10000000
			0x50000000 0x10000000
			0x60000000 0x10000000
			0x70000000 0x10000000>;

		reserved-memory {
			#address-cells = <1>;
			#size-cells = <1>;

			/*
			 * global autoconfigured region for contiguous allocations
			 * (used only with Contiguous Memory Allocator)
			 */
			contig_region@0 {
				compatible = "linux,contiguous-memory-region";
				reg = <0x0 0x4000000>;
				linux,default-contiguous-region;
			};

			/*
			 * special region for framebuffer
			 */
			display_region: region@78000000 {
				compatible = "linux,contiguous-memory-region", "reserved-memory-region";
				reg = <0x78000000 0x800000>;
			};

			/*
			 * special region for multimedia processing devices
			 */
			multimedia_region: region@77000000 {
				compatible = "linux,contiguous-memory-region";
				reg = <0x77000000 0x4000000>;
			};
		};
	};

	/* ... */

	fb0: fb@12300000 {
		status = "okay";
		memory-region = <&display_region>;
	};

	scaler: scaler@12500000 {
		status = "okay";
		memory-region = <&multimedia_region>;
	};

	codec: codec@12600000 {
		status = "okay";
		memory-region = <&multimedia_region>;
	};
};