CPU hotplug in the Kernel

CPU hotplug in the Kernel

이 문서는 2021년 9월 기준이며 Sebastian Andrzej Siewior, Rusty Russell, Srivatsa Vaddagiri, Ashok Raj, Joel Schopp, Thomas Gleixner가 작성했습니다.

현대 processor는 고급 error reporting 및 correction 기능을 제공하며, 일부 OEM의 NUMA hardware는 physical node 자체를 hot-plug할 수 있습니다. 이런 node를 삽입하거나 제거하려면 CPU hotplug 지원이 필요합니다.

Kernel이 사용할 수 있는 CPU를 provisioning 목적으로 제거하거나, RAS 목적으로 문제가 있는 CPU를 system execution path에서 제외해야 하므로 Linux kernel에 CPU hotplug가 필요합니다.

CPU hotplug는 SMP suspend/resume에도 사용됩니다. Dual-core와 HT 때문에 과거 이 방식을 지원하지 않던 laptop도 SMP kernel로 동작하기 때문입니다.

Command Line Switches

CPU maps

대부분의 code는 system CPU map을 직접 조작할 필요가 없으며 read-only로 취급해야 합니다. Per-CPU resource를 설정할 때는 거의 항상 `cpu_possible_mask` 또는 `for_each_possible_cpu()`로 순회하고, custom mask는 `for_each_cpu()`로 순회합니다.

CPU bitmap은 반드시 `cpumask_t`로 표현해야 합니다.

sysfs로 CPU hotplug 사용하기

Kernel option `CONFIG_HOTPLUG_CPU`를 enable해야 합니다. ARM, MIPS, PowerPC, X86을 비롯한 여러 architecture가 지원하며 sysfs interface로 구성합니다.

$ ls -lh /sys/devices/system/cpu
total 0
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu0
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu1
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu2
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu3
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu4
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu5
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu6
drwxr-xr-x  9 root root    0 Dec 21 16:33 cpu7
drwxr-xr-x  2 root root    0 Dec 21 16:33 hotplug
-r--r--r--  1 root root 4.0K Dec 21 16:33 offline
-r--r--r--  1 root root 4.0K Dec 21 16:33 online
-r--r--r--  1 root root 4.0K Dec 21 16:33 possible
-r--r--r--  1 root root 4.0K Dec 21 16:33 present

`offline`, `online`, `possible`, `present` file은 각각 CPU mask를 나타냅니다. 각 CPU directory의 `online` file은 logical on(1)과 off(0) 상태를 제어합니다. CPU4를 logical shutdown하려면 다음을 실행합니다.

$ echo 0 > /sys/devices/system/cpu/cpu4/online
 smpboot: CPU 4 is now offline

Shutdown된 CPU는 `/proc/interrupts`와 `/proc/cpuinfo`에서 제거되고 `top`에도 나타나지 않아야 합니다. CPU4를 다시 online으로 만들려면 다음을 실행합니다.

$ echo 1 > /sys/devices/system/cpu/cpu4/online
smpboot: Booting Node 0 Processor 4 APIC 0x1

이제 CPU를 다시 사용할 수 있습니다. 모든 CPU에서 동작해야 하지만 CPU0은 특별하게 취급되어 CPU hotplug 대상에서 제외되는 경우가 많습니다.

CPU offline coordination

CPU를 logical shutdown하면 등록된 hotplug state의 teardown callback을 `CPUHP_ONLINE`에서 시작해 `CPUHP_OFFLINE`까지 호출합니다.

• Suspend로 task가 frozen 상태이면 `cpuhp_tasks_frozen`을 true로 설정합니다.
• 나가는 CPU의 모든 process를 새 CPU로 migration합니다. 각 process의 현재 cpuset에서 대상 CPU를 고르므로 전체 online CPU의 subset일 수 있습니다.
• 해당 CPU를 대상으로 한 모든 interrupt를 새 CPU로 migration합니다.
• Timer도 새 CPU로 migration합니다.
• 모든 service를 옮긴 뒤 architecture-specific cleanup을 위해 `__cpu_disable()`을 호출합니다.

CPU hotplug state machine

CPU hotplug는 `CPUHP_OFFLINE`부터 `CPUHP_ONLINE`까지 선형 state space를 갖는 단순한 state machine을 사용하며, 각 state에는 startup callback과 teardown callback이 있습니다.

CPU를 online으로 만들 때는 `CPUHP_ONLINE`에 도달할 때까지 startup callback을 순서대로 호출합니다. State callback을 설치하거나 multi-instance state에 instance를 추가할 때도 호출될 수 있습니다.

CPU를 offline으로 만들 때는 `CPUHP_OFFLINE`에 도달할 때까지 teardown callback을 역순으로 호출합니다. State callback을 제거하거나 multi-instance state에서 instance를 제거할 때도 호출될 수 있습니다.

사용 지점이 online 또는 offline 한 방향의 callback만 필요로 한다면 state를 설정할 때 필요 없는 다른 callback을 `NULL`로 지정할 수 있습니다.

PREPARE, STARTING, ONLINE section

CPU online/offline state transition

성공한 online operation은 startup callback을 state 오름차순으로 실행합니다.

성공한 offline operation은 teardown callback을 state 내림차순으로 실행합니다.

Online 중 `CPUHP_AP_ONLINE + N`의 startup이 실패하면 이미 성공한 state의 teardown을 역순으로 호출하여 `CPUHP_OFFLINE`까지 rollback합니다.

Offline 중 `CPUHP_ONLINE - N`의 teardown이 실패하면 이미 내려간 state의 startup을 다시 호출하여 `CPUHP_ONLINE`으로 복구합니다.

Rollback callback까지 실패하는 recursive failure는 합리적으로 처리할 수 없습니다. 다시 아래로 내려가려 하면 같은 teardown 실패와 startup 실패를 반복하는 endless loop가 되기 때문입니다.

이 경우 CPU는 `CPUHP_ONLINE - (N - 1)` state에 남습니다. 적어도 system이 계속 진행하고 user가 상황을 debug하거나 해결할 기회를 제공합니다.

Hotplug state 할당

CPU hotplug state 할당 방식은 두 가지입니다.

• Static allocation: subsystem 또는 driver가 다른 hotplug state와의 ordering을 요구할 때 사용합니다. 예를 들어 online에서는 PERF core startup이 PERF driver startup보다 먼저, offline에서는 driver teardown이 core teardown보다 먼저여야 합니다. `include/linux/cpuhotplug.h`의 `cpuhp_state` enum에서 올바른 위치에 state를 삽입하고 그 상수를 setup 및 removal에 사용합니다. Callback이 runtime에 설치되지 않고 `kernel/cpu.c`의 state array initializer에 포함될 때도 static allocation이 필요합니다.
• Dynamic allocation: ordering requirement가 없을 때 선호합니다. Setup function이 state number를 할당해 성공 시 caller에게 반환합니다. Dynamic range는 PREPARE와 ONLINE에만 있고, 명시적인 ordering이 필요한 callback이 많은 STARTING에는 없습니다.

CPU hotplug state setup

Core code는 state setup을 위해 다음 function을 제공합니다.

• cpuhp_setup_state(state, name, startup, teardown)
• cpuhp_setup_state_nocalls(state, name, startup, teardown)
• cpuhp_setup_state_cpuslocked(state, name, startup, teardown)
• cpuhp_setup_state_nocalls_cpuslocked(state, name, startup, teardown)

Driver 또는 subsystem에 instance가 여러 개이고 각 instance마다 같은 callback을 호출해야 하면 hotplug core의 multi-instance 지원을 사용합니다. Driver별 instance list와 달리 instance function은 CPU hotplug operation과 완전히 serialize되고 add/remove 때 callback을 자동으로 호출합니다.

• cpuhp_setup_state_multi(state, name, startup, teardown)

`@state`는 statically allocated state이거나 dynamic state 상수 `CPUHP_BP_PREPARE_DYN`, `CPUHP_AP_ONLINE_DYN` 가운데 section에 맞는 값입니다.

`@name`은 sysfs output과 instrumentation에 사용합니다. Naming convention은 `subsys:mode` 또는 `subsys/driver:mode`이며 `perf:mode`, `perf/x86:mode`가 예입니다.

`@name`은 sysfs와 instrumentation에만 쓰이므로 state 성격을 더 잘 설명한다면 다른 mode descriptor도 사용할 수 있습니다. 예는 `perf/online`, `perf/x86:prepare`, `RCU/tree:dying`, `sched/waitempty`입니다.

Setup callback 처리와 반환값

`@startup`은 CPU online operation에서 호출할 callback function pointer이고, 필요 없으면 `NULL`로 둡니다. `@teardown`은 CPU offline operation에서 호출할 callback pointer이며 역시 필요 없으면 `NULL`로 둡니다.

• `cpuhp_setup_state_nocalls()`, `cpuhp_setup_state_nocalls_cpuslocked()`, `cpuhp_setup_state_multi()`는 callback만 설치합니다.
• `cpuhp_setup_state()`와 `cpuhp_setup_state_cpuslocked()`는 callback을 설치하고 현재 state가 새 state보다 높은 모든 online CPU에 non-NULL startup을 호출합니다. PREPARE에서는 current CPU, ONLINE에서는 각 CPU의 hotplug thread context에서 해당 online CPU에 호출합니다.

CPU N의 callback이 실패하면 CPU 0부터 N-1까지 teardown callback을 호출해 rollback합니다. Setup은 실패하고 callback은 설치되지 않으며 dynamic allocation이면 state도 해제됩니다.

State setup과 callback 호출은 CPU hotplug operation과 serialize됩니다. CPU hotplug read lock 영역에서 setup을 호출해야 하면 `_cpuslocked()` variant를 사용해야 하며, 이 function들은 CPU hotplug callback 내부에서 사용할 수 없습니다.

CPU hotplug state removal

설치한 state를 제거하는 function은 다음과 같습니다.

• cpuhp_remove_state(state)
• cpuhp_remove_state_nocalls(state)
• cpuhp_remove_state_nocalls_cpuslocked(state)
• cpuhp_remove_multi_state(state)

`@state`는 static state 또는 `cpuhp_setup_state*()`가 dynamic range에서 할당한 state number입니다. Dynamic state를 제거하면 number도 해제되어 다시 할당할 수 있습니다.

• `cpuhp_remove_state_nocalls()`, `cpuhp_remove_state_nocalls_cpuslocked()`, `cpuhp_remove_multi_state()`는 callback만 제거합니다.
• `cpuhp_remove_state()`는 callback을 제거하고 현재 state가 제거된 state보다 높은 모든 online CPU에 non-NULL teardown을 호출합니다. PREPARE에서는 current CPU, ONLINE에서는 각 CPU hotplug thread context에서 호출합니다.

Removal을 완료하려면 teardown callback이 실패하지 않아야 합니다. Removal과 callback 호출은 hotplug operation과 serialize되며, read-locked 영역에서는 `_cpuslocked()` variant를 사용합니다. Hotplug callback 내부에서는 사용할 수 없습니다.

Multi-instance state를 제거하기 전에 caller가 모든 instance를 먼저 제거해야 합니다.

Multi-instance state 관리

Multi-instance state를 설치한 뒤 다음 function으로 instance를 추가합니다.

• cpuhp_state_add_instance(state, node)
• cpuhp_state_add_instance_nocalls(state, node)

`@state`는 static state 또는 `cpuhp_setup_state_multi()`가 dynamic range에서 할당한 number입니다. `@node`는 instance data structure에 embedded된 `hlist_node` pointer이며 callback은 이를 받아 `container_of()`로 instance를 찾습니다.

• `cpuhp_state_add_instance_nocalls()`는 multi-instance state의 node list에 instance만 추가합니다.
• `cpuhp_state_add_instance()`는 instance를 추가하고 현재 state가 @state보다 높은 모든 online CPU에 해당 instance의 startup callback을 호출합니다. CPU N에서 실패하면 CPU 0부터 N-1까지 teardown으로 rollback하고 instance를 list에 추가하지 않습니다.

Instance를 제거하는 function은 다음과 같습니다.

• cpuhp_state_remove_instance(state, node)
• cpuhp_state_remove_instance_nocalls(state, node)

Argument는 위의 `cpuhp_state_add_instance*()` variant와 같습니다.

• `cpuhp_state_remove_instance_nocalls()`는 state node list에서 instance만 제거합니다.
• `cpuhp_state_remove_instance()`는 instance를 제거하고 현재 state가 @state보다 높은 모든 online CPU에 해당 instance의 non-NULL teardown callback을 호출합니다. Removal을 완료하려면 teardown이 실패하지 않아야 합니다.

Node list add/remove와 callback 호출은 CPU hotplug operation과 serialize됩니다. 이 function들은 CPU hotplug callback 내부나 CPU hotplug read-locked 영역에서 사용할 수 없습니다.

State setup 및 teardown 예제

STARTING section의 statically allocated state를 online/offline notification용으로 설치하고 제거하는 예입니다.

ret = cpuhp_setup_state(CPUHP_SUBSYS_STARTING, "subsys:starting", subsys_cpu_starting, subsys_cpu_dying);
if (ret < 0)
     return ret;
....
cpuhp_remove_state(CPUHP_SUBSYS_STARTING);

ONLINE section의 dynamically allocated state를 offline notification용으로 설치하고 제거하는 예입니다.

state = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "subsys:offline", NULL, subsys_cpu_offline);
if (state < 0)
    return state;
....
cpuhp_remove_state(state);

Callback을 즉시 호출하지 않고 ONLINE section의 dynamic state를 online notification용으로 설치하고 제거하는 예입니다.

state = cpuhp_setup_state_nocalls(CPUHP_AP_ONLINE_DYN, "subsys:online", subsys_cpu_online, NULL);
if (state < 0)
    return state;
....
cpuhp_remove_state_nocalls(state);

ONLINE section의 dynamically allocated multi-instance state를 설치하고 두 instance를 추가한 뒤 제거하는 예입니다.

state = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline);
if (state < 0)
    return state;
....
ret = cpuhp_state_add_instance(state, &inst1->node);
if (ret)
     return ret;
....
ret = cpuhp_state_add_instance(state, &inst2->node);
if (ret)
     return ret;
....
cpuhp_remove_instance(state, &inst1->node);
....
cpuhp_remove_instance(state, &inst2->node);
....
cpuhp_remove_multi_state(state);

Hotplug state 시험

Custom state가 예상대로 동작하는지는 CPU를 shutdown했다가 다시 online으로 만들거나, CPU를 `CPUHP_AP_ONLINE` 같은 특정 state로 내렸다가 `CPUHP_ONLINE`으로 되돌려 확인할 수 있습니다. 후자는 AP_ONLINE 다음 state의 error와 online state로의 rollback을 simulate합니다.

등록된 모든 state는 `/sys/devices/system/cpu/hotplug/states`에 열거됩니다.

$ tail /sys/devices/system/cpu/hotplug/states
138: mm/vmscan:online
139: mm/vmstat:online
140: lib/percpu_cnt:online
141: acpi/cpu-drv:online
142: base/cacheinfo:online
143: virtio/net:online
144: x86/mce:online
145: printk:online
168: sched:active
169: online

CPU4를 `lib/percpu_cnt:online` state 140까지 rollback하는 예입니다.

$ cat /sys/devices/system/cpu/cpu4/hotplug/state
169
$ echo 140 > /sys/devices/system/cpu/cpu4/hotplug/target
$ cat /sys/devices/system/cpu/cpu4/hotplug/state
140

이 과정에서 state 140의 teardown callback도 호출됩니다. 다시 online으로 전환합니다.

$ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target
$ cat /sys/devices/system/cpu/cpu4/hotplug/state
169

Trace event를 enable하면 각 단계와 callback return code를 볼 수 있습니다.

#  TASK-PID   CPU#    TIMESTAMP  FUNCTION
#     | |       |        |         |
    bash-394  [001]  22.976: cpuhp_enter: cpu: 0004 target: 140 step: 169 (cpuhp_kick_ap_work)
 cpuhp/4-31   [004]  22.977: cpuhp_enter: cpu: 0004 target: 140 step: 168 (sched_cpu_deactivate)
 cpuhp/4-31   [004]  22.990: cpuhp_exit:  cpu: 0004  state: 168 step: 168 ret: 0
 cpuhp/4-31   [004]  22.991: cpuhp_enter: cpu: 0004 target: 140 step: 144 (mce_cpu_pre_down)
 cpuhp/4-31   [004]  22.992: cpuhp_exit:  cpu: 0004  state: 144 step: 144 ret: 0
 cpuhp/4-31   [004]  22.993: cpuhp_multi_enter: cpu: 0004 target: 140 step: 143 (virtnet_cpu_down_prep)
 cpuhp/4-31   [004]  22.994: cpuhp_exit:  cpu: 0004  state: 143 step: 143 ret: 0
 cpuhp/4-31   [004]  22.995: cpuhp_enter: cpu: 0004 target: 140 step: 142 (cacheinfo_cpu_pre_down)
 cpuhp/4-31   [004]  22.996: cpuhp_exit:  cpu: 0004  state: 142 step: 142 ret: 0
    bash-394  [001]  22.997: cpuhp_exit:  cpu: 0004  state: 140 step: 169 ret: 0
    bash-394  [005]  95.540: cpuhp_enter: cpu: 0004 target: 169 step: 140 (cpuhp_kick_ap_work)
 cpuhp/4-31   [004]  95.541: cpuhp_enter: cpu: 0004 target: 169 step: 141 (acpi_soft_cpu_online)
 cpuhp/4-31   [004]  95.542: cpuhp_exit:  cpu: 0004  state: 141 step: 141 ret: 0
 cpuhp/4-31   [004]  95.543: cpuhp_enter: cpu: 0004 target: 169 step: 142 (cacheinfo_cpu_online)
 cpuhp/4-31   [004]  95.544: cpuhp_exit:  cpu: 0004  state: 142 step: 142 ret: 0
 cpuhp/4-31   [004]  95.545: cpuhp_multi_enter: cpu: 0004 target: 169 step: 143 (virtnet_cpu_online)
 cpuhp/4-31   [004]  95.546: cpuhp_exit:  cpu: 0004  state: 143 step: 143 ret: 0
 cpuhp/4-31   [004]  95.547: cpuhp_enter: cpu: 0004 target: 169 step: 144 (mce_cpu_online)
 cpuhp/4-31   [004]  95.548: cpuhp_exit:  cpu: 0004  state: 144 step: 144 ret: 0
 cpuhp/4-31   [004]  95.549: cpuhp_enter: cpu: 0004 target: 169 step: 145 (console_cpu_notify)
 cpuhp/4-31   [004]  95.550: cpuhp_exit:  cpu: 0004  state: 145 step: 145 ret: 0
 cpuhp/4-31   [004]  95.551: cpuhp_enter: cpu: 0004 target: 169 step: 168 (sched_cpu_activate)
 cpuhp/4-31   [004]  95.552: cpuhp_exit:  cpu: 0004  state: 168 step: 168 ret: 0
    bash-394  [005]  95.553: cpuhp_exit:  cpu: 0004  state: 169 step: 140 ret: 0

Trace에서 CPU4는 timestamp 22.996까지 내려갔다가 95.552까지 다시 올라왔으며, 호출된 모든 callback과 return code가 표시됩니다.

Architecture requirements

User Space Notification

CPU가 성공적으로 online 또는 offline이 되면 udev event를 보냅니다. 다음 rule로 모든 event를 받을 수 있습니다.

SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh"

Event를 처리하는 script 예입니다.

#!/bin/sh

if [ "${ACTION}" = "offline" ]
then
    echo "CPU ${DEVPATH##*/} offline"

elif [ "${ACTION}" = "online" ]
then
    echo "CPU ${DEVPATH##*/} online"

fi

System CPU가 바뀔 때 `/sys/devices/system/cpu/crash_hotplug`는 kernel이 `elfcorehdr`와 관련 kexec segment를 통해 kdump capture kernel의 CPU list를 직접 갱신하면 `1`, userspace가 갱신해야 하면 `0`을 담습니다. 사용 가능 여부는 `CONFIG_HOTPLUG_CPU`에 달려 있습니다.

Kdump의 최신 CPU list를 얻기 위한 unload 후 reload를 생략하려면 다음 udev rule을 사용할 수 있습니다.

SUBSYSTEM=="cpu", ATTRS{crash_hotplug}=="1", GOTO="kdump_reload_end"

Architecture가 CPU list를 담은 `elfcorehdr`와 관련 kexec segment를 kernel에서 갱신할 수 있다면 이 rule은 CPU hot un/plug event에서 kdump capture kernel의 unload/reload를 건너뜁니다.

Kernel Inline Documentations Reference

CPU hotplug API의 inline kernel-doc reference는 `include/linux/cpuhotplug.h`에서 가져옵니다.

.. kernel-doc:: include/linux/cpuhotplug.h