diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/cpu-hotplug.txt | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt new file mode 100644 index 000000000000..08c5d04f3086 --- /dev/null +++ b/Documentation/cpu-hotplug.txt | |||
@@ -0,0 +1,357 @@ | |||
1 | CPU hotplug Support in Linux(tm) Kernel | ||
2 | |||
3 | Maintainers: | ||
4 | CPU Hotplug Core: | ||
5 | Rusty Russell <rusty@rustycorp.com.au> | ||
6 | Srivatsa Vaddagiri <vatsa@in.ibm.com> | ||
7 | i386: | ||
8 | Zwane Mwaikambo <zwane@arm.linux.org.uk> | ||
9 | ppc64: | ||
10 | Nathan Lynch <nathanl@austin.ibm.com> | ||
11 | Joel Schopp <jschopp@austin.ibm.com> | ||
12 | ia64/x86_64: | ||
13 | Ashok Raj <ashok.raj@intel.com> | ||
14 | |||
15 | Authors: Ashok Raj <ashok.raj@intel.com> | ||
16 | Lots of feedback: Nathan Lynch <nathanl@austin.ibm.com>, | ||
17 | Joel Schopp <jschopp@austin.ibm.com> | ||
18 | |||
19 | Introduction | ||
20 | |||
21 | Modern advances in system architectures have introduced advanced error | ||
22 | reporting and correction capabilities in processors. CPU architectures permit | ||
23 | partitioning support, where compute resources of a single CPU could be made | ||
24 | available to virtual machine environments. There are couple OEMS that | ||
25 | support NUMA hardware which are hot pluggable as well, where physical | ||
26 | node insertion and removal require support for CPU hotplug. | ||
27 | |||
28 | Such advances require CPUs available to a kernel to be removed either for | ||
29 | provisioning reasons, or for RAS purposes to keep an offending CPU off | ||
30 | system execution path. Hence the need for CPU hotplug support in the | ||
31 | Linux kernel. | ||
32 | |||
33 | A more novel use of CPU-hotplug support is its use today in suspend | ||
34 | resume support for SMP. Dual-core and HT support makes even | ||
35 | a laptop run SMP kernels which didn't support these methods. SMP support | ||
36 | for suspend/resume is a work in progress. | ||
37 | |||
38 | General Stuff about CPU Hotplug | ||
39 | -------------------------------- | ||
40 | |||
41 | Command Line Switches | ||
42 | --------------------- | ||
43 | maxcpus=n Restrict boot time cpus to n. Say if you have 4 cpus, using | ||
44 | maxcpus=2 will only boot 2. You can choose to bring the | ||
45 | other cpus later online, read FAQ's for more info. | ||
46 | |||
47 | additional_cpus=n [x86_64 only] use this to limit hotpluggable cpus. | ||
48 | This option sets | ||
49 | cpu_possible_map = cpu_present_map + additional_cpus | ||
50 | |||
51 | CPU maps and such | ||
52 | ----------------- | ||
53 | [More on cpumaps and primitive to manipulate, please check | ||
54 | include/linux/cpumask.h that has more descriptive text.] | ||
55 | |||
56 | cpu_possible_map: Bitmap of possible CPUs that can ever be available in the | ||
57 | system. This is used to allocate some boot time memory for per_cpu variables | ||
58 | that aren't designed to grow/shrink as CPUs are made available or removed. | ||
59 | Once set during boot time discovery phase, the map is static, i.e no bits | ||
60 | are added or removed anytime. Trimming it accurately for your system needs | ||
61 | upfront can save some boot time memory. See below for how we use heuristics | ||
62 | in x86_64 case to keep this under check. | ||
63 | |||
64 | cpu_online_map: Bitmap of all CPUs currently online. Its set in __cpu_up() | ||
65 | after a cpu is available for kernel scheduling and ready to receive | ||
66 | interrupts from devices. Its cleared when a cpu is brought down using | ||
67 | __cpu_disable(), before which all OS services including interrupts are | ||
68 | migrated to another target CPU. | ||
69 | |||
70 | cpu_present_map: Bitmap of CPUs currently present in the system. Not all | ||
71 | of them may be online. When physical hotplug is processed by the relevant | ||
72 | subsystem (e.g ACPI) can change and new bit either be added or removed | ||
73 | from the map depending on the event is hot-add/hot-remove. There are currently | ||
74 | no locking rules as of now. Typical usage is to init topology during boot, | ||
75 | at which time hotplug is disabled. | ||
76 | |||
77 | You really dont need to manipulate any of the system cpu maps. They should | ||
78 | be read-only for most use. When setting up per-cpu resources almost always use | ||
79 | cpu_possible_map/for_each_cpu() to iterate. | ||
80 | |||
81 | Never use anything other than cpumask_t to represent bitmap of CPUs. | ||
82 | |||
83 | #include <linux/cpumask.h> | ||
84 | |||
85 | for_each_cpu - Iterate over cpu_possible_map | ||
86 | for_each_online_cpu - Iterate over cpu_online_map | ||
87 | for_each_present_cpu - Iterate over cpu_present_map | ||
88 | for_each_cpu_mask(x,mask) - Iterate over some random collection of cpu mask. | ||
89 | |||
90 | #include <linux/cpu.h> | ||
91 | lock_cpu_hotplug() and unlock_cpu_hotplug(): | ||
92 | |||
93 | The above calls are used to inhibit cpu hotplug operations. While holding the | ||
94 | cpucontrol mutex, cpu_online_map will not change. If you merely need to avoid | ||
95 | cpus going away, you could also use preempt_disable() and preempt_enable() | ||
96 | for those sections. Just remember the critical section cannot call any | ||
97 | function that can sleep or schedule this process away. The preempt_disable() | ||
98 | will work as long as stop_machine_run() is used to take a cpu down. | ||
99 | |||
100 | CPU Hotplug - Frequently Asked Questions. | ||
101 | |||
102 | Q: How to i enable my kernel to support CPU hotplug? | ||
103 | A: When doing make defconfig, Enable CPU hotplug support | ||
104 | |||
105 | "Processor type and Features" -> Support for Hotpluggable CPUs | ||
106 | |||
107 | Make sure that you have CONFIG_HOTPLUG, and CONFIG_SMP turned on as well. | ||
108 | |||
109 | You would need to enable CONFIG_HOTPLUG_CPU for SMP suspend/resume support | ||
110 | as well. | ||
111 | |||
112 | Q: What architectures support CPU hotplug? | ||
113 | A: As of 2.6.14, the following architectures support CPU hotplug. | ||
114 | |||
115 | i386 (Intel), ppc, ppc64, parisc, s390, ia64 and x86_64 | ||
116 | |||
117 | Q: How to test if hotplug is supported on the newly built kernel? | ||
118 | A: You should now notice an entry in sysfs. | ||
119 | |||
120 | Check if sysfs is mounted, using the "mount" command. You should notice | ||
121 | an entry as shown below in the output. | ||
122 | |||
123 | .... | ||
124 | none on /sys type sysfs (rw) | ||
125 | .... | ||
126 | |||
127 | if this is not mounted, do the following. | ||
128 | |||
129 | #mkdir /sysfs | ||
130 | #mount -t sysfs sys /sys | ||
131 | |||
132 | now you should see entries for all present cpu, the following is an example | ||
133 | in a 8-way system. | ||
134 | |||
135 | #pwd | ||
136 | #/sys/devices/system/cpu | ||
137 | #ls -l | ||
138 | total 0 | ||
139 | drwxr-xr-x 10 root root 0 Sep 19 07:44 . | ||
140 | drwxr-xr-x 13 root root 0 Sep 19 07:45 .. | ||
141 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu0 | ||
142 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu1 | ||
143 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu2 | ||
144 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu3 | ||
145 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu4 | ||
146 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu5 | ||
147 | drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu6 | ||
148 | drwxr-xr-x 3 root root 0 Sep 19 07:48 cpu7 | ||
149 | |||
150 | Under each directory you would find an "online" file which is the control | ||
151 | file to logically online/offline a processor. | ||
152 | |||
153 | Q: Does hot-add/hot-remove refer to physical add/remove of cpus? | ||
154 | A: The usage of hot-add/remove may not be very consistently used in the code. | ||
155 | CONFIG_CPU_HOTPLUG enables logical online/offline capability in the kernel. | ||
156 | To support physical addition/removal, one would need some BIOS hooks and | ||
157 | the platform should have something like an attention button in PCI hotplug. | ||
158 | CONFIG_ACPI_HOTPLUG_CPU enables ACPI support for physical add/remove of CPUs. | ||
159 | |||
160 | Q: How do i logically offline a CPU? | ||
161 | A: Do the following. | ||
162 | |||
163 | #echo 0 > /sys/devices/system/cpu/cpuX/online | ||
164 | |||
165 | once the logical offline is successful, check | ||
166 | |||
167 | #cat /proc/interrupts | ||
168 | |||
169 | you should now not see the CPU that you removed. Also online file will report | ||
170 | the state as 0 when a cpu if offline and 1 when its online. | ||
171 | |||
172 | #To display the current cpu state. | ||
173 | #cat /sys/devices/system/cpu/cpuX/online | ||
174 | |||
175 | Q: Why cant i remove CPU0 on some systems? | ||
176 | A: Some architectures may have some special dependency on a certain CPU. | ||
177 | |||
178 | For e.g in IA64 platforms we have ability to sent platform interrupts to the | ||
179 | OS. a.k.a Corrected Platform Error Interrupts (CPEI). In current ACPI | ||
180 | specifications, we didn't have a way to change the target CPU. Hence if the | ||
181 | current ACPI version doesn't support such re-direction, we disable that CPU | ||
182 | by making it not-removable. | ||
183 | |||
184 | In such cases you will also notice that the online file is missing under cpu0. | ||
185 | |||
186 | Q: How do i find out if a particular CPU is not removable? | ||
187 | A: Depending on the implementation, some architectures may show this by the | ||
188 | absence of the "online" file. This is done if it can be determined ahead of | ||
189 | time that this CPU cannot be removed. | ||
190 | |||
191 | In some situations, this can be a run time check, i.e if you try to remove the | ||
192 | last CPU, this will not be permitted. You can find such failures by | ||
193 | investigating the return value of the "echo" command. | ||
194 | |||
195 | Q: What happens when a CPU is being logically offlined? | ||
196 | A: The following happen, listed in no particular order :-) | ||
197 | |||
198 | - A notification is sent to in-kernel registered modules by sending an event | ||
199 | CPU_DOWN_PREPARE | ||
200 | - All process is migrated away from this outgoing CPU to a new CPU | ||
201 | - All interrupts targeted to this CPU is migrated to a new CPU | ||
202 | - timers/bottom half/task lets are also migrated to a new CPU | ||
203 | - Once all services are migrated, kernel calls an arch specific routine | ||
204 | __cpu_disable() to perform arch specific cleanup. | ||
205 | - Once this is successful, an event for successful cleanup is sent by an event | ||
206 | CPU_DEAD. | ||
207 | |||
208 | "It is expected that each service cleans up when the CPU_DOWN_PREPARE | ||
209 | notifier is called, when CPU_DEAD is called its expected there is nothing | ||
210 | running on behalf of this CPU that was offlined" | ||
211 | |||
212 | Q: If i have some kernel code that needs to be aware of CPU arrival and | ||
213 | departure, how to i arrange for proper notification? | ||
214 | A: This is what you would need in your kernel code to receive notifications. | ||
215 | |||
216 | #include <linux/cpu.h> | ||
217 | static int __cpuinit foobar_cpu_callback(struct notifier_block *nfb, | ||
218 | unsigned long action, void *hcpu) | ||
219 | { | ||
220 | unsigned int cpu = (unsigned long)hcpu; | ||
221 | |||
222 | switch (action) { | ||
223 | case CPU_ONLINE: | ||
224 | foobar_online_action(cpu); | ||
225 | break; | ||
226 | case CPU_DEAD: | ||
227 | foobar_dead_action(cpu); | ||
228 | break; | ||
229 | } | ||
230 | return NOTIFY_OK; | ||
231 | } | ||
232 | |||
233 | static struct notifier_block foobar_cpu_notifer = | ||
234 | { | ||
235 | .notifier_call = foobar_cpu_callback, | ||
236 | }; | ||
237 | |||
238 | |||
239 | In your init function, | ||
240 | |||
241 | register_cpu_notifier(&foobar_cpu_notifier); | ||
242 | |||
243 | You can fail PREPARE notifiers if something doesn't work to prepare resources. | ||
244 | This will stop the activity and send a following CANCELED event back. | ||
245 | |||
246 | CPU_DEAD should not be failed, its just a goodness indication, but bad | ||
247 | things will happen if a notifier in path sent a BAD notify code. | ||
248 | |||
249 | Q: I don't see my action being called for all CPUs already up and running? | ||
250 | A: Yes, CPU notifiers are called only when new CPUs are on-lined or offlined. | ||
251 | If you need to perform some action for each cpu already in the system, then | ||
252 | |||
253 | for_each_online_cpu(i) { | ||
254 | foobar_cpu_callback(&foobar_cpu_notifier, CPU_UP_PREPARE, i); | ||
255 | foobar_cpu_callback(&foobar-cpu_notifier, CPU_ONLINE, i); | ||
256 | } | ||
257 | |||
258 | Q: If i would like to develop cpu hotplug support for a new architecture, | ||
259 | what do i need at a minimum? | ||
260 | A: The following are what is required for CPU hotplug infrastructure to work | ||
261 | correctly. | ||
262 | |||
263 | - Make sure you have an entry in Kconfig to enable CONFIG_HOTPLUG_CPU | ||
264 | - __cpu_up() - Arch interface to bring up a CPU | ||
265 | - __cpu_disable() - Arch interface to shutdown a CPU, no more interrupts | ||
266 | can be handled by the kernel after the routine | ||
267 | returns. Including local APIC timers etc are | ||
268 | shutdown. | ||
269 | - __cpu_die() - This actually supposed to ensure death of the CPU. | ||
270 | Actually look at some example code in other arch | ||
271 | that implement CPU hotplug. The processor is taken | ||
272 | down from the idle() loop for that specific | ||
273 | architecture. __cpu_die() typically waits for some | ||
274 | per_cpu state to be set, to ensure the processor | ||
275 | dead routine is called to be sure positively. | ||
276 | |||
277 | Q: I need to ensure that a particular cpu is not removed when there is some | ||
278 | work specific to this cpu is in progress. | ||
279 | A: First switch the current thread context to preferred cpu | ||
280 | |||
281 | int my_func_on_cpu(int cpu) | ||
282 | { | ||
283 | cpumask_t saved_mask, new_mask = CPU_MASK_NONE; | ||
284 | int curr_cpu, err = 0; | ||
285 | |||
286 | saved_mask = current->cpus_allowed; | ||
287 | cpu_set(cpu, new_mask); | ||
288 | err = set_cpus_allowed(current, new_mask); | ||
289 | |||
290 | if (err) | ||
291 | return err; | ||
292 | |||
293 | /* | ||
294 | * If we got scheduled out just after the return from | ||
295 | * set_cpus_allowed() before running the work, this ensures | ||
296 | * we stay locked. | ||
297 | */ | ||
298 | curr_cpu = get_cpu(); | ||
299 | |||
300 | if (curr_cpu != cpu) { | ||
301 | err = -EAGAIN; | ||
302 | goto ret; | ||
303 | } else { | ||
304 | /* | ||
305 | * Do work : But cant sleep, since get_cpu() disables preempt | ||
306 | */ | ||
307 | } | ||
308 | ret: | ||
309 | put_cpu(); | ||
310 | set_cpus_allowed(current, saved_mask); | ||
311 | return err; | ||
312 | } | ||
313 | |||
314 | |||
315 | Q: How do we determine how many CPUs are available for hotplug. | ||
316 | A: There is no clear spec defined way from ACPI that can give us that | ||
317 | information today. Based on some input from Natalie of Unisys, | ||
318 | that the ACPI MADT (Multiple APIC Description Tables) marks those possible | ||
319 | CPUs in a system with disabled status. | ||
320 | |||
321 | Andi implemented some simple heuristics that count the number of disabled | ||
322 | CPUs in MADT as hotpluggable CPUS. In the case there are no disabled CPUS | ||
323 | we assume 1/2 the number of CPUs currently present can be hotplugged. | ||
324 | |||
325 | Caveat: Today's ACPI MADT can only provide 256 entries since the apicid field | ||
326 | in MADT is only 8 bits. | ||
327 | |||
328 | User Space Notification | ||
329 | |||
330 | Hotplug support for devices is common in Linux today. Its being used today to | ||
331 | support automatic configuration of network, usb and pci devices. A hotplug | ||
332 | event can be used to invoke an agent script to perform the configuration task. | ||
333 | |||
334 | You can add /etc/hotplug/cpu.agent to handle hotplug notification user space | ||
335 | scripts. | ||
336 | |||
337 | #!/bin/bash | ||
338 | # $Id: cpu.agent | ||
339 | # Kernel hotplug params include: | ||
340 | #ACTION=%s [online or offline] | ||
341 | #DEVPATH=%s | ||
342 | # | ||
343 | cd /etc/hotplug | ||
344 | . ./hotplug.functions | ||
345 | |||
346 | case $ACTION in | ||
347 | online) | ||
348 | echo `date` ":cpu.agent" add cpu >> /tmp/hotplug.txt | ||
349 | ;; | ||
350 | offline) | ||
351 | echo `date` ":cpu.agent" remove cpu >>/tmp/hotplug.txt | ||
352 | ;; | ||
353 | *) | ||
354 | debug_mesg CPU $ACTION event not supported | ||
355 | exit 1 | ||
356 | ;; | ||
357 | esac | ||