Ashok Raj | c809406 | 2006-01-08 01:03:17 -0800 | [diff] [blame] | 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> |
Heiko Carstens | 255acee | 2006-02-17 13:52:46 -0800 | [diff] [blame^] | 14 | s390: |
| 15 | Heiko Carstens <heiko.carstens@de.ibm.com> |
Ashok Raj | c809406 | 2006-01-08 01:03:17 -0800 | [diff] [blame] | 16 | |
| 17 | Authors: Ashok Raj <ashok.raj@intel.com> |
| 18 | Lots of feedback: Nathan Lynch <nathanl@austin.ibm.com>, |
| 19 | Joel Schopp <jschopp@austin.ibm.com> |
| 20 | |
| 21 | Introduction |
| 22 | |
| 23 | Modern advances in system architectures have introduced advanced error |
| 24 | reporting and correction capabilities in processors. CPU architectures permit |
| 25 | partitioning support, where compute resources of a single CPU could be made |
| 26 | available to virtual machine environments. There are couple OEMS that |
| 27 | support NUMA hardware which are hot pluggable as well, where physical |
| 28 | node insertion and removal require support for CPU hotplug. |
| 29 | |
| 30 | Such advances require CPUs available to a kernel to be removed either for |
| 31 | provisioning reasons, or for RAS purposes to keep an offending CPU off |
| 32 | system execution path. Hence the need for CPU hotplug support in the |
| 33 | Linux kernel. |
| 34 | |
| 35 | A more novel use of CPU-hotplug support is its use today in suspend |
| 36 | resume support for SMP. Dual-core and HT support makes even |
| 37 | a laptop run SMP kernels which didn't support these methods. SMP support |
| 38 | for suspend/resume is a work in progress. |
| 39 | |
| 40 | General Stuff about CPU Hotplug |
| 41 | -------------------------------- |
| 42 | |
| 43 | Command Line Switches |
| 44 | --------------------- |
| 45 | maxcpus=n Restrict boot time cpus to n. Say if you have 4 cpus, using |
| 46 | maxcpus=2 will only boot 2. You can choose to bring the |
| 47 | other cpus later online, read FAQ's for more info. |
| 48 | |
Heiko Carstens | 255acee | 2006-02-17 13:52:46 -0800 | [diff] [blame^] | 49 | additional_cpus=n [x86_64, s390 only] use this to limit hotpluggable cpus. |
| 50 | This option sets |
| 51 | cpu_possible_map = cpu_present_map + additional_cpus |
Ashok Raj | 8f8b113 | 2006-02-16 14:01:48 -0800 | [diff] [blame] | 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 | |
Ashok Raj | c809406 | 2006-01-08 01:03:17 -0800 | [diff] [blame] | 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 |