Hey Jonathan,
On 08.11.2024 09:40, Jonathan Corbet wrote:
Sebastian Fricke <sebastian.fricke@xxxxxxxxxxxxx> writes:
Hey Jonathan,
On 07.11.2024 13:35, Jonathan Corbet wrote:
Please, let's not add this to the top-level page. I've been through a
multi-year struggle trying to trim that page down to the point where it
is possible to actually find something of interest there. Everybody
wants their stuff up front, but please link this from the process guide
instead.
Hmmm ... we are talking about a page for newbies here, when it is under
process the person will have to figure out first that one has to click
on All development-process docs and then find that document under the
abundance of others. Could we atleast generate a top level page called
Beginner intro or something similar, where you are guided through the
documentation tree from the perspective of a beginner?
By the time somebody needs this document, they should be at least
wrist-deep in kernel development and should be able to find it.
Now, as per the discussion with Randy, if we decide we want to separate
"how to work on kernel code" from "how to work with the kernel
community", we can do that. We're talking about a bigger organizational
issue at this point, though.
Meanwhile, more introductory documentation is always a good thing :)
Okay, so I conclude, for the time being, I will remove the links from
the top page and make sure that the debugging page is properly linked in
the process page and we keep the debugging guide in
Documentation/process for now. Next steps can then include:
- Adding a introductory documentation page that links to the debugging
guide
- Move the debugging guide to a different location
When referencing the function, say printk() - that's the convention we
use.
Ah even in the title? Can do. (Even though it makes the titles look less
uniform..)
That would be my preference, yes.
Ack.
That is anything but full documentation of lockdep; it's really only
about RCU. I wish (hint :) that we had proper documentation for lockdep
that we could link here. For the purposes of a reader who needs this
level of guide, though, linking deep into RCU is not likely to be
helpful.
Yep I struggled finiding something useful for this topic in the docs.
I'd say I skip adding a link for now and we can create another MR later
to add a proper documentation + link in the documentation.
Sounds like a good plan to me.
Ack.
diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
new file mode 100644
index 000000000000..c200ede7c955
--- /dev/null
+++ b/Documentation/process/debugging/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================
+Debugging advice for Linux Kernel developers
+============================================
+
This file needs an introductory paragraph (at least) saying what it is
about. A simple directory listing is not hugely useful.
An alternative might be to turn your "general advice" document into the
index.rst file.
Well that is what I had in the previous iteration and Bagas Sanjaya told me:
Please split general debugging advice into its own doc (e.g. at
general-advice.rst). Most other docs have index.rst only for toctree
listing.
So, shall I revert that or should I add a intro sentence to the index
file?
Bagas is fond of giving bad but authoritative-sounding advice to
documentation contributors despite repeated requests to stop.
Unfortunately, I don't have the time to chase him around all the time
and set things straight.
My preference would be to go back to what you had, but if you prefer to
just add an intro paragraph at this point we can certainly live with it.
I go back to what I had previously. Thanks.
+ $ alias ddcmd='echo $* > /proc/dynamic_debug/control'
+ $ ddcmd '-p; file v4l2-h264.c +p'
It seems to me that the alias just obfuscates things, why bother?
Well because the Linux Kernel documentation suggests that :P
https://docs.kernel.org/admin-guide/dynamic-debug-howto.html#controlling-dynamic-debug-behaviour
If you don't like that, then I think I should send a MR for that file as
well.
Up to you, this is just something that caught my eye as I was going by.
I'd say I keep it as is for now and put this and I discuss with the
dynamic debug maintainer to see if we change that in both locations, I
wouldn't want the dynamic debug guide advice from the debugging guide to
differ from the official documentation.
+ To analyse the crash dump please use `Kdump` & `Kexec`.
Those will not *analyze* a crash dump.
Well yes they will capture the crash dump, which can then be used to
analyse the crash. Maybe a better wording is:
To capture the crash dump please use `Kdump` & `Kexec`. Below you can
find some advice for analysing the data.
better?
Yes, thanks.
Ack.
jon
Regards,
Sebastian Fricke
