diff mbox series

[net-next,v5,8/8] netconsole: docs: Add documentation for CPU number auto-population

Message ID 20250206-netcon_cpu-v5-8-859b23cc3826@debian.org (mailing list archive)
State New
Headers show
Series netconsole: Add support for CPU population | expand

Commit Message

Breno Leitao Feb. 6, 2025, 11:05 a.m. UTC 
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>
Reviewed-by: Simon Horman <horms@kernel.org>
---
 Documentation/networking/netconsole.rst | 45 +++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

Comments

Bagas Sanjaya Feb. 7, 2025, 1:50 a.m. UTC | #1 
On Thu, Feb 06, 2025 at 03:05:59AM -0800, Breno Leitao wrote:
> +.. 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::

In that case, shouldn't the kernel autopopulates numbers of the rest of
CPUs?

Confused...
Breno Leitao Feb. 10, 2025, 11:07 a.m. UTC | #2 
Hello Bagas,

On Fri, Feb 07, 2025 at 08:50:22AM +0700, Bagas Sanjaya wrote:
> On Thu, Feb 06, 2025 at 03:05:59AM -0800, Breno Leitao wrote:
> > +.. 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::
> 
> In that case, shouldn't the kernel autopopulates numbers of the rest of
> CPUs?

Do you mean listing all the CPUs that are *not* sending the current
message?

Let me come up with an example to try to understand this better. Let's
suppopse I have a machine with 64 cores, and cpu=42 is sending that
current message, then I would see the following on the dictionary:

 cpu=42

You are suggesting we send all the other cpus, except 42 in a "key"?

Thanks
--breno
Bagas Sanjaya Feb. 10, 2025, 11:42 p.m. UTC | #3 
On Mon, Feb 10, 2025 at 03:07:24AM -0800, Breno Leitao wrote:
> Hello Bagas,
> 
> On Fri, Feb 07, 2025 at 08:50:22AM +0700, Bagas Sanjaya wrote:
> > On Thu, Feb 06, 2025 at 03:05:59AM -0800, Breno Leitao wrote:
> > > +.. 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::
> > 
> > In that case, shouldn't the kernel autopopulates numbers of the rest of
> > CPUs?
> 
> Do you mean listing all the CPUs that are *not* sending the current
> message?

Nope.

> 
> Let me come up with an example to try to understand this better. Let's
> suppopse I have a machine with 64 cores, and cpu=42 is sending that
> current message, then I would see the following on the dictionary:
> 
>  cpu=42
> 
> You are suggesting we send all the other cpus, except 42 in a "key"?

Sort of.

I mean, on the dictionary, we would see user-defined cpu number on one cpu,
and kernel-generated numbers on the rest.

Thanks.
diff mbox series

Patch

diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst
index 94c4680fdf3e7e1a0020d11b44547acfd68072a5..84803c59968a3237012fab821f432eb531aba45c 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
+populates 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:
 =================