Root/
1 | ============== |
2 | Memory Hotplug |
3 | ============== |
4 | |
5 | Created: Jul 28 2007 |
6 | Add description of notifier of memory hotplug Oct 11 2007 |
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 |
28 | 8. Memory hotplug event notifier |
29 | 9. Future Work List |
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 |
76 | available/unavailable for users. Amount of memory from user's view is |
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 | |
82 | Logical Memory Hotplug phase is triggered by write of sysfs file by system |
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 | ------------ |
91 | Memory hotplug uses SPARSEMEM memory model. SPARSEMEM divides the whole memory |
92 | into chunks of the same size. The chunk is called a "section". The size of |
93 | a section is architecture dependent. For example, power uses 16MiB, ia64 uses |
94 | 1GiB. The unit of online/offline operation is "one section". (see Section 3.) |
95 | |
96 | To determine the size of sections, please read this file: |
97 | |
98 | /sys/devices/system/memory/block_size_bytes |
99 | |
100 | This file shows the size of sections in byte. |
101 | |
102 | ----------------------- |
103 | 2. Kernel Configuration |
104 | ----------------------- |
105 | To use memory hotplug feature, kernel must be compiled with following |
106 | config options. |
107 | |
108 | - For all memory hotplug |
109 | Memory model -> Sparse Memory (CONFIG_SPARSEMEM) |
110 | Allow for memory hot-add (CONFIG_MEMORY_HOTPLUG) |
111 | |
112 | - To enable memory removal, the followings are also necessary |
113 | Allow for memory hot remove (CONFIG_MEMORY_HOTREMOVE) |
114 | Page Migration (CONFIG_MIGRATION) |
115 | |
116 | - For ACPI memory hotplug, the followings are also necessary |
117 | Memory hotplug (under ACPI Support menu) (CONFIG_ACPI_HOTPLUG_MEMORY) |
118 | This option can be kernel module. |
119 | |
120 | - As a related configuration, if your box has a feature of NUMA-node hotplug |
121 | via ACPI, then this option is necessary too. |
122 | ACPI0004,PNP0A05 and PNP0A06 Container Driver (under ACPI Support menu) |
123 | (CONFIG_ACPI_CONTAINER). |
124 | This option can be kernel module too. |
125 | |
126 | -------------------------------- |
127 | 4 sysfs files for memory hotplug |
128 | -------------------------------- |
129 | All sections have their device information in sysfs. Each section is part of |
130 | a memory block under /sys/devices/system/memory as |
131 | |
132 | /sys/devices/system/memory/memoryXXX |
133 | (XXX is the section id.) |
134 | |
135 | Now, XXX is defined as (start_address_of_section / section_size) of the first |
136 | section contained in the memory block. The files 'phys_index' and |
137 | 'end_phys_index' under each directory report the beginning and end section id's |
138 | for the memory block covered by the sysfs directory. It is expected that all |
139 | memory sections in this range are present and no memory holes exist in the |
140 | range. Currently there is no way to determine if there is a memory hole, but |
141 | the existence of one should not affect the hotplug capabilities of the memory |
142 | block. |
143 | |
144 | For example, assume 1GiB section size. A device for a memory starting at |
145 | 0x100000000 is /sys/device/system/memory/memory4 |
146 | (0x100000000 / 1Gib = 4) |
147 | This device covers address range [0x100000000 ... 0x140000000) |
148 | |
149 | Under each section, you can see 4 or 5 files, the end_phys_index file being |
150 | a recent addition and not present on older kernels. |
151 | |
152 | /sys/devices/system/memory/memoryXXX/start_phys_index |
153 | /sys/devices/system/memory/memoryXXX/end_phys_index |
154 | /sys/devices/system/memory/memoryXXX/phys_device |
155 | /sys/devices/system/memory/memoryXXX/state |
156 | /sys/devices/system/memory/memoryXXX/removable |
157 | |
158 | 'phys_index' : read-only and contains section id of the first section |
159 | in the memory block, same as XXX. |
160 | 'end_phys_index' : read-only and contains section id of the last section |
161 | in the memory block. |
162 | 'state' : read-write |
163 | at read: contains online/offline state of memory. |
164 | at write: user can specify "online_kernel", |
165 | "online_movable", "online", "offline" command |
166 | which will be performed on all sections in the block. |
167 | 'phys_device' : read-only: designed to show the name of physical memory |
168 | device. This is not well implemented now. |
169 | 'removable' : read-only: contains an integer value indicating |
170 | whether the memory block is removable or not |
171 | removable. A value of 1 indicates that the memory |
172 | block is removable and a value of 0 indicates that |
173 | it is not removable. A memory block is removable only if |
174 | every section in the block is removable. |
175 | |
176 | NOTE: |
177 | These directories/files appear after physical memory hotplug phase. |
178 | |
179 | If CONFIG_NUMA is enabled the memoryXXX/ directories can also be accessed |
180 | via symbolic links located in the /sys/devices/system/node/node* directories. |
181 | |
182 | For example: |
183 | /sys/devices/system/node/node0/memory9 -> ../../memory/memory9 |
184 | |
185 | A backlink will also be created: |
186 | /sys/devices/system/memory/memory9/node0 -> ../../node/node0 |
187 | |
188 | -------------------------------- |
189 | 4. Physical memory hot-add phase |
190 | -------------------------------- |
191 | |
192 | 4.1 Hardware(Firmware) Support |
193 | ------------ |
194 | On x86_64/ia64 platform, memory hotplug by ACPI is supported. |
195 | |
196 | In general, the firmware (ACPI) which supports memory hotplug defines |
197 | memory class object of _HID "PNP0C80". When a notify is asserted to PNP0C80, |
198 | Linux's ACPI handler does hot-add memory to the system and calls a hotplug udev |
199 | script. This will be done automatically. |
200 | |
201 | But scripts for memory hotplug are not contained in generic udev package(now). |
202 | You may have to write it by yourself or online/offline memory by hand. |
203 | Please see "How to online memory", "How to offline memory" in this text. |
204 | |
205 | If firmware supports NUMA-node hotplug, and defines an object _HID "ACPI0004", |
206 | "PNP0A05", or "PNP0A06", notification is asserted to it, and ACPI handler |
207 | calls hotplug code for all of objects which are defined in it. |
208 | If memory device is found, memory hotplug code will be called. |
209 | |
210 | |
211 | 4.2 Notify memory hot-add event by hand |
212 | ------------ |
213 | On powerpc, the firmware does not notify a memory hotplug event to the kernel. |
214 | Therefore, "probe" interface is supported to notify the event to the kernel. |
215 | This interface depends on CONFIG_ARCH_MEMORY_PROBE. |
216 | |
217 | CONFIG_ARCH_MEMORY_PROBE is supported on powerpc only. On x86, this config |
218 | option is disabled by default since ACPI notifies a memory hotplug event to |
219 | the kernel, which performs its hotplug operation as the result. Please |
220 | enable this option if you need the "probe" interface for testing purposes |
221 | on x86. |
222 | |
223 | Probe interface is located at |
224 | /sys/devices/system/memory/probe |
225 | |
226 | You can tell the physical address of new memory to the kernel by |
227 | |
228 | % echo start_address_of_new_memory > /sys/devices/system/memory/probe |
229 | |
230 | Then, [start_address_of_new_memory, start_address_of_new_memory + section_size) |
231 | memory range is hot-added. In this case, hotplug script is not called (in |
232 | current implementation). You'll have to online memory by yourself. |
233 | Please see "How to online memory" in this text. |
234 | |
235 | |
236 | |
237 | ------------------------------ |
238 | 5. Logical Memory hot-add phase |
239 | ------------------------------ |
240 | |
241 | 5.1. State of memory |
242 | ------------ |
243 | To see (online/offline) state of memory section, read 'state' file. |
244 | |
245 | % cat /sys/device/system/memory/memoryXXX/state |
246 | |
247 | |
248 | If the memory section is online, you'll read "online". |
249 | If the memory section is offline, you'll read "offline". |
250 | |
251 | |
252 | 5.2. How to online memory |
253 | ------------ |
254 | Even if the memory is hot-added, it is not at ready-to-use state. |
255 | For using newly added memory, you have to "online" the memory section. |
256 | |
257 | For onlining, you have to write "online" to the section's state file as: |
258 | |
259 | % echo online > /sys/devices/system/memory/memoryXXX/state |
260 | |
261 | This onlining will not change the ZONE type of the target memory section, |
262 | If the memory section is in ZONE_NORMAL, you can change it to ZONE_MOVABLE: |
263 | |
264 | % echo online_movable > /sys/devices/system/memory/memoryXXX/state |
265 | (NOTE: current limit: this memory section must be adjacent to ZONE_MOVABLE) |
266 | |
267 | And if the memory section is in ZONE_MOVABLE, you can change it to ZONE_NORMAL: |
268 | |
269 | % echo online_kernel > /sys/devices/system/memory/memoryXXX/state |
270 | (NOTE: current limit: this memory section must be adjacent to ZONE_NORMAL) |
271 | |
272 | After this, section memoryXXX's state will be 'online' and the amount of |
273 | available memory will be increased. |
274 | |
275 | Currently, newly added memory is added as ZONE_NORMAL (for powerpc, ZONE_DMA). |
276 | This may be changed in future. |
277 | |
278 | |
279 | |
280 | ------------------------ |
281 | 6. Logical memory remove |
282 | ------------------------ |
283 | |
284 | 6.1 Memory offline and ZONE_MOVABLE |
285 | ------------ |
286 | Memory offlining is more complicated than memory online. Because memory offline |
287 | has to make the whole memory section be unused, memory offline can fail if |
288 | the section includes memory which cannot be freed. |
289 | |
290 | In general, memory offline can use 2 techniques. |
291 | |
292 | (1) reclaim and free all memory in the section. |
293 | (2) migrate all pages in the section. |
294 | |
295 | In the current implementation, Linux's memory offline uses method (2), freeing |
296 | all pages in the section by page migration. But not all pages are |
297 | migratable. Under current Linux, migratable pages are anonymous pages and |
298 | page caches. For offlining a section by migration, the kernel has to guarantee |
299 | that the section contains only migratable pages. |
300 | |
301 | Now, a boot option for making a section which consists of migratable pages is |
302 | supported. By specifying "kernelcore=" or "movablecore=" boot option, you can |
303 | create ZONE_MOVABLE...a zone which is just used for movable pages. |
304 | (See also Documentation/kernel-parameters.txt) |
305 | |
306 | Assume the system has "TOTAL" amount of memory at boot time, this boot option |
307 | creates ZONE_MOVABLE as following. |
308 | |
309 | 1) When kernelcore=YYYY boot option is used, |
310 | Size of memory not for movable pages (not for offline) is YYYY. |
311 | Size of memory for movable pages (for offline) is TOTAL-YYYY. |
312 | |
313 | 2) When movablecore=ZZZZ boot option is used, |
314 | Size of memory not for movable pages (not for offline) is TOTAL - ZZZZ. |
315 | Size of memory for movable pages (for offline) is ZZZZ. |
316 | |
317 | |
318 | Note) Unfortunately, there is no information to show which section belongs |
319 | to ZONE_MOVABLE. This is TBD. |
320 | |
321 | |
322 | 6.2. How to offline memory |
323 | ------------ |
324 | You can offline a section by using the same sysfs interface that was used in |
325 | memory onlining. |
326 | |
327 | % echo offline > /sys/devices/system/memory/memoryXXX/state |
328 | |
329 | If offline succeeds, the state of the memory section is changed to be "offline". |
330 | If it fails, some error core (like -EBUSY) will be returned by the kernel. |
331 | Even if a section does not belong to ZONE_MOVABLE, you can try to offline it. |
332 | If it doesn't contain 'unmovable' memory, you'll get success. |
333 | |
334 | A section under ZONE_MOVABLE is considered to be able to be offlined easily. |
335 | But under some busy state, it may return -EBUSY. Even if a memory section |
336 | cannot be offlined due to -EBUSY, you can retry offlining it and may be able to |
337 | offline it (or not). |
338 | (For example, a page is referred to by some kernel internal call and released |
339 | soon.) |
340 | |
341 | Consideration: |
342 | Memory hotplug's design direction is to make the possibility of memory offlining |
343 | higher and to guarantee unplugging memory under any situation. But it needs |
344 | more work. Returning -EBUSY under some situation may be good because the user |
345 | can decide to retry more or not by himself. Currently, memory offlining code |
346 | does some amount of retry with 120 seconds timeout. |
347 | |
348 | ------------------------- |
349 | 7. Physical memory remove |
350 | ------------------------- |
351 | Need more implementation yet.... |
352 | - Notification completion of remove works by OS to firmware. |
353 | - Guard from remove if not yet. |
354 | |
355 | -------------------------------- |
356 | 8. Memory hotplug event notifier |
357 | -------------------------------- |
358 | Memory hotplug has event notifier. There are 6 types of notification. |
359 | |
360 | MEMORY_GOING_ONLINE |
361 | Generated before new memory becomes available in order to be able to |
362 | prepare subsystems to handle memory. The page allocator is still unable |
363 | to allocate from the new memory. |
364 | |
365 | MEMORY_CANCEL_ONLINE |
366 | Generated if MEMORY_GOING_ONLINE fails. |
367 | |
368 | MEMORY_ONLINE |
369 | Generated when memory has successfully brought online. The callback may |
370 | allocate pages from the new memory. |
371 | |
372 | MEMORY_GOING_OFFLINE |
373 | Generated to begin the process of offlining memory. Allocations are no |
374 | longer possible from the memory but some of the memory to be offlined |
375 | is still in use. The callback can be used to free memory known to a |
376 | subsystem from the indicated memory section. |
377 | |
378 | MEMORY_CANCEL_OFFLINE |
379 | Generated if MEMORY_GOING_OFFLINE fails. Memory is available again from |
380 | the section that we attempted to offline. |
381 | |
382 | MEMORY_OFFLINE |
383 | Generated after offlining memory is complete. |
384 | |
385 | A callback routine can be registered by |
386 | hotplug_memory_notifier(callback_func, priority) |
387 | |
388 | The second argument of callback function (action) is event types of above. |
389 | The third argument is passed by pointer of struct memory_notify. |
390 | |
391 | struct memory_notify { |
392 | unsigned long start_pfn; |
393 | unsigned long nr_pages; |
394 | int status_change_nid_normal; |
395 | int status_change_nid_high; |
396 | int status_change_nid; |
397 | } |
398 | |
399 | start_pfn is start_pfn of online/offline memory. |
400 | nr_pages is # of pages of online/offline memory. |
401 | status_change_nid_normal is set node id when N_NORMAL_MEMORY of nodemask |
402 | is (will be) set/clear, if this is -1, then nodemask status is not changed. |
403 | status_change_nid_high is set node id when N_HIGH_MEMORY of nodemask |
404 | is (will be) set/clear, if this is -1, then nodemask status is not changed. |
405 | status_change_nid is set node id when N_MEMORY of nodemask is (will be) |
406 | set/clear. It means a new(memoryless) node gets new memory by online and a |
407 | node loses all memory. If this is -1, then nodemask status is not changed. |
408 | If status_changed_nid* >= 0, callback should create/discard structures for the |
409 | node if necessary. |
410 | |
411 | -------------- |
412 | 9. Future Work |
413 | -------------- |
414 | - allowing memory hot-add to ZONE_MOVABLE. maybe we need some switch like |
415 | sysctl or new control file. |
416 | - showing memory section and physical device relationship. |
417 | - showing memory section is under ZONE_MOVABLE or not |
418 | - test and make it better memory offlining. |
419 | - support HugeTLB page migration and offlining. |
420 | - memmap removing at memory offline. |
421 | - physical remove memory. |
422 | |
423 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9