Update the netconsole documentation to explain the new feature that
allows automatic population of the CPU number.

The key changes include introducing a new section titled "CPU number
auto population in userdata", explaining how to enable the CPU number
auto-population feature by writing to the "populate_cpu_nr" file in the
netconsole configfs hierarchy.

This documentation update ensures users are aware of the new CPU number
auto-population functionality and how to leverage it for better
demultiplexing and visibility of parallel netconsole output.

Signed-off-by: Breno Leitao <leitao@debian.org>
---
 Documentation/networking/netconsole.rst | 45 +++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst
index 94c4680fdf3e7e1a0020d11b44547acfd68072a5..bc9ccebdae7adadd7c57aef20a726536d7ab3173 100644
--- a/Documentation/networking/netconsole.rst
+++ b/Documentation/networking/netconsole.rst
@@ -17,6 +17,8 @@ Release prepend support by Breno Leitao <leitao@debian.org>, Jul 7 2023
 
 Userdata append support by Matthew Wood <thepacketgeek@gmail.com>, Jan 22 2024
 
+Sysdata append support by Breno Leitao <leitao@debian.org>, Jan 15 2025
+
 Please send bug reports to Matt Mackall <mpm@selenic.com>
 Satyam Sharma <satyam.sharma@gmail.com>, and Cong Wang <xiyou.wangcong@gmail.com>
 
@@ -238,6 +240,49 @@ Delete `userdata` entries with `rmdir`::
 
    It is recommended to not write user data values with newlines.
 
+CPU number auto population in userdata
+--------------------------------------
+
+Inside the netconsole configfs hierarchy, there is a file called
+`cpu_nr` under the `userdata` directory. This file is used to enable or disable
+the automatic CPU number population feature. This feature automatically
+populate the CPU number that is sending the message.
+
+To enable the CPU number auto-population::
+
+  echo 1 > /sys/kernel/config/netconsole/target1/userdata/cpu_nr
+
+When this option is enabled, the netconsole messages will include an additional
+line in the userdata field with the format `cpu=<cpu_number>`. This allows the
+receiver of the netconsole messages to easily differentiate and demultiplex
+messages originating from different CPUs, which is particularly useful when
+dealing with parallel log output.
+
+Example::
+
+  echo "This is a message" > /dev/kmsg
+  12,607,22085407756,-;This is a message
+   cpu=42
+
+In this example, the message was sent by CPU 42.
+
+.. note::
+
+   If the user has set a conflicting `cpu` key in the userdata dictionary,
+   both keys will be reported, with the kernel-populated entry appearing after
+   the user one. For example::
+
+     # User-defined CPU entry
+     mkdir -p /sys/kernel/config/netconsole/target1/userdata/cpu
+     echo "1" > /sys/kernel/config/netconsole/target1/userdata/cpu/value
+
+   Output might look like::
+
+     12,607,22085407756,-;This is a message
+      cpu=1
+      cpu=42    # kernel-populated value
+
+
 Extended console:
 =================
 

-- 
2.43.5

On 1/15/25 5:35 AM, Breno Leitao wrote:
> Update the netconsole documentation to explain the new feature that
> allows automatic population of the CPU number.
> 
> The key changes include introducing a new section titled "CPU number
> auto population in userdata", explaining how to enable the CPU number
> auto-population feature by writing to the "populate_cpu_nr" file in the
> netconsole configfs hierarchy.
> 
> This documentation update ensures users are aware of the new CPU number
> auto-population functionality and how to leverage it for better
> demultiplexing and visibility of parallel netconsole output.
> 
> Signed-off-by: Breno Leitao <leitao@debian.org>
> ---
>  Documentation/networking/netconsole.rst | 45 +++++++++++++++++++++++++++++++++
>  1 file changed, 45 insertions(+)
> 
> diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst
> index 94c4680fdf3e7e1a0020d11b44547acfd68072a5..bc9ccebdae7adadd7c57aef20a726536d7ab3173 100644
> --- a/Documentation/networking/netconsole.rst
> +++ b/Documentation/networking/netconsole.rst
> @@ -17,6 +17,8 @@ Release prepend support by Breno Leitao <leitao@debian.org>, Jul 7 2023
>  
>  Userdata append support by Matthew Wood <thepacketgeek@gmail.com>, Jan 22 2024
>  
> +Sysdata append support by Breno Leitao <leitao@debian.org>, Jan 15 2025
> +
>  Please send bug reports to Matt Mackall <mpm@selenic.com>
>  Satyam Sharma <satyam.sharma@gmail.com>, and Cong Wang <xiyou.wangcong@gmail.com>
>  
> @@ -238,6 +240,49 @@ Delete `userdata` entries with `rmdir`::
>  
>     It is recommended to not write user data values with newlines.
>  
> +CPU number auto population in userdata
> +--------------------------------------
> +
> +Inside the netconsole configfs hierarchy, there is a file called
> +`cpu_nr` under the `userdata` directory. This file is used to enable or disable
> +the automatic CPU number population feature. This feature automatically
> +populate the CPU number that is sending the message.

   populates

> +
> +To enable the CPU number auto-population::
> +
> +  echo 1 > /sys/kernel/config/netconsole/target1/userdata/cpu_nr
> +
> +When this option is enabled, the netconsole messages will include an additional
> +line in the userdata field with the format `cpu=<cpu_number>`. This allows the
> +receiver of the netconsole messages to easily differentiate and demultiplex
> +messages originating from different CPUs, which is particularly useful when
> +dealing with parallel log output.
> +
> +Example::
> +
> +  echo "This is a message" > /dev/kmsg
> +  12,607,22085407756,-;This is a message
> +   cpu=42
> +
> +In this example, the message was sent by CPU 42.
> +
> +.. note::
> +
> +   If the user has set a conflicting `cpu` key in the userdata dictionary,
> +   both keys will be reported, with the kernel-populated entry appearing after
> +   the user one. For example::
> +
> +     # User-defined CPU entry
> +     mkdir -p /sys/kernel/config/netconsole/target1/userdata/cpu
> +     echo "1" > /sys/kernel/config/netconsole/target1/userdata/cpu/value
> +
> +   Output might look like::
> +
> +     12,607,22085407756,-;This is a message
> +      cpu=1
> +      cpu=42    # kernel-populated value
> +
> +
>  Extended console:
>  =================
>  
> 

-- 
~Randy

Hello Randy,

On Wed, Jan 15, 2025 at 02:56:06PM -0800, Randy Dunlap wrote:
> On 1/15/25 5:35 AM, Breno Leitao wrote:
> > Update the netconsole documentation to explain the new feature that
> > allows automatic population of the CPU number.
> > 
> > The key changes include introducing a new section titled "CPU number
> > auto population in userdata", explaining how to enable the CPU number
> > auto-population feature by writing to the "populate_cpu_nr" file in the
> > netconsole configfs hierarchy.
> > 
> > This documentation update ensures users are aware of the new CPU number
> > auto-population functionality and how to leverage it for better
> > demultiplexing and visibility of parallel netconsole output.
> > 
> > Signed-off-by: Breno Leitao <leitao@debian.org>
> > ---
> >  Documentation/networking/netconsole.rst | 45 +++++++++++++++++++++++++++++++++
> >  1 file changed, 45 insertions(+)
> > 
> > diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst
> > index 94c4680fdf3e7e1a0020d11b44547acfd68072a5..bc9ccebdae7adadd7c57aef20a726536d7ab3173 100644
> > --- a/Documentation/networking/netconsole.rst
> > +++ b/Documentation/networking/netconsole.rst
> > @@ -17,6 +17,8 @@ Release prepend support by Breno Leitao <leitao@debian.org>, Jul 7 2023
> >  
> >  Userdata append support by Matthew Wood <thepacketgeek@gmail.com>, Jan 22 2024
> >  
> > +Sysdata append support by Breno Leitao <leitao@debian.org>, Jan 15 2025
> > +
> >  Please send bug reports to Matt Mackall <mpm@selenic.com>
> >  Satyam Sharma <satyam.sharma@gmail.com>, and Cong Wang <xiyou.wangcong@gmail.com>
> >  
> > @@ -238,6 +240,49 @@ Delete `userdata` entries with `rmdir`::
> >  
> >     It is recommended to not write user data values with newlines.
> >  
> > +CPU number auto population in userdata
> > +--------------------------------------
> > +
> > +Inside the netconsole configfs hierarchy, there is a file called
> > +`cpu_nr` under the `userdata` directory. This file is used to enable or disable
> > +the automatic CPU number population feature. This feature automatically
> > +populate the CPU number that is sending the message.
> 
>    populates

Thanks for the review, I will update.
--breno