Re: [PATCH] Documentation: Update CPU hotplug and move it to core-api
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
On Wed, 04 Jan 2017, Sebastian Andrzej Siewior wrote: > On 2016-12-23 10:03:09 [+0200], Jani Nikula wrote: >> > --- /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. > > I see an Author: line for each author, I like better the way it is. > >> That said, I think git will do a better job of maintaining both the date >> and the authorship. > > If you see the generated html output in your browser you don't have git > around to check the date or the Author. The date should help you to keep > track of the latest version. As for the Author, git would only show me > as the author but I did not write everything myself. Some parts are > still from old documentation. Just to be clear, I don't really care about this file specifically one way or the other. Do as you wish, and please don't let my comments block you. --- In general, I don't think maintaining either the date or the authors manually is a good idea. This applies for both documentation and source code. The obvious downside is that updating them will be overlooked and forgotten. Arguably not having them at all is better than having incorrect or stale information (when the accurate information can be retrieved from git). Perhaps we could add more automatically updated metadata to the generated documentation. We could even add the date from git if we really wanted to. But do we? The generated documentation already includes the kernel version, is that not enough? Even when people do remember to update the fields, they're faced with a dilemma: Do their changes warrant an update in date or adding themselves as author? Are the changes significant enough? This is completely subjective. What if there have been bigger changes by others without updates to authors? Should you remove authors when their contributions have been long since been removed or rewritten, and forgotten, and don't have any relevance to the current text? I think listing authors in files, whether they're text or source code, in collaborative projects, is counter-productive. The best possible end result, not the promotion of individuals, should be the shared goal. No contributor should feel that their contribution promotes the people in authors rather than improves the end result. No contributor should shy away from updating a file because it seems to be "owned" by someone. Of course, credit to whom credit is due, but in an objective and fair manner. I argue that git log and blame are objective, and the history is all there for anyone that cares to look. It's not without flaws, as you point out, but I think it's superior to maintaining authors manually. (Copyright notices may need to be updated in the files, but they could be in reStructuredText comments, not unlike in source code.) BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- 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
On 2016-12-23 10:03:09 [+0200], Jani Nikula wrote: > > --- /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. I see an Author: line for each author, I like better the way it is. > That said, I think git will do a better job of maintaining both the date > and the authorship. If you see the generated html output in your browser you don't have git around to check the date or the Author. The date should help you to keep track of the latest version. As for the Author, git would only show me as the author but I did not write everything myself. Some parts are still from old documentation. > BR, > Jani. Sebastian -- 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
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 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 set
