Commit | Line | Data |
---|---|---|
6867c931 YG |
1 | ============== |
2 | Memory Hotplug | |
3 | ============== | |
4 | ||
10020ca2 YG |
5 | Created: Jul 28 2007 |
6 | Add description of notifier of memory hotplug Oct 11 2007 | |
6867c931 YG |
7 | |
8 | This document is about memory hotplug including how-to-use and current status. | |
9 | Because Memory Hotplug is still under development, contents of this text will | |
10 | be changed often. | |
11 | ||
12 | 1. Introduction | |
13 | 1.1 purpose of memory hotplug | |
14 | 1.2. Phases of memory hotplug | |
15 | 1.3. Unit of Memory online/offline operation | |
16 | 2. Kernel Configuration | |
17 | 3. sysfs files for memory hotplug | |
18 | 4. Physical memory hot-add phase | |
19 | 4.1 Hardware(Firmware) Support | |
20 | 4.2 Notify memory hot-add event by hand | |
21 | 5. Logical Memory hot-add phase | |
22 | 5.1. State of memory | |
23 | 5.2. How to online memory | |
24 | 6. Logical memory remove | |
25 | 6.1 Memory offline and ZONE_MOVABLE | |
26 | 6.2. How to offline memory | |
27 | 7. Physical memory remove | |
10020ca2 YG |
28 | 8. Memory hotplug event notifier |
29 | 9. Future Work List | |
6867c931 YG |
30 | |
31 | Note(1): x86_64's has special implementation for memory hotplug. | |
32 | This text does not describe it. | |
33 | Note(2): This text assumes that sysfs is mounted at /sys. | |
34 | ||
35 | ||
36 | --------------- | |
37 | 1. Introduction | |
38 | --------------- | |
39 | ||
40 | 1.1 purpose of memory hotplug | |
41 | ------------ | |
42 | Memory Hotplug allows users to increase/decrease the amount of memory. | |
43 | Generally, there are two purposes. | |
44 | ||
45 | (A) For changing the amount of memory. | |
46 | This is to allow a feature like capacity on demand. | |
47 | (B) For installing/removing DIMMs or NUMA-nodes physically. | |
48 | This is to exchange DIMMs/NUMA-nodes, reduce power consumption, etc. | |
49 | ||
50 | (A) is required by highly virtualized environments and (B) is required by | |
51 | hardware which supports memory power management. | |
52 | ||
53 | Linux memory hotplug is designed for both purpose. | |
54 | ||
55 | ||
56 | 1.2. Phases of memory hotplug | |
57 | --------------- | |
58 | There are 2 phases in Memory Hotplug. | |
59 | 1) Physical Memory Hotplug phase | |
60 | 2) Logical Memory Hotplug phase. | |
61 | ||
62 | The First phase is to communicate hardware/firmware and make/erase | |
63 | environment for hotplugged memory. Basically, this phase is necessary | |
64 | for the purpose (B), but this is good phase for communication between | |
65 | highly virtualized environments too. | |
66 | ||
67 | When memory is hotplugged, the kernel recognizes new memory, makes new memory | |
68 | management tables, and makes sysfs files for new memory's operation. | |
69 | ||
70 | If firmware supports notification of connection of new memory to OS, | |
71 | this phase is triggered automatically. ACPI can notify this event. If not, | |
72 | "probe" operation by system administration is used instead. | |
73 | (see Section 4.). | |
74 | ||
75 | Logical Memory Hotplug phase is to change memory state into | |
19f59460 | 76 | available/unavailable for users. Amount of memory from user's view is |
6867c931 YG |
77 | changed by this phase. The kernel makes all memory in it as free pages |
78 | when a memory range is available. | |
79 | ||
80 | In this document, this phase is described as online/offline. | |
81 | ||
19f59460 | 82 | Logical Memory Hotplug phase is triggered by write of sysfs file by system |
6867c931 YG |
83 | administrator. For the hot-add case, it must be executed after Physical Hotplug |
84 | phase by hand. | |
85 | (However, if you writes udev's hotplug scripts for memory hotplug, these | |
86 | phases can be execute in seamless way.) | |
87 | ||
88 | ||
89 | 1.3. Unit of Memory online/offline operation | |
90 | ------------ | |
56a3c655 LZ |
91 | Memory hotplug uses SPARSEMEM memory model which allows memory to be divided |
92 | into chunks of the same size. These chunks are called "sections". The size of | |
93 | a memory section is architecture dependent. For example, power uses 16MiB, ia64 | |
94 | uses 1GiB. | |
6867c931 | 95 | |
56a3c655 LZ |
96 | Memory sections are combined into chunks referred to as "memory blocks". The |
97 | size of a memory block is architecture dependent and represents the logical | |
98 | unit upon which memory online/offline operations are to be performed. The | |
99 | default size of a memory block is the same as memory section size unless an | |
100 | architecture specifies otherwise. (see Section 3.) | |
101 | ||
102 | To determine the size (in bytes) of a memory block please read this file: | |
6867c931 YG |
103 | |
104 | /sys/devices/system/memory/block_size_bytes | |
105 | ||
6867c931 YG |
106 | |
107 | ----------------------- | |
108 | 2. Kernel Configuration | |
109 | ----------------------- | |
110 | To use memory hotplug feature, kernel must be compiled with following | |
111 | config options. | |
112 | ||
113 | - For all memory hotplug | |
114 | Memory model -> Sparse Memory (CONFIG_SPARSEMEM) | |
115 | Allow for memory hot-add (CONFIG_MEMORY_HOTPLUG) | |
116 | ||
117 | - To enable memory removal, the followings are also necessary | |
118 | Allow for memory hot remove (CONFIG_MEMORY_HOTREMOVE) | |
119 | Page Migration (CONFIG_MIGRATION) | |
120 | ||
121 | - For ACPI memory hotplug, the followings are also necessary | |
122 | Memory hotplug (under ACPI Support menu) (CONFIG_ACPI_HOTPLUG_MEMORY) | |
123 | This option can be kernel module. | |
124 | ||
125 | - As a related configuration, if your box has a feature of NUMA-node hotplug | |
126 | via ACPI, then this option is necessary too. | |
127 | ACPI0004,PNP0A05 and PNP0A06 Container Driver (under ACPI Support menu) | |
128 | (CONFIG_ACPI_CONTAINER). | |
129 | This option can be kernel module too. | |
130 | ||
56a3c655 | 131 | |
6867c931 | 132 | -------------------------------- |
56a3c655 | 133 | 3 sysfs files for memory hotplug |
6867c931 | 134 | -------------------------------- |
56a3c655 LZ |
135 | All memory blocks have their device information in sysfs. Each memory block |
136 | is described under /sys/devices/system/memory as | |
6867c931 YG |
137 | |
138 | /sys/devices/system/memory/memoryXXX | |
56a3c655 | 139 | (XXX is the memory block id.) |
6867c931 | 140 | |
56a3c655 | 141 | For the memory block covered by the sysfs directory. It is expected that all |
0c2c99b1 NF |
142 | memory sections in this range are present and no memory holes exist in the |
143 | range. Currently there is no way to determine if there is a memory hole, but | |
144 | the existence of one should not affect the hotplug capabilities of the memory | |
145 | block. | |
6867c931 | 146 | |
56a3c655 | 147 | For example, assume 1GiB memory block size. A device for a memory starting at |
6867c931 YG |
148 | 0x100000000 is /sys/device/system/memory/memory4 |
149 | (0x100000000 / 1Gib = 4) | |
150 | This device covers address range [0x100000000 ... 0x140000000) | |
151 | ||
56a3c655 | 152 | Under each memory block, you can see 4 files: |
6867c931 | 153 | |
56a3c655 | 154 | /sys/devices/system/memory/memoryXXX/phys_index |
6867c931 YG |
155 | /sys/devices/system/memory/memoryXXX/phys_device |
156 | /sys/devices/system/memory/memoryXXX/state | |
c04fc586 | 157 | /sys/devices/system/memory/memoryXXX/removable |
6867c931 | 158 | |
56a3c655 | 159 | 'phys_index' : read-only and contains memory block id, same as XXX. |
0c2c99b1 NF |
160 | 'state' : read-write |
161 | at read: contains online/offline state of memory. | |
511c2aba LJ |
162 | at write: user can specify "online_kernel", |
163 | "online_movable", "online", "offline" command | |
59e68a18 | 164 | which will be performed on all sections in the block. |
0c2c99b1 NF |
165 | 'phys_device' : read-only: designed to show the name of physical memory |
166 | device. This is not well implemented now. | |
167 | 'removable' : read-only: contains an integer value indicating | |
168 | whether the memory block is removable or not | |
169 | removable. A value of 1 indicates that the memory | |
170 | block is removable and a value of 0 indicates that | |
171 | it is not removable. A memory block is removable only if | |
172 | every section in the block is removable. | |
6867c931 YG |
173 | |
174 | NOTE: | |
175 | These directories/files appear after physical memory hotplug phase. | |
176 | ||
dee5d0d5 AC |
177 | If CONFIG_NUMA is enabled the memoryXXX/ directories can also be accessed |
178 | via symbolic links located in the /sys/devices/system/node/node* directories. | |
179 | ||
180 | For example: | |
c04fc586 | 181 | /sys/devices/system/node/node0/memory9 -> ../../memory/memory9 |
6867c931 | 182 | |
dee5d0d5 AC |
183 | A backlink will also be created: |
184 | /sys/devices/system/memory/memory9/node0 -> ../../node/node0 | |
185 | ||
56a3c655 | 186 | |
6867c931 YG |
187 | -------------------------------- |
188 | 4. Physical memory hot-add phase | |
189 | -------------------------------- | |
190 | ||
191 | 4.1 Hardware(Firmware) Support | |
192 | ------------ | |
193 | On x86_64/ia64 platform, memory hotplug by ACPI is supported. | |
194 | ||
195 | In general, the firmware (ACPI) which supports memory hotplug defines | |
196 | memory class object of _HID "PNP0C80". When a notify is asserted to PNP0C80, | |
197 | Linux's ACPI handler does hot-add memory to the system and calls a hotplug udev | |
198 | script. This will be done automatically. | |
199 | ||
200 | But scripts for memory hotplug are not contained in generic udev package(now). | |
201 | You may have to write it by yourself or online/offline memory by hand. | |
202 | Please see "How to online memory", "How to offline memory" in this text. | |
203 | ||
204 | If firmware supports NUMA-node hotplug, and defines an object _HID "ACPI0004", | |
205 | "PNP0A05", or "PNP0A06", notification is asserted to it, and ACPI handler | |
206 | calls hotplug code for all of objects which are defined in it. | |
207 | If memory device is found, memory hotplug code will be called. | |
208 | ||
209 | ||
210 | 4.2 Notify memory hot-add event by hand | |
211 | ------------ | |
a0842b70 TK |
212 | On powerpc, the firmware does not notify a memory hotplug event to the kernel. |
213 | Therefore, "probe" interface is supported to notify the event to the kernel. | |
214 | This interface depends on CONFIG_ARCH_MEMORY_PROBE. | |
215 | ||
216 | CONFIG_ARCH_MEMORY_PROBE is supported on powerpc only. On x86, this config | |
217 | option is disabled by default since ACPI notifies a memory hotplug event to | |
218 | the kernel, which performs its hotplug operation as the result. Please | |
219 | enable this option if you need the "probe" interface for testing purposes | |
220 | on x86. | |
6867c931 YG |
221 | |
222 | Probe interface is located at | |
223 | /sys/devices/system/memory/probe | |
224 | ||
225 | You can tell the physical address of new memory to the kernel by | |
226 | ||
227 | % echo start_address_of_new_memory > /sys/devices/system/memory/probe | |
228 | ||
56a3c655 LZ |
229 | Then, [start_address_of_new_memory, start_address_of_new_memory + |
230 | memory_block_size] memory range is hot-added. In this case, hotplug script is | |
231 | not called (in current implementation). You'll have to online memory by | |
232 | yourself. Please see "How to online memory" in this text. | |
6867c931 YG |
233 | |
234 | ||
235 | ------------------------------ | |
236 | 5. Logical Memory hot-add phase | |
237 | ------------------------------ | |
238 | ||
239 | 5.1. State of memory | |
240 | ------------ | |
56a3c655 | 241 | To see (online/offline) state of a memory block, read 'state' file. |
6867c931 YG |
242 | |
243 | % cat /sys/device/system/memory/memoryXXX/state | |
244 | ||
245 | ||
56a3c655 LZ |
246 | If the memory block is online, you'll read "online". |
247 | If the memory block is offline, you'll read "offline". | |
6867c931 YG |
248 | |
249 | ||
250 | 5.2. How to online memory | |
251 | ------------ | |
252 | Even if the memory is hot-added, it is not at ready-to-use state. | |
56a3c655 | 253 | For using newly added memory, you have to "online" the memory block. |
6867c931 | 254 | |
56a3c655 | 255 | For onlining, you have to write "online" to the memory block's state file as: |
6867c931 YG |
256 | |
257 | % echo online > /sys/devices/system/memory/memoryXXX/state | |
258 | ||
56a3c655 LZ |
259 | This onlining will not change the ZONE type of the target memory block, |
260 | If the memory block is in ZONE_NORMAL, you can change it to ZONE_MOVABLE: | |
511c2aba LJ |
261 | |
262 | % echo online_movable > /sys/devices/system/memory/memoryXXX/state | |
56a3c655 | 263 | (NOTE: current limit: this memory block must be adjacent to ZONE_MOVABLE) |
511c2aba | 264 | |
56a3c655 | 265 | And if the memory block is in ZONE_MOVABLE, you can change it to ZONE_NORMAL: |
511c2aba LJ |
266 | |
267 | % echo online_kernel > /sys/devices/system/memory/memoryXXX/state | |
56a3c655 | 268 | (NOTE: current limit: this memory block must be adjacent to ZONE_NORMAL) |
511c2aba | 269 | |
56a3c655 | 270 | After this, memory block XXX's state will be 'online' and the amount of |
6867c931 YG |
271 | available memory will be increased. |
272 | ||
273 | Currently, newly added memory is added as ZONE_NORMAL (for powerpc, ZONE_DMA). | |
274 | This may be changed in future. | |
275 | ||
276 | ||
277 | ||
278 | ------------------------ | |
279 | 6. Logical memory remove | |
280 | ------------------------ | |
281 | ||
282 | 6.1 Memory offline and ZONE_MOVABLE | |
283 | ------------ | |
284 | Memory offlining is more complicated than memory online. Because memory offline | |
56a3c655 LZ |
285 | has to make the whole memory block be unused, memory offline can fail if |
286 | the memory block includes memory which cannot be freed. | |
6867c931 YG |
287 | |
288 | In general, memory offline can use 2 techniques. | |
289 | ||
56a3c655 LZ |
290 | (1) reclaim and free all memory in the memory block. |
291 | (2) migrate all pages in the memory block. | |
6867c931 YG |
292 | |
293 | In the current implementation, Linux's memory offline uses method (2), freeing | |
56a3c655 | 294 | all pages in the memory block by page migration. But not all pages are |
6867c931 | 295 | migratable. Under current Linux, migratable pages are anonymous pages and |
56a3c655 LZ |
296 | page caches. For offlining a memory block by migration, the kernel has to |
297 | guarantee that the memory block contains only migratable pages. | |
6867c931 | 298 | |
56a3c655 LZ |
299 | Now, a boot option for making a memory block which consists of migratable pages |
300 | is supported. By specifying "kernelcore=" or "movablecore=" boot option, you can | |
6867c931 YG |
301 | create ZONE_MOVABLE...a zone which is just used for movable pages. |
302 | (See also Documentation/kernel-parameters.txt) | |
303 | ||
304 | Assume the system has "TOTAL" amount of memory at boot time, this boot option | |
305 | creates ZONE_MOVABLE as following. | |
306 | ||
307 | 1) When kernelcore=YYYY boot option is used, | |
308 | Size of memory not for movable pages (not for offline) is YYYY. | |
309 | Size of memory for movable pages (for offline) is TOTAL-YYYY. | |
310 | ||
311 | 2) When movablecore=ZZZZ boot option is used, | |
312 | Size of memory not for movable pages (not for offline) is TOTAL - ZZZZ. | |
313 | Size of memory for movable pages (for offline) is ZZZZ. | |
314 | ||
315 | ||
56a3c655 | 316 | Note: Unfortunately, there is no information to show which memory block belongs |
6867c931 YG |
317 | to ZONE_MOVABLE. This is TBD. |
318 | ||
319 | ||
320 | 6.2. How to offline memory | |
321 | ------------ | |
56a3c655 LZ |
322 | You can offline a memory block by using the same sysfs interface that was used |
323 | in memory onlining. | |
6867c931 YG |
324 | |
325 | % echo offline > /sys/devices/system/memory/memoryXXX/state | |
326 | ||
56a3c655 | 327 | If offline succeeds, the state of the memory block is changed to be "offline". |
6867c931 | 328 | If it fails, some error core (like -EBUSY) will be returned by the kernel. |
56a3c655 LZ |
329 | Even if a memory block does not belong to ZONE_MOVABLE, you can try to offline |
330 | it. If it doesn't contain 'unmovable' memory, you'll get success. | |
6867c931 | 331 | |
56a3c655 LZ |
332 | A memory block under ZONE_MOVABLE is considered to be able to be offlined |
333 | easily. But under some busy state, it may return -EBUSY. Even if a memory | |
334 | block cannot be offlined due to -EBUSY, you can retry offlining it and may be | |
335 | able to offline it (or not). (For example, a page is referred to by some kernel | |
336 | internal call and released soon.) | |
6867c931 YG |
337 | |
338 | Consideration: | |
339 | Memory hotplug's design direction is to make the possibility of memory offlining | |
340 | higher and to guarantee unplugging memory under any situation. But it needs | |
341 | more work. Returning -EBUSY under some situation may be good because the user | |
342 | can decide to retry more or not by himself. Currently, memory offlining code | |
343 | does some amount of retry with 120 seconds timeout. | |
344 | ||
345 | ------------------------- | |
346 | 7. Physical memory remove | |
347 | ------------------------- | |
348 | Need more implementation yet.... | |
349 | - Notification completion of remove works by OS to firmware. | |
350 | - Guard from remove if not yet. | |
351 | ||
10020ca2 YG |
352 | -------------------------------- |
353 | 8. Memory hotplug event notifier | |
354 | -------------------------------- | |
c94bed8e | 355 | Memory hotplug has event notifier. There are 6 types of notification. |
10020ca2 YG |
356 | |
357 | MEMORY_GOING_ONLINE | |
358 | Generated before new memory becomes available in order to be able to | |
359 | prepare subsystems to handle memory. The page allocator is still unable | |
360 | to allocate from the new memory. | |
361 | ||
362 | MEMORY_CANCEL_ONLINE | |
363 | Generated if MEMORY_GOING_ONLINE fails. | |
364 | ||
365 | MEMORY_ONLINE | |
19f59460 | 366 | Generated when memory has successfully brought online. The callback may |
10020ca2 YG |
367 | allocate pages from the new memory. |
368 | ||
369 | MEMORY_GOING_OFFLINE | |
370 | Generated to begin the process of offlining memory. Allocations are no | |
371 | longer possible from the memory but some of the memory to be offlined | |
372 | is still in use. The callback can be used to free memory known to a | |
56a3c655 | 373 | subsystem from the indicated memory block. |
10020ca2 YG |
374 | |
375 | MEMORY_CANCEL_OFFLINE | |
376 | Generated if MEMORY_GOING_OFFLINE fails. Memory is available again from | |
56a3c655 | 377 | the memory block that we attempted to offline. |
10020ca2 YG |
378 | |
379 | MEMORY_OFFLINE | |
380 | Generated after offlining memory is complete. | |
381 | ||
382 | A callback routine can be registered by | |
383 | hotplug_memory_notifier(callback_func, priority) | |
384 | ||
385 | The second argument of callback function (action) is event types of above. | |
386 | The third argument is passed by pointer of struct memory_notify. | |
387 | ||
388 | struct memory_notify { | |
389 | unsigned long start_pfn; | |
390 | unsigned long nr_pages; | |
d9713679 | 391 | int status_change_nid_normal; |
6715ddf9 | 392 | int status_change_nid_high; |
19f59460 | 393 | int status_change_nid; |
10020ca2 YG |
394 | } |
395 | ||
396 | start_pfn is start_pfn of online/offline memory. | |
397 | nr_pages is # of pages of online/offline memory. | |
d9713679 LJ |
398 | status_change_nid_normal is set node id when N_NORMAL_MEMORY of nodemask |
399 | is (will be) set/clear, if this is -1, then nodemask status is not changed. | |
6715ddf9 LJ |
400 | status_change_nid_high is set node id when N_HIGH_MEMORY of nodemask |
401 | is (will be) set/clear, if this is -1, then nodemask status is not changed. | |
402 | status_change_nid is set node id when N_MEMORY of nodemask is (will be) | |
10020ca2 YG |
403 | set/clear. It means a new(memoryless) node gets new memory by online and a |
404 | node loses all memory. If this is -1, then nodemask status is not changed. | |
d9713679 | 405 | If status_changed_nid* >= 0, callback should create/discard structures for the |
10020ca2 YG |
406 | node if necessary. |
407 | ||
6867c931 | 408 | -------------- |
10020ca2 | 409 | 9. Future Work |
6867c931 YG |
410 | -------------- |
411 | - allowing memory hot-add to ZONE_MOVABLE. maybe we need some switch like | |
412 | sysctl or new control file. | |
56a3c655 LZ |
413 | - showing memory block and physical device relationship. |
414 | - showing memory block is under ZONE_MOVABLE or not | |
6867c931 YG |
415 | - test and make it better memory offlining. |
416 | - support HugeTLB page migration and offlining. | |
417 | - memmap removing at memory offline. | |
418 | - physical remove memory. | |
419 |