Back to home page




0001                 CPU hotplug Support in Linux(tm) Kernel
0003                 Maintainers:
0004                 CPU Hotplug Core:
0005                         Rusty Russell <>
0006                         Srivatsa Vaddagiri <>
0007                 i386:
0008                         Zwane Mwaikambo <>
0009                 ppc64:
0010                         Nathan Lynch <>
0011                         Joel Schopp <>
0012                 ia64/x86_64:
0013                         Ashok Raj <>
0014                 s390:
0015                         Heiko Carstens <>
0017 Authors: Ashok Raj <>
0018 Lots of feedback: Nathan Lynch <>,
0019              Joel Schopp <>
0021 Introduction
0023 Modern advances in system architectures have introduced advanced error
0024 reporting and correction capabilities in processors. CPU architectures permit
0025 partitioning support, where compute resources of a single CPU could be made
0026 available to virtual machine environments. There are couple OEMS that
0027 support NUMA hardware which are hot pluggable as well, where physical
0028 node insertion and removal require support for CPU hotplug.
0030 Such advances require CPUs available to a kernel to be removed either for
0031 provisioning reasons, or for RAS purposes to keep an offending CPU off
0032 system execution path. Hence the need for CPU hotplug support in the
0033 Linux kernel.
0035 A more novel use of CPU-hotplug support is its use today in suspend
0036 resume support for SMP. Dual-core and HT support makes even
0037 a laptop run SMP kernels which didn't support these methods. SMP support
0038 for suspend/resume is a work in progress.
0040 General Stuff about CPU Hotplug
0041 --------------------------------
0043 Command Line Switches
0044 ---------------------
0045 maxcpus=n    Restrict boot time cpus to n. Say if you have 4 cpus, using
0046              maxcpus=2 will only boot 2. You can choose to bring the
0047              other cpus later online, read FAQ's for more info.
0049 additional_cpus=n (*)   Use this to limit hotpluggable cpus. This option sets
0050                         cpu_possible_mask = cpu_present_mask + additional_cpus
0052 cede_offline={"off","on"}  Use this option to disable/enable putting offlined
0053                             processors to an extended H_CEDE state on
0054                             supported pseries platforms.
0055                             If nothing is specified,
0056                             cede_offline is set to "on".
0058 (*) Option valid only for following architectures
0059 - ia64
0061 ia64 uses the number of disabled local apics in ACPI tables MADT to
0062 determine the number of potentially hot-pluggable cpus. The implementation
0063 should only rely on this to count the # of cpus, but *MUST* not rely
0064 on the apicid values in those tables for disabled apics. In the event
0065 BIOS doesn't mark such hot-pluggable cpus as disabled entries, one could
0066 use this parameter "additional_cpus=x" to represent those cpus in the
0067 cpu_possible_mask.
0069 possible_cpus=n         [s390,x86_64] use this to set hotpluggable cpus.
0070                         This option sets possible_cpus bits in
0071                         cpu_possible_mask. Thus keeping the numbers of bits set
0072                         constant even if the machine gets rebooted.
0074 CPU maps and such
0075 -----------------
0076 [More on cpumaps and primitive to manipulate, please check
0077 include/linux/cpumask.h that has more descriptive text.]
0079 cpu_possible_mask: Bitmap of possible CPUs that can ever be available in the
0080 system. This is used to allocate some boot time memory for per_cpu variables
0081 that aren't designed to grow/shrink as CPUs are made available or removed.
0082 Once set during boot time discovery phase, the map is static, i.e no bits
0083 are added or removed anytime.  Trimming it accurately for your system needs
0084 upfront can save some boot time memory. See below for how we use heuristics
0085 in x86_64 case to keep this under check.
0087 cpu_online_mask: Bitmap of all CPUs currently online. It's set in __cpu_up()
0088 after a CPU is available for kernel scheduling and ready to receive
0089 interrupts from devices. It's cleared when a CPU is brought down using
0090 __cpu_disable(), before which all OS services including interrupts are
0091 migrated to another target CPU.
0093 cpu_present_mask: Bitmap of CPUs currently present in the system. Not all
0094 of them may be online. When physical hotplug is processed by the relevant
0095 subsystem (e.g ACPI) can change and new bit either be added or removed
0096 from the map depending on the event is hot-add/hot-remove. There are currently
0097 no locking rules as of now. Typical usage is to init topology during boot,
0098 at which time hotplug is disabled.
0100 You really dont need to manipulate any of the system cpu maps. They should
0101 be read-only for most use. When setting up per-cpu resources almost always use
0102 cpu_possible_mask/for_each_possible_cpu() to iterate.
0104 Never use anything other than cpumask_t to represent bitmap of CPUs.
0106         #include <linux/cpumask.h>
0108         for_each_possible_cpu     - Iterate over cpu_possible_mask
0109         for_each_online_cpu       - Iterate over cpu_online_mask
0110         for_each_present_cpu      - Iterate over cpu_present_mask
0111         for_each_cpu(x,mask)      - Iterate over some random collection of cpu mask.
0113         #include <linux/cpu.h>
0114         get_online_cpus() and put_online_cpus():
0116 The above calls are used to inhibit cpu hotplug operations. While the
0117 cpu_hotplug.refcount is non zero, the cpu_online_mask will not change.
0118 If you merely need to avoid cpus going away, you could also use
0119 preempt_disable() and preempt_enable() for those sections.
0120 Just remember the critical section cannot call any
0121 function that can sleep or schedule this process away. The preempt_disable()
0122 will work as long as stop_machine_run() is used to take a cpu down.
0124 CPU Hotplug - Frequently Asked Questions.
0126 Q: How to enable my kernel to support CPU hotplug?
0127 A: When doing make defconfig, Enable CPU hotplug support
0129    "Processor type and Features" -> Support for Hotpluggable CPUs
0131 Make sure that you have CONFIG_SMP turned on as well.
0133 You would need to enable CONFIG_HOTPLUG_CPU for SMP suspend/resume support
0134 as well.
0136 Q: What architectures support CPU hotplug?
0137 A: As of 2.6.14, the following architectures support CPU hotplug.
0139 i386 (Intel), ppc, ppc64, parisc, s390, ia64 and x86_64
0141 Q: How to test if hotplug is supported on the newly built kernel?
0142 A: You should now notice an entry in sysfs.
0144 Check if sysfs is mounted, using the "mount" command. You should notice
0145 an entry as shown below in the output.
0147         ....
0148         none on /sys type sysfs (rw)
0149         ....
0151 If this is not mounted, do the following.
0153         #mkdir /sys
0154         #mount -t sysfs sys /sys
0156 Now you should see entries for all present cpu, the following is an example
0157 in a 8-way system.
0159         #pwd
0160         #/sys/devices/system/cpu
0161         #ls -l
0162         total 0
0163         drwxr-xr-x  10 root root 0 Sep 19 07:44 .
0164         drwxr-xr-x  13 root root 0 Sep 19 07:45 ..
0165         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu0
0166         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu1
0167         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu2
0168         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu3
0169         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu4
0170         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu5
0171         drwxr-xr-x   3 root root 0 Sep 19 07:44 cpu6
0172         drwxr-xr-x   3 root root 0 Sep 19 07:48 cpu7
0174 Under each directory you would find an "online" file which is the control
0175 file to logically online/offline a processor.
0177 Q: Does hot-add/hot-remove refer to physical add/remove of cpus?
0178 A: The usage of hot-add/remove may not be very consistently used in the code.
0179 CONFIG_HOTPLUG_CPU enables logical online/offline capability in the kernel.
0180 To support physical addition/removal, one would need some BIOS hooks and
0181 the platform should have something like an attention button in PCI hotplug.
0182 CONFIG_ACPI_HOTPLUG_CPU enables ACPI support for physical add/remove of CPUs.
0184 Q: How do I logically offline a CPU?
0185 A: Do the following.
0187         #echo 0 > /sys/devices/system/cpu/cpuX/online
0189 Once the logical offline is successful, check
0191         #cat /proc/interrupts
0193 You should now not see the CPU that you removed. Also online file will report
0194 the state as 0 when a CPU is offline and 1 when it's online.
0196         #To display the current cpu state.
0197         #cat /sys/devices/system/cpu/cpuX/online
0199 Q: Why can't I remove CPU0 on some systems?
0200 A: Some architectures may have some special dependency on a certain CPU.
0202 For e.g in IA64 platforms we have ability to send platform interrupts to the
0203 OS. a.k.a Corrected Platform Error Interrupts (CPEI). In current ACPI
0204 specifications, we didn't have a way to change the target CPU. Hence if the
0205 current ACPI version doesn't support such re-direction, we disable that CPU
0206 by making it not-removable.
0208 In such cases you will also notice that the online file is missing under cpu0.
0210 Q: Is CPU0 removable on X86?
0211 A: Yes. If kernel is compiled with CONFIG_BOOTPARAM_HOTPLUG_CPU0=y, CPU0 is
0212 removable by default. Otherwise, CPU0 is also removable by kernel option
0213 cpu0_hotplug.
0215 But some features depend on CPU0. Two known dependencies are:
0217 1. Resume from hibernate/suspend depends on CPU0. Hibernate/suspend will fail if
0218 CPU0 is offline and you need to online CPU0 before hibernate/suspend can
0219 continue.
0220 2. PIC interrupts also depend on CPU0. CPU0 can't be removed if a PIC interrupt
0221 is detected.
0223 It's said poweroff/reboot may depend on CPU0 on some machines although I haven't
0224 seen any poweroff/reboot failure so far after CPU0 is offline on a few tested
0225 machines.
0227 Please let me know if you know or see any other dependencies of CPU0.
0229 If the dependencies are under your control, you can turn on CPU0 hotplug feature
0230 either by CONFIG_BOOTPARAM_HOTPLUG_CPU0 or by kernel parameter cpu0_hotplug.
0232 --Fenghua Yu <>
0234 Q: How do I find out if a particular CPU is not removable?
0235 A: Depending on the implementation, some architectures may show this by the
0236 absence of the "online" file. This is done if it can be determined ahead of
0237 time that this CPU cannot be removed.
0239 In some situations, this can be a run time check, i.e if you try to remove the
0240 last CPU, this will not be permitted. You can find such failures by
0241 investigating the return value of the "echo" command.
0243 Q: What happens when a CPU is being logically offlined?
0244 A: The following happen, listed in no particular order :-)
0246 - A notification is sent to in-kernel registered modules by sending an event
0247   CPU_DOWN_PREPARE or CPU_DOWN_PREPARE_FROZEN, depending on whether or not the
0248   CPU is being offlined while tasks are frozen due to a suspend operation in
0249   progress
0250 - All processes are migrated away from this outgoing CPU to new CPUs.
0251   The new CPU is chosen from each process' current cpuset, which may be
0252   a subset of all online CPUs.
0253 - All interrupts targeted to this CPU are migrated to a new CPU
0254 - timers/bottom half/task lets are also migrated to a new CPU
0255 - Once all services are migrated, kernel calls an arch specific routine
0256   __cpu_disable() to perform arch specific cleanup.
0257 - Once this is successful, an event for successful cleanup is sent by an event
0258   CPU_DEAD (or CPU_DEAD_FROZEN if tasks are frozen due to a suspend while the
0259   CPU is being offlined).
0261   "It is expected that each service cleans up when the CPU_DOWN_PREPARE
0262   notifier is called, when CPU_DEAD is called it's expected there is nothing
0263   running on behalf of this CPU that was offlined"
0265 Q: If I have some kernel code that needs to be aware of CPU arrival and
0266    departure, how to i arrange for proper notification?
0267 A: This is what you would need in your kernel code to receive notifications.
0269         #include <linux/cpu.h>
0270         static int foobar_cpu_callback(struct notifier_block *nfb,
0271                                        unsigned long action, void *hcpu)
0272         {
0273                 unsigned int cpu = (unsigned long)hcpu;
0275                 switch (action) {
0276                 case CPU_ONLINE:
0277                 case CPU_ONLINE_FROZEN:
0278                         foobar_online_action(cpu);
0279                         break;
0280                 case CPU_DEAD:
0281                 case CPU_DEAD_FROZEN:
0282                         foobar_dead_action(cpu);
0283                         break;
0284                 }
0285                 return NOTIFY_OK;
0286         }
0288         static struct notifier_block foobar_cpu_notifier =
0289         {
0290            .notifier_call = foobar_cpu_callback,
0291         };
0293 You need to call register_cpu_notifier() from your init function.
0294 Init functions could be of two types:
0295 1. early init (init function called when only the boot processor is online).
0296 2. late init (init function called _after_ all the CPUs are online).
0298 For the first case, you should add the following to your init function
0300         register_cpu_notifier(&foobar_cpu_notifier);
0302 For the second case, you should add the following to your init function
0304         register_hotcpu_notifier(&foobar_cpu_notifier);
0306 You can fail PREPARE notifiers if something doesn't work to prepare resources.
0307 This will stop the activity and send a following CANCELED event back.
0309 CPU_DEAD should not be failed, its just a goodness indication, but bad
0310 things will happen if a notifier in path sent a BAD notify code.
0312 Q: I don't see my action being called for all CPUs already up and running?
0313 A: Yes, CPU notifiers are called only when new CPUs are on-lined or offlined.
0314    If you need to perform some action for each CPU already in the system, then
0315    do this:
0317         for_each_online_cpu(i) {
0318                 foobar_cpu_callback(&foobar_cpu_notifier, CPU_UP_PREPARE, i);
0319                 foobar_cpu_callback(&foobar_cpu_notifier, CPU_ONLINE, i);
0320         }
0322    However, if you want to register a hotplug callback, as well as perform
0323    some initialization for CPUs that are already online, then do this:
0325    Version 1: (Correct)
0326    ---------
0328         cpu_notifier_register_begin();
0330                 for_each_online_cpu(i) {
0331                         foobar_cpu_callback(&foobar_cpu_notifier,
0332                                             CPU_UP_PREPARE, i);
0333                         foobar_cpu_callback(&foobar_cpu_notifier,
0334                                             CPU_ONLINE, i);
0335                 }
0337         /* Note the use of the double underscored version of the API */
0338         __register_cpu_notifier(&foobar_cpu_notifier);
0340         cpu_notifier_register_done();
0342    Note that the following code is *NOT* the right way to achieve this,
0343    because it is prone to an ABBA deadlock between the cpu_add_remove_lock
0344    and the cpu_hotplug.lock.
0346    Version 2: (Wrong!)
0347    ---------
0349         get_online_cpus();
0351                 for_each_online_cpu(i) {
0352                         foobar_cpu_callback(&foobar_cpu_notifier,
0353                                             CPU_UP_PREPARE, i);
0354                         foobar_cpu_callback(&foobar_cpu_notifier,
0355                                             CPU_ONLINE, i);
0356                 }
0358         register_cpu_notifier(&foobar_cpu_notifier);
0360         put_online_cpus();
0362     So always use the first version shown above when you want to register
0363     callbacks as well as initialize the already online CPUs.
0366 Q: If I would like to develop CPU hotplug support for a new architecture,
0367    what do I need at a minimum?
0368 A: The following are what is required for CPU hotplug infrastructure to work
0369    correctly.
0371     - Make sure you have an entry in Kconfig to enable CONFIG_HOTPLUG_CPU
0372     - __cpu_up()        - Arch interface to bring up a CPU
0373     - __cpu_disable()   - Arch interface to shutdown a CPU, no more interrupts
0374                           can be handled by the kernel after the routine
0375                           returns. Including local APIC timers etc are
0376                           shutdown.
0377      - __cpu_die()      - This actually supposed to ensure death of the CPU.
0378                           Actually look at some example code in other arch
0379                           that implement CPU hotplug. The processor is taken
0380                           down from the idle() loop for that specific
0381                           architecture. __cpu_die() typically waits for some
0382                           per_cpu state to be set, to ensure the processor
0383                           dead routine is called to be sure positively.
0385 Q: I need to ensure that a particular CPU is not removed when there is some
0386    work specific to this CPU in progress.
0387 A: There are two ways.  If your code can be run in interrupt context, use
0388    smp_call_function_single(), otherwise use work_on_cpu().  Note that
0389    work_on_cpu() is slow, and can fail due to out of memory:
0391         int my_func_on_cpu(int cpu)
0392         {
0393                 int err;
0394                 get_online_cpus();
0395                 if (!cpu_online(cpu))
0396                         err = -EINVAL;
0397                 else
0399                         err = work_on_cpu(cpu, __my_func_on_cpu, NULL);
0400 #else
0401                         smp_call_function_single(cpu, __my_func_on_cpu, &err,
0402                                                  true);
0403 #endif
0404                 put_online_cpus();
0405                 return err;
0406         }
0408 Q: How do we determine how many CPUs are available for hotplug.
0409 A: There is no clear spec defined way from ACPI that can give us that
0410    information today. Based on some input from Natalie of Unisys,
0411    that the ACPI MADT (Multiple APIC Description Tables) marks those possible
0412    CPUs in a system with disabled status.
0414    Andi implemented some simple heuristics that count the number of disabled
0415    CPUs in MADT as hotpluggable CPUS.  In the case there are no disabled CPUS
0416    we assume 1/2 the number of CPUs currently present can be hotplugged.
0418    Caveat: ACPI MADT can only provide 256 entries in systems with only ACPI 2.0c
0419    or earlier ACPI version supported, because the apicid field in MADT is only
0420    8 bits. From ACPI 3.0, this limitation was removed since the apicid field
0421    was extended to 32 bits with x2APIC introduced.
0423 User Space Notification
0425 Hotplug support for devices is common in Linux today. Its being used today to
0426 support automatic configuration of network, usb and pci devices. A hotplug
0427 event can be used to invoke an agent script to perform the configuration task.
0429 You can add /etc/hotplug/cpu.agent to handle hotplug notification user space
0430 scripts.
0432         #!/bin/bash
0433         # $Id: cpu.agent
0434         # Kernel hotplug params include:
0435         #ACTION=%s [online or offline]
0436         #DEVPATH=%s
0437         #
0438         cd /etc/hotplug
0439         . ./hotplug.functions
0441         case $ACTION in
0442                 online)
0443                         echo `date` ":cpu.agent" add cpu >> /tmp/hotplug.txt
0444                         ;;
0445                 offline)
0446                         echo `date` ":cpu.agent" remove cpu >>/tmp/hotplug.txt
0447                         ;;
0448                 *)
0449                         debug_mesg CPU $ACTION event not supported
0450         exit 1
0451         ;;
0452         esac