[PATCH] Documentation: admin: reorganize kernel-parameters intro

[PATCH] Documentation: admin: reorganize kernel-parameters intro

[Randy Dunlap]

Reorganize the introduction to the kernel-parameters file to place
related paragraphs together:

- move module info together and near the beginning
- add a Special Handling section for dashes, underscores, double quotes,
  cpu lists, and KMG suffixes
- add a Kernel Build Options section

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/admin-guide/kernel-parameters.rst |   35 ++++++++------
 1 file changed, 22 insertions(+), 13 deletions(-)

--- linux-next-20241025.orig/Documentation/admin-guide/kernel-parameters.rst
+++ linux-next-20241025/Documentation/admin-guide/kernel-parameters.rst
@@ -27,6 +27,16 @@ kernel command line (/proc/cmdline) and
 when it loads a module, so the kernel command line can be used for
 loadable modules too.
 
+This document may not be entirely up to date and comprehensive. The command
+"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
+module. Loadable modules, after being loaded into the running kernel, also
+reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
+parameters may be changed at runtime by the command
+``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
+
+Special handling
+----------------
+
 Hyphens (dashes) and underscores are equivalent in parameter names, so::
 
 	log_buf_len=1M print-fatal-signals=1
@@ -39,8 +49,8 @@ Double-quotes can be used to protect spa
 
 	param="spaces in here"
 
-cpu lists:
-----------
+cpu lists
+~~~~~~~~~
 
 Some kernel parameters take a list of CPUs as a value, e.g.  isolcpus,
 nohz_full, irqaffinity, rcu_nocbs.  The format of this list is:
@@ -82,12 +92,16 @@ so that "nohz_full=all" is the equivalen
 The semantics of "N" and "all" is supported on a level of bitmaps and holds for
 all users of bitmap_parselist().
 
-This document may not be entirely up to date and comprehensive. The command
-"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
-module. Loadable modules, after being loaded into the running kernel, also
-reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
-parameters may be changed at runtime by the command
-``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
+KMG suffixes
+~~~~~~~~~~~~
+
+The [KMG] suffix is commonly described after a number of kernel
+parameter values. These 'K', 'M', and 'G' letters represent the _binary_
+multipliers 'Kilo', 'Mega', and 'Giga', equaling 2^10, 2^20, and 2^30
+bytes respectively. Such letter suffixes can also be entirely omitted.
+
+Kernel Build Options
+--------------------
 
 The parameters listed below are only valid if certain kernel build options
 were enabled and if respective hardware is present. This list should be kept
@@ -212,10 +226,5 @@ a fixed number of characters. This limit
 and is between 256 and 4096 characters. It is defined in the file
 ./include/uapi/asm-generic/setup.h as COMMAND_LINE_SIZE.
 
-Finally, the [KMG] suffix is commonly described after a number of kernel
-parameter values. These 'K', 'M', and 'G' letters represent the _binary_
-multipliers 'Kilo', 'Mega', and 'Giga', equaling 2^10, 2^20, and 2^30
-bytes respectively. Such letter suffixes can also be entirely omitted:
-
 .. include:: kernel-parameters.txt
    :literal:

Re: [PATCH] Documentation: admin: reorganize kernel-parameters intro

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1102 bytes --]

On Sun, Oct 27, 2024 at 05:53:56PM -0700, Randy Dunlap wrote:
> +This document may not be entirely up to date and comprehensive. The command
> +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
> +module. Loadable modules, after being loaded into the running kernel, also
> +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
> +parameters may be changed at runtime by the command
> +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.

How can users get support for parameters not documented here? Post to LKML
(and hoping that they also Cc: relevant maintainers and mailing list)?

> +KMG suffixes
> +~~~~~~~~~~~~
> +
> +The [KMG] suffix is commonly described after a number of kernel
> +parameter values. These 'K', 'M', and 'G' letters represent the _binary_
> +multipliers 'Kilo', 'Mega', and 'Giga', equaling 2^10, 2^20, and 2^30
> +bytes respectively. Such letter suffixes can also be entirely omitted.
> +

Metric suffixes?

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] Documentation: admin: reorganize kernel-parameters intro

[Randy Dunlap]

On 10/27/24 8:59 PM, Bagas Sanjaya wrote:
> On Sun, Oct 27, 2024 at 05:53:56PM -0700, Randy Dunlap wrote:
>> +This document may not be entirely up to date and comprehensive. The command
>> +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
>> +module. Loadable modules, after being loaded into the running kernel, also
>> +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
>> +parameters may be changed at runtime by the command
>> +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
> 
> How can users get support for parameters not documented here? Post to LKML
> (and hoping that they also Cc: relevant maintainers and mailing list)?

That's probably the best option currently.

>> +KMG suffixes
>> +~~~~~~~~~~~~
>> +
>> +The [KMG] suffix is commonly described after a number of kernel
>> +parameter values. These 'K', 'M', and 'G' letters represent the _binary_
>> +multipliers 'Kilo', 'Mega', and 'Giga', equaling 2^10, 2^20, and 2^30
>> +bytes respectively. Such letter suffixes can also be entirely omitted.
>> +
> 
> Metric suffixes?

Hm, it looks like memparse() supports all of these suffixes: K, M, G, T, P, E.

So the heading could be Metric suffixes along with some changed text.

thanks.

[waiting for more comments]

-- 
~Randy

Re: [PATCH] Documentation: admin: reorganize kernel-parameters intro

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1523 bytes --]

On Sun, Oct 27, 2024 at 09:27:50PM -0700, Randy Dunlap wrote:
> 
> 
> On 10/27/24 8:59 PM, Bagas Sanjaya wrote:
> > On Sun, Oct 27, 2024 at 05:53:56PM -0700, Randy Dunlap wrote:
> >> +This document may not be entirely up to date and comprehensive. The command
> >> +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
> >> +module. Loadable modules, after being loaded into the running kernel, also
> >> +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
> >> +parameters may be changed at runtime by the command
> >> +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
> > 
> > How can users get support for parameters not documented here? Post to LKML
> > (and hoping that they also Cc: relevant maintainers and mailing list)?
> 
> That's probably the best option currently.

OK.

> 
> >> +KMG suffixes
> >> +~~~~~~~~~~~~
> >> +
> >> +The [KMG] suffix is commonly described after a number of kernel
> >> +parameter values. These 'K', 'M', and 'G' letters represent the _binary_
> >> +multipliers 'Kilo', 'Mega', and 'Giga', equaling 2^10, 2^20, and 2^30
> >> +bytes respectively. Such letter suffixes can also be entirely omitted.
> >> +
> > 
> > Metric suffixes?
> 
> Hm, it looks like memparse() supports all of these suffixes: K, M, G, T, P, E.
> 
> So the heading could be Metric suffixes along with some changed text.
> 

Agreed.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]