Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api

[Jonathan Corbet]

On Thu, 22 Dec 2016 17:19:34 +0100
Sebastian Andrzej Siewior  wrote:

> The current CPU hotplug is outdated. During the update to what we
> currently have I rewrote it partly and moved to sphinx format.

OK, I've applied this (finally) to the docs tree, even though I do kind
of agree with Jani about keeping the author information in Git.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api

[Jani Nikula]

On Thu, 22 Dec 2016, Sebastian Andrzej Siewior  wrote:
> The current CPU hotplug is outdated. During the update to what we
> currently have I rewrote it partly and moved to sphinx format.
>
> Cc: Jonathan Corbet 
> Cc: Mauro Carvalho Chehab 
> Cc: Rusty Russell 
> Cc: Srivatsa Vaddagiri 
> Cc: Ashok Raj 
> Cc: Joel Schopp 
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Sebastian Andrzej Siewior 
> ---
>  Documentation/core-api/cpu_hotplug.rst | 372 +++
>  Documentation/core-api/index.rst   |   1 +
>  Documentation/cpu-hotplug.txt  | 452 
> -
>  3 files changed, 373 insertions(+), 452 deletions(-)
>  create mode 100644 Documentation/core-api/cpu_hotplug.rst
>  delete mode 100644 Documentation/cpu-hotplug.txt
>
> diff --git a/Documentation/core-api/cpu_hotplug.rst 
> b/Documentation/core-api/cpu_hotplug.rst
> new file mode 100644
> index ..4a50ab7817f7
> --- /dev/null
> +++ b/Documentation/core-api/cpu_hotplug.rst
> @@ -0,0 +1,372 @@
> +=
> +CPU hotplug in the Kernel
> +=
> +
> +:Date: December, 2016
> +:Author: Sebastian Andrzej Siewior ,
> +  Rusty Russell ,
> +  Srivatsa Vaddagiri ,
> +  Ashok Raj ,
> +  Joel Schopp 

Just a drive-by comment, does that do what you want? You might want to
see if adding one :Author: line per author produces better results.

That said, I think git will do a better job of maintaining both the date
and the authorship.


BR,
Jani.


> +
> +Introduction
> +
> +
> +Modern advances in system architectures have introduced advanced error
> +reporting and correction capabilities in processors. There are couple OEMS 
> that
> +support NUMA hardware which are hot pluggable as well, where physical node
> +insertion and removal require support for CPU hotplug.
> +
> +Such advances require CPUs available to a kernel to be removed either for
> +provisioning reasons, or for RAS purposes to keep an offending CPU off
> +system execution path. Hence the need for CPU hotplug support in the
> +Linux kernel.
> +
> +A more novel use of CPU-hotplug support is its use today in suspend resume
> +support for SMP. Dual-core and HT support makes even a laptop run SMP kernels
> +which didn't support these methods.
> +
> +
> +Command Line Switches
> +=
> +``maxcpus=n``
> +  Restrict boot time CPUs to *n*. Say if you have fourV CPUs, using
> +  ``maxcpus=2`` will only boot two. You can choose to bring the
> +  other CPUs later online.
> +
> +``nr_cpus=n``
> +  Restrict the total amount CPUs the kernel will support. If the number
> +  supplied here is lower than the number of physically available CPUs than
> +  those CPUs can not be brought online later.
> +
> +``additional_cpus=n``
> +  Use this to limit hotpluggable CPUs. This option sets
> +  ``cpu_possible_mask = cpu_present_mask + additional_cpus``
> +
> +  This option is limited to the IA64 architecture.
> +
> +``possible_cpus=n``
> +  This option sets ``possible_cpus`` bits in ``cpu_possible_mask``.
> +
> +  This option is limited to the X86 and S390 architecture.
> +
> +``cede_offline={"off","on"}``
> +  Use this option to disable/enable putting offlined processors to an 
> extended
> +  ``H_CEDE`` state on supported pseries platforms. If nothing is specified,
> +  ``cede_offline`` is set to "on".
> +
> +  This option is limited to the PowerPC architecture.
> +
> +``cpu0_hotplug``
> +  Allow to shutdown CPU0.
> +
> +  This option is limited to the X86 architecture.
> +
> +CPU maps
> +
> +
> +``cpu_possible_mask``
> +  Bitmap of possible CPUs that can ever be available in the
> +  system. This is used to allocate some boot time memory for per_cpu 
> variables
> +  that aren't designed to grow/shrink as CPUs are made available or removed.
> +  Once set during boot time discovery phase, the map is static, i.e no bits
> +  are added or removed anytime. Trimming it accurately for your system needs
> +  upfront can save some boot time memory.
> +
> +``cpu_online_mask``
> +  Bitmap of all CPUs currently online. Its set in ``__cpu_up()``
> +  after a CPU is available for kernel scheduling and ready to receive
> +  interrupts from devices. Its cleared when a CPU is brought down using
> +  ``__cpu_disable()``, before which all OS services including interrupts are
> +  migrated to another target CPU.
> +
> +``cpu_present_mask``
> +  Bitmap of CPUs currently present in the system. Not all
> +  of them may be online. When physical hotplug is processed by the relevant
> +  subsystem (e.g ACPI) can change and new bit either be added or removed
> +  from the map depending on the event is 

[PATCH] Documentation: Update CPU hotplug and move it to core-api

[Sebastian Andrzej Siewior]

The current CPU hotplug is outdated. During the update to what we
currently have I rewrote it partly and moved to sphinx format.

Cc: Jonathan Corbet 
Cc: Mauro Carvalho Chehab 
Cc: Rusty Russell 
Cc: Srivatsa Vaddagiri 
Cc: Ashok Raj 
Cc: Joel Schopp 
Cc: linux-doc@vger.kernel.org
Signed-off-by: Sebastian Andrzej Siewior 
---
 Documentation/core-api/cpu_hotplug.rst | 372 +++
 Documentation/core-api/index.rst   |   1 +
 Documentation/cpu-hotplug.txt  | 452 -
 3 files changed, 373 insertions(+), 452 deletions(-)
 create mode 100644 Documentation/core-api/cpu_hotplug.rst
 delete mode 100644 Documentation/cpu-hotplug.txt

diff --git a/Documentation/core-api/cpu_hotplug.rst 
b/Documentation/core-api/cpu_hotplug.rst
new file mode 100644
index ..4a50ab7817f7
--- /dev/null
+++ b/Documentation/core-api/cpu_hotplug.rst
@@ -0,0 +1,372 @@
+=
+CPU hotplug in the Kernel
+=
+
+:Date: December, 2016
+:Author: Sebastian Andrzej Siewior ,
+  Rusty Russell ,
+  Srivatsa Vaddagiri ,
+  Ashok Raj ,
+  Joel Schopp 
+
+Introduction
+
+
+Modern advances in system architectures have introduced advanced error
+reporting and correction capabilities in processors. There are couple OEMS that
+support NUMA hardware which are hot pluggable as well, where physical node
+insertion and removal require support for CPU hotplug.
+
+Such advances require CPUs available to a kernel to be removed either for
+provisioning reasons, or for RAS purposes to keep an offending CPU off
+system execution path. Hence the need for CPU hotplug support in the
+Linux kernel.
+
+A more novel use of CPU-hotplug support is its use today in suspend resume
+support for SMP. Dual-core and HT support makes even a laptop run SMP kernels
+which didn't support these methods.
+
+
+Command Line Switches
+=
+``maxcpus=n``
+  Restrict boot time CPUs to *n*. Say if you have fourV CPUs, using
+  ``maxcpus=2`` will only boot two. You can choose to bring the
+  other CPUs later online.
+
+``nr_cpus=n``
+  Restrict the total amount CPUs the kernel will support. If the number
+  supplied here is lower than the number of physically available CPUs than
+  those CPUs can not be brought online later.
+
+``additional_cpus=n``
+  Use this to limit hotpluggable CPUs. This option sets
+  ``cpu_possible_mask = cpu_present_mask + additional_cpus``
+
+  This option is limited to the IA64 architecture.
+
+``possible_cpus=n``
+  This option sets ``possible_cpus`` bits in ``cpu_possible_mask``.
+
+  This option is limited to the X86 and S390 architecture.
+
+``cede_offline={"off","on"}``
+  Use this option to disable/enable putting offlined processors to an extended
+  ``H_CEDE`` state on supported pseries platforms. If nothing is specified,
+  ``cede_offline`` is set to "on".
+
+  This option is limited to the PowerPC architecture.
+
+``cpu0_hotplug``
+  Allow to shutdown CPU0.
+
+  This option is limited to the X86 architecture.
+
+CPU maps
+
+
+``cpu_possible_mask``
+  Bitmap of possible CPUs that can ever be available in the
+  system. This is used to allocate some boot time memory for per_cpu variables
+  that aren't designed to grow/shrink as CPUs are made available or removed.
+  Once set during boot time discovery phase, the map is static, i.e no bits
+  are added or removed anytime. Trimming it accurately for your system needs
+  upfront can save some boot time memory.
+
+``cpu_online_mask``
+  Bitmap of all CPUs currently online. Its set in ``__cpu_up()``
+  after a CPU is available for kernel scheduling and ready to receive
+  interrupts from devices. Its cleared when a CPU is brought down using
+  ``__cpu_disable()``, before which all OS services including interrupts are
+  migrated to another target CPU.
+
+``cpu_present_mask``
+  Bitmap of CPUs currently present in the system. Not all
+  of them may be online. When physical hotplug is processed by the relevant
+  subsystem (e.g ACPI) can change and new bit either be added or removed
+  from the map depending on the event is hot-add/hot-remove. There are 
currently
+  no locking rules as of now. Typical usage is to init topology during boot,
+  at which time hotplug is disabled.
+
+You really don't need to manipulate any of the system CPU maps. They should
+be read-only for most use. When setting up per-cpu resources almost always use
+``cpu_possible_mask`` or ``for_each_possible_cpu()`` to iterate. To macro
+``for_each_cpu()`` can be used to iterate over a custom CPU mask.
+
+Never use anything other than ``cpumask_t`` to represent bitmap of CPUs.
+
+
+Using CPU hotplug