提交 f8c6a07c 编写于 作者: Y Yanteng Si 提交者: Jonathan Corbet

docs/core-api: Modify document layout

Modify the layout of the document and remove unnecessary symbols.
Signed-off-by: NYanteng Si <siyanteng@loongson.cn>
Reviewed-by: NWu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/f151bbc0d1ff6cf24611a698c76b90181f005f8d.1625798719.git.siyanteng@loongson.cnSigned-off-by: NJonathan Corbet <corbet@lwn.net>
上级 341968c6
...@@ -91,9 +91,10 @@ Never use anything other than ``cpumask_t`` to represent bitmap of CPUs. ...@@ -91,9 +91,10 @@ Never use anything other than ``cpumask_t`` to represent bitmap of CPUs.
Using CPU hotplug Using CPU hotplug
================= =================
The kernel option *CONFIG_HOTPLUG_CPU* needs to be enabled. It is currently The kernel option *CONFIG_HOTPLUG_CPU* needs to be enabled. It is currently
available on multiple architectures including ARM, MIPS, PowerPC and X86. The available on multiple architectures including ARM, MIPS, PowerPC and X86. The
configuration is done via the sysfs interface: :: configuration is done via the sysfs interface::
$ ls -lh /sys/devices/system/cpu $ ls -lh /sys/devices/system/cpu
total 0 total 0
...@@ -113,14 +114,14 @@ configuration is done via the sysfs interface: :: ...@@ -113,14 +114,14 @@ configuration is done via the sysfs interface: ::
The files *offline*, *online*, *possible*, *present* represent the CPU masks. The files *offline*, *online*, *possible*, *present* represent the CPU masks.
Each CPU folder contains an *online* file which controls the logical on (1) and Each CPU folder contains an *online* file which controls the logical on (1) and
off (0) state. To logically shutdown CPU4: :: off (0) state. To logically shutdown CPU4::
$ echo 0 > /sys/devices/system/cpu/cpu4/online $ echo 0 > /sys/devices/system/cpu/cpu4/online
smpboot: CPU 4 is now offline smpboot: CPU 4 is now offline
Once the CPU is shutdown, it will be removed from */proc/interrupts*, Once the CPU is shutdown, it will be removed from */proc/interrupts*,
*/proc/cpuinfo* and should also not be shown visible by the *top* command. To */proc/cpuinfo* and should also not be shown visible by the *top* command. To
bring CPU4 back online: :: bring CPU4 back online::
$ echo 1 > /sys/devices/system/cpu/cpu4/online $ echo 1 > /sys/devices/system/cpu/cpu4/online
smpboot: Booting Node 0 Processor 4 APIC 0x1 smpboot: Booting Node 0 Processor 4 APIC 0x1
...@@ -142,6 +143,7 @@ The CPU hotplug coordination ...@@ -142,6 +143,7 @@ The CPU hotplug coordination
The offline case The offline case
---------------- ----------------
Once a CPU has been logically shutdown the teardown callbacks of registered Once a CPU has been logically shutdown the teardown callbacks of registered
hotplug states will be invoked, starting with ``CPUHP_ONLINE`` and terminating hotplug states will be invoked, starting with ``CPUHP_ONLINE`` and terminating
at state ``CPUHP_OFFLINE``. This includes: at state ``CPUHP_OFFLINE``. This includes:
...@@ -158,9 +160,10 @@ at state ``CPUHP_OFFLINE``. This includes: ...@@ -158,9 +160,10 @@ at state ``CPUHP_OFFLINE``. This includes:
Using the hotplug API Using the hotplug API
--------------------- ---------------------
It is possible to receive notifications once a CPU is offline or onlined. This It is possible to receive notifications once a CPU is offline or onlined. This
might be important to certain drivers which need to perform some kind of setup might be important to certain drivers which need to perform some kind of setup
or clean up functions based on the number of available CPUs: :: or clean up functions based on the number of available CPUs::
#include <linux/cpuhotplug.h> #include <linux/cpuhotplug.h>
...@@ -186,9 +189,10 @@ During the removal of a hotplug state the teardown callback will be invoked. ...@@ -186,9 +189,10 @@ During the removal of a hotplug state the teardown callback will be invoked.
Multiple instances Multiple instances
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
If a driver has multiple instances and each instance needs to perform the If a driver has multiple instances and each instance needs to perform the
callback independently then it is likely that a ''multi-state'' should be used. callback independently then it is likely that a ''multi-state'' should be used.
First a multi-state state needs to be registered: :: First a multi-state state needs to be registered::
ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online,
Y_online, Y_prepare_down); Y_online, Y_prepare_down);
...@@ -197,7 +201,7 @@ First a multi-state state needs to be registered: :: ...@@ -197,7 +201,7 @@ First a multi-state state needs to be registered: ::
The ``cpuhp_setup_state_multi()`` behaves similar to ``cpuhp_setup_state()`` The ``cpuhp_setup_state_multi()`` behaves similar to ``cpuhp_setup_state()``
except it prepares the callbacks for a multi state and does not invoke except it prepares the callbacks for a multi state and does not invoke
the callbacks. This is a one time setup. the callbacks. This is a one time setup.
Once a new instance is allocated, you need to register this new instance: :: Once a new instance is allocated, you need to register this new instance::
ret = cpuhp_state_add_instance(Y_hp_online, &d->node); ret = cpuhp_state_add_instance(Y_hp_online, &d->node);
...@@ -206,7 +210,8 @@ This function will add this instance to your previously allocated ...@@ -206,7 +210,8 @@ This function will add this instance to your previously allocated
(*Y_online*) on all online CPUs. The *node* element is a ``struct (*Y_online*) on all online CPUs. The *node* element is a ``struct
hlist_node`` member of your per-instance data structure. hlist_node`` member of your per-instance data structure.
On removal of the instance: :: On removal of the instance::
cpuhp_state_remove_instance(Y_hp_online, &d->node) cpuhp_state_remove_instance(Y_hp_online, &d->node)
should be invoked which will invoke the teardown callback on all online should be invoked which will invoke the teardown callback on all online
...@@ -214,6 +219,7 @@ CPUs. ...@@ -214,6 +219,7 @@ CPUs.
Manual setup Manual setup
~~~~~~~~~~~~ ~~~~~~~~~~~~
Usually it is handy to invoke setup and teardown callbacks on registration or Usually it is handy to invoke setup and teardown callbacks on registration or
removal of a state because usually the operation needs to performed once a CPU removal of a state because usually the operation needs to performed once a CPU
goes online (offline) and during initial setup (shutdown) of the driver. However goes online (offline) and during initial setup (shutdown) of the driver. However
...@@ -226,6 +232,7 @@ hotplug operations. ...@@ -226,6 +232,7 @@ hotplug operations.
The ordering of the events The ordering of the events
-------------------------- --------------------------
The hotplug states are defined in ``include/linux/cpuhotplug.h``: The hotplug states are defined in ``include/linux/cpuhotplug.h``:
* The states *CPUHP_OFFLINE* … *CPUHP_AP_OFFLINE* are invoked before the * The states *CPUHP_OFFLINE* … *CPUHP_AP_OFFLINE* are invoked before the
...@@ -248,13 +255,14 @@ another hotplug event. ...@@ -248,13 +255,14 @@ another hotplug event.
Testing of hotplug states Testing of hotplug states
========================= =========================
One way to verify whether a custom state is working as expected or not is to One way to verify whether a custom state is working as expected or not is to
shutdown a CPU and then put it online again. It is also possible to put the CPU shutdown a CPU and then put it online again. It is also possible to put the CPU
to certain state (for instance *CPUHP_AP_ONLINE*) and then go back to to certain state (for instance *CPUHP_AP_ONLINE*) and then go back to
*CPUHP_ONLINE*. This would simulate an error one state after *CPUHP_AP_ONLINE* *CPUHP_ONLINE*. This would simulate an error one state after *CPUHP_AP_ONLINE*
which would lead to rollback to the online state. which would lead to rollback to the online state.
All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states``: :: All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states`` ::
$ tail /sys/devices/system/cpu/hotplug/states $ tail /sys/devices/system/cpu/hotplug/states
138: mm/vmscan:online 138: mm/vmscan:online
...@@ -268,7 +276,7 @@ All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states ...@@ -268,7 +276,7 @@ All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states
168: sched:active 168: sched:active
169: online 169: online
To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue::
$ cat /sys/devices/system/cpu/cpu4/hotplug/state $ cat /sys/devices/system/cpu/cpu4/hotplug/state
169 169
...@@ -276,14 +284,14 @@ To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: ...@@ -276,14 +284,14 @@ To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: ::
$ cat /sys/devices/system/cpu/cpu4/hotplug/state $ cat /sys/devices/system/cpu/cpu4/hotplug/state
140 140
It is important to note that the teardown callbac of state 140 have been It is important to note that the teardown callback of state 140 have been
invoked. And now get back online: :: invoked. And now get back online::
$ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target $ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target
$ cat /sys/devices/system/cpu/cpu4/hotplug/state $ cat /sys/devices/system/cpu/cpu4/hotplug/state
169 169
With trace events enabled, the individual steps are visible, too: :: With trace events enabled, the individual steps are visible, too::
# TASK-PID CPU# TIMESTAMP FUNCTION # TASK-PID CPU# TIMESTAMP FUNCTION
# | | | | | # | | | | |
...@@ -318,6 +326,7 @@ trace. ...@@ -318,6 +326,7 @@ trace.
Architecture's requirements Architecture's requirements
=========================== ===========================
The following functions and configurations are required: The following functions and configurations are required:
``CONFIG_HOTPLUG_CPU`` ``CONFIG_HOTPLUG_CPU``
...@@ -339,11 +348,12 @@ The following functions and configurations are required: ...@@ -339,11 +348,12 @@ The following functions and configurations are required:
User Space Notification User Space Notification
======================= =======================
After CPU successfully onlined or offline udev events are sent. A udev rule like: ::
After CPU successfully onlined or offline udev events are sent. A udev rule like::
SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh" SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh"
will receive all events. A script like: :: will receive all events. A script like::
#!/bin/sh #!/bin/sh
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册