summaryrefslogtreecommitdiffstats
path: root/Documentation/core-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2021-09-01 18:49:47 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2021-09-01 18:49:47 -0700
commit4ac6d90867a4de2e12117e755dbd76e08d88697f (patch)
treecc6dae69b561f2cf797e7c823fbfa0e9d32236c5 /Documentation/core-api
parentdf43d903828c59afb9e93b59835127a02e1f8144 (diff)
parent37397b092e7f4b520a257aaafe83f868cd3d5e27 (diff)
downloadlinux-4ac6d90867a4de2e12117e755dbd76e08d88697f.tar.bz2
Merge tag 'docs-5.15' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "Yet another set of documentation changes: - A reworking of PDF generation to yield better results for documents using CJK fonts in particular. - A new set of translations into traditional Chinese, a dialect for which I am assured there is a community of interested readers. - A lot more regular Chinese translation work as well. ... plus the usual assortment of updates, fixes, typo tweaks, etc" * tag 'docs-5.15' of git://git.lwn.net/linux: (55 commits) docs: sphinx-requirements: Move sphinx_rtd_theme to top docs: pdfdocs: Enable language-specific font choice of zh_TW translations docs: pdfdocs: Teach xeCJK about character classes of quotation marks docs: pdfdocs: Permit AutoFakeSlant for CJK fonts docs: pdfdocs: One-half spacing for CJK translations docs: pdfdocs: Add conf.py local to translations for ascii-art alignment docs: pdfdocs: Preserve inter-phrase space in Korean translations docs: pdfdocs: Choose Serif font as CJK mainfont if possible docs: pdfdocs: Add CJK-language-specific font settings docs: pdfdocs: Refactor config for CJK document scripts/kernel-doc: Override -Werror from KCFLAGS with KDOC_WERROR docs/zh_CN: Add zh_CN/accounting/psi.rst doc: align Italian translation Documentation/features/vm: riscv supports THP now docs/zh_CN: add infiniband user_verbs translation docs/zh_CN: add infiniband user_mad translation docs/zh_CN: add infiniband tag_matching translation docs/zh_CN: add infiniband sysfs translation docs/zh_CN: add infiniband opa_vnic translation docs/zh_CN: add infiniband ipoib translation ...
Diffstat (limited to 'Documentation/core-api')
-rw-r--r--Documentation/core-api/cpu_hotplug.rst38
-rw-r--r--Documentation/core-api/printk-formats.rst1
2 files changed, 25 insertions, 14 deletions
diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst
index 1122cd3044c0..b66e3cae1472 100644
--- a/Documentation/core-api/cpu_hotplug.rst
+++ b/Documentation/core-api/cpu_hotplug.rst
@@ -91,9 +91,10 @@ Never use anything other than ``cpumask_t`` to represent bitmap of CPUs.
Using CPU hotplug
=================
+
The kernel option *CONFIG_HOTPLUG_CPU* needs to be enabled. It is currently
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
total 0
@@ -113,14 +114,14 @@ configuration is done via the sysfs interface: ::
The files *offline*, *online*, *possible*, *present* represent the CPU masks.
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
smpboot: CPU 4 is now offline
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
-bring CPU4 back online: ::
+bring CPU4 back online::
$ echo 1 > /sys/devices/system/cpu/cpu4/online
smpboot: Booting Node 0 Processor 4 APIC 0x1
@@ -142,6 +143,7 @@ The CPU hotplug coordination
The offline case
----------------
+
Once a CPU has been logically shutdown the teardown callbacks of registered
hotplug states will be invoked, starting with ``CPUHP_ONLINE`` and terminating
at state ``CPUHP_OFFLINE``. This includes:
@@ -158,9 +160,10 @@ at state ``CPUHP_OFFLINE``. This includes:
Using the hotplug API
---------------------
+
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
-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>
@@ -186,9 +189,10 @@ During the removal of a hotplug state the teardown callback will be invoked.
Multiple instances
~~~~~~~~~~~~~~~~~~
+
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.
-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,
Y_online, Y_prepare_down);
@@ -197,7 +201,7 @@ First a multi-state state needs to be registered: ::
The ``cpuhp_setup_state_multi()`` behaves similar to ``cpuhp_setup_state()``
except it prepares the callbacks for a multi state and does not invoke
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);
@@ -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
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)
should be invoked which will invoke the teardown callback on all online
@@ -214,6 +219,7 @@ CPUs.
Manual setup
~~~~~~~~~~~~
+
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
goes online (offline) and during initial setup (shutdown) of the driver. However
@@ -226,6 +232,7 @@ hotplug operations.
The ordering of the events
--------------------------
+
The hotplug states are defined in ``include/linux/cpuhotplug.h``:
* The states *CPUHP_OFFLINE* … *CPUHP_AP_OFFLINE* are invoked before the
@@ -248,13 +255,14 @@ another hotplug event.
Testing of hotplug states
=========================
+
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
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*
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
138: mm/vmscan:online
@@ -268,7 +276,7 @@ All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states
168: sched:active
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
169
@@ -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
140
-It is important to note that the teardown callbac of state 140 have been
-invoked. And now get back online: ::
+It is important to note that the teardown callback of state 140 have been
+invoked. And now get back online::
$ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target
$ cat /sys/devices/system/cpu/cpu4/hotplug/state
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
# | | | | |
@@ -318,6 +326,7 @@ trace.
Architecture's requirements
===========================
+
The following functions and configurations are required:
``CONFIG_HOTPLUG_CPU``
@@ -339,11 +348,12 @@ The following functions and configurations are required:
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"
-will receive all events. A script like: ::
+will receive all events. A script like::
#!/bin/sh
diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst
index d941717a191b..e08bbe9b0cbf 100644
--- a/Documentation/core-api/printk-formats.rst
+++ b/Documentation/core-api/printk-formats.rst
@@ -130,6 +130,7 @@ printed after the symbol name with an extra ``b`` appended to the end of the
specifier.
::
+
%pS versatile_init+0x0/0x110 [module_name]
%pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]
%pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]