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