[0/2] Documentation: Debugging guide

Message

Sebastian Fricke Nov. 7, 2024, 2 p.m. UTC

The series contains:
- a general debugging guide split into debugging for driver developers and
debugging from userspace
- a new summary page for all media related documentation. This is inspired by
other subsystems, which first of all allows a user to find the subsystem
under the subsystems page and secondly eases general navigation through the
documentation that is sprinkled onto multiple places.
- a guide on how to debug code in the media subsystem, which points to the
parts of the general documentation and adds own routines.

WHY do we need this?
--------------------

For anyone without years of experience in the Linux kernel, knowing which tool
to use or even which tools are available is not as straightforward as some
senior developers might perceive.
We realized that there is a general need for a kind of "start page", that
allows especially beginners to get up-to-speed with the codebase and the
documentation. The documentation in particular is currently quite hard to navigate
as you mostly have to know what you are searching for to find it.

WHAT do we cover?
-----------------

The document is structured into two sections:

1. A problem-focused approach: This means, a developer facing an issue matching
one of the given examples, will find suggestions for how to approach that
problem (e.g. which tool to use) in this section
2. A tool-focused approach: This sections highlights the available tools, with
comparisions between the tools if sensible. The goal of this work is
**duplicate as little as possible** from the existing documentation and
instead provide a rough overview that provides:
- A link to the actual documentation
- A minimal example for how it can be used (from a media perspective,
  if the usage isn't absolutely trivial like printk)
- A rational for why it should be used

To: Jonathan Corbet <[e-mail]>
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Signed-off-by: Sebastian Fricke <[e-mail]>

---
Changes in v1 (first non-RFC):
- Move the guides from Documentation/debugging to Documentation/process/debugging
- Remove the new Documentation/media folder and place the media-specific guide
  instead into Documentation/process/debugging
- Reduce the line length to 80 character wherever possible
- Exchange |code| with © and remove the include
- Remove :code: specifiers
- Exchange html links with :doc: and :ref: links, to allow sphinx to convert them correctly
- Use markdown links only when necessary 
- Various style fixes
- Improve the description for how to read a crash dump
- Split the general advice into a separate file
- Remove unnecessary labels
- Replace duplicated ftrace example with links to the documentation
- Add 2 additional debugging sections to the media debugging guide
- Replace the lkml link with the matching lore link
- Extend the error checkers section with further details
- Add intro sentences on the media debugging guide to the various sections
- Remove ftrace examples and point to the documentation instead
- Change the section depth to allow cross references via the autosectionlabels
- Add Elixir links whenever I point to a specific file

Changes in v2 (RFC):
- Split the media debugging guide into a general and a media specific guide,
which contains mostly references to the general guide and a few media
specific aspects.
- Fill out TBD sections
- Add device coredump section

---
Sebastian Fricke (2):
      docs: Add guides section for debugging
      docs: media: Debugging guide for the media subsystem

 Documentation/index.rst                            |   2 +
 .../driver_development_debugging_guide.rst         | 206 +++++++++++++++
 Documentation/process/debugging/general_advice.rst |  48 ++++
 Documentation/process/debugging/index.rst          |  22 ++
 .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++
 .../debugging/userspace_debugging_guide.rst        | 278 +++++++++++++++++++++
 6 files changed, 734 insertions(+)
---
base-commit: 8c64f4cdf4e6cc5682c52523713af8c39c94e6d5
change-id: 20241028-media_docs_improve_v3-3d7c16017713

Best regards,

Comments

Sebastian Fricke Nov. 7, 2024, 2:03 p.m. UTC | #1

Hey Jonathan,

please let me know what you think, I have played around with the links
a lot and this is the best I have figured out so far, otherwise I think
I have adressed all of the suggestions besides the FAQ reques frmo Steve
Cho, which I think can be added afterwards to the documentation as that
part requires more research.

Regards,
Sebastian

On 07.11.2024 15:00, Sebastian Fricke wrote:
>The series contains:
>- a general debugging guide split into debugging for driver developers and
>debugging from userspace
>- a new summary page for all media related documentation. This is inspired by
>other subsystems, which first of all allows a user to find the subsystem
>under the subsystems page and secondly eases general navigation through the
>documentation that is sprinkled onto multiple places.
>- a guide on how to debug code in the media subsystem, which points to the
>parts of the general documentation and adds own routines.
>
>WHY do we need this?
>--------------------
>
>For anyone without years of experience in the Linux kernel, knowing which tool
>to use or even which tools are available is not as straightforward as some
>senior developers might perceive.
>We realized that there is a general need for a kind of "start page", that
>allows especially beginners to get up-to-speed with the codebase and the
>documentation. The documentation in particular is currently quite hard to navigate
>as you mostly have to know what you are searching for to find it.
>
>WHAT do we cover?
>-----------------
>
>The document is structured into two sections:
>
>1. A problem-focused approach: This means, a developer facing an issue matching
>one of the given examples, will find suggestions for how to approach that
>problem (e.g. which tool to use) in this section
>2. A tool-focused approach: This sections highlights the available tools, with
>comparisions between the tools if sensible. The goal of this work is
>**duplicate as little as possible** from the existing documentation and
>instead provide a rough overview that provides:
>- A link to the actual documentation
>- A minimal example for how it can be used (from a media perspective,
>  if the usage isn't absolutely trivial like printk)
>- A rational for why it should be used
>
>To: Jonathan Corbet <[e-mail]>
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Cc: [e-mail]
>Signed-off-by: Sebastian Fricke <[e-mail]>
>
>---
>Changes in v1 (first non-RFC):
>- Move the guides from Documentation/debugging to Documentation/process/debugging
>- Remove the new Documentation/media folder and place the media-specific guide
>  instead into Documentation/process/debugging
>- Reduce the line length to 80 character wherever possible
>- Exchange |code| with © and remove the include
>- Remove :code: specifiers
>- Exchange html links with :doc: and :ref: links, to allow sphinx to convert them correctly
>- Use markdown links only when necessary
>- Various style fixes
>- Improve the description for how to read a crash dump
>- Split the general advice into a separate file
>- Remove unnecessary labels
>- Replace duplicated ftrace example with links to the documentation
>- Add 2 additional debugging sections to the media debugging guide
>- Replace the lkml link with the matching lore link
>- Extend the error checkers section with further details
>- Add intro sentences on the media debugging guide to the various sections
>- Remove ftrace examples and point to the documentation instead
>- Change the section depth to allow cross references via the autosectionlabels
>- Add Elixir links whenever I point to a specific file
>
>Changes in v2 (RFC):
>- Split the media debugging guide into a general and a media specific guide,
>which contains mostly references to the general guide and a few media
>specific aspects.
>- Fill out TBD sections
>- Add device coredump section
>
>---
>Sebastian Fricke (2):
>      docs: Add guides section for debugging
>      docs: media: Debugging guide for the media subsystem
>
> Documentation/index.rst                            |   2 +
> .../driver_development_debugging_guide.rst         | 206 +++++++++++++++
> Documentation/process/debugging/general_advice.rst |  48 ++++
> Documentation/process/debugging/index.rst          |  22 ++
> .../debugging/media_specific_debugging_guide.rst   | 178 +++++++++++++
> .../debugging/userspace_debugging_guide.rst        | 278 +++++++++++++++++++++
> 6 files changed, 734 insertions(+)
>---
>base-commit: 8c64f4cdf4e6cc5682c52523713af8c39c94e6d5
>change-id: 20241028-media_docs_improve_v3-3d7c16017713
>
>Best regards,
>-- 
>Sebastian Fricke <[e-mail]>
Sebastian Fricke
Consultant Software Engineer

Collabora Ltd
Platinum Building, St John's Innovation Park, Cambridge CB4 0DS, UK
Registered in England & Wales no 5513718.

Sebastian Fricke Nov. 7, 2024, 2:09 p.m. UTC | #2

Hello,

CC: Jonathan

On 07.11.2024 06:03, Patchwork Integration wrote:
>Dear Sebastian Fricke:
>
>Thanks for your patches! Unfortunately media-ci has not been able to
>test them.
>
>Make sure that the whole series <[e-mail]> is
>available at lore. And that it can be cherry-picked on top the "next"
>branch of "https://gitlab.freedesktop.org/linux-media/media-committers.git".

Woops, I have mine on the media master, but thinking about it I never
actually asked which branch my work should be on for the Documentation
subsystem.

Regards,
Sebastian

>
>Error message:
>Running in OFFLINE mode
>Analyzing 3 messages in the thread
>Checking attestation on all messages, may take a moment...
>---
>  [PATCH 1/2] docs: Add guides section for debugging
>    + Link: https://lore.kernel.org/r/[e-mail]
>  [PATCH 2/2] docs: media: Debugging guide for the media subsystem
>    + Link: https://lore.kernel.org/r/[e-mail]
>  ---
>  ✗ No key: ed25519/[e-mail]
>---
>Total patches: 2
>---
> Base: using specified base-commit 8c64f4cdf4e6cc5682c52523713af8c39c94e6d5
>Applying: docs: Add guides section for debugging
>Patch failed at 0001 docs: Add guides section for debugging
>When you have resolved this problem, run "git am --continue".
>If you prefer to skip this patch, run "git am --skip" instead.
>To restore the original branch and stop patching, run "git am --abort".
>error: patch failed: Documentation/index.rst:57
>error: Documentation/index.rst: patch does not apply
>hint: Use 'git am --show-current-patch=diff' to see the failed patch
>
>
>Best regards, and Happy Hacking!
>Media CI robot out on behalf of the linux-media community.
>
>---
>Check the latest rules for contributing your patches at:
>https://docs.kernel.org/driver-api/media/maintainer-entry-profile.html
>
>If you believe that the CI is wrong, kindly open an issue at
>https://gitlab.freedesktop.org/linux-media/media-ci/-/issues or reply-all
>to this message.
Sebastian Fricke
Consultant Software Engineer

Collabora Ltd
Platinum Building, St John's Innovation Park, Cambridge CB4 0DS, UK
Registered in England & Wales no 5513718.

Jonathan Corbet Nov. 7, 2024, 4:45 p.m. UTC | #3

Sebastian Fricke <[e-mail]> writes:

> The series contains:
> - a general debugging guide split into debugging for driver developers and
> debugging from userspace
> - a new summary page for all media related documentation. This is inspired by
> other subsystems, which first of all allows a user to find the subsystem
> under the subsystems page and secondly eases general navigation through the
> documentation that is sprinkled onto multiple places.
> - a guide on how to debug code in the media subsystem, which points to the
> parts of the general documentation and adds own routines.

So I am just getting into looking at this; the fact that I had a hard
time applying the series has not helped...

> base-commit: 8c64f4cdf4e6cc5682c52523713af8c39c94e6d5

That is ... 6.9?  Why are you basing your patches on such an ancient
kernel?  If you want me to apply them for 6.12 (not guaranteed in any
case, it's getting late) you'll need to bring them forward to current
docs-next.

Thanks,

jon

Sebastian Fricke Nov. 7, 2024, 5:57 p.m. UTC | #4

Hey Jon,

On 07.11.2024 09:45, Jonathan Corbet wrote:
>Sebastian Fricke <[e-mail]> writes:
>
>> The series contains:
>> - a general debugging guide split into debugging for driver developers and
>> debugging from userspace
>> - a new summary page for all media related documentation. This is inspired by
>> other subsystems, which first of all allows a user to find the subsystem
>> under the subsystems page and secondly eases general navigation through the
>> documentation that is sprinkled onto multiple places.
>> - a guide on how to debug code in the media subsystem, which points to the
>> parts of the general documentation and adds own routines.
>
>So I am just getting into looking at this; the fact that I had a hard
>time applying the series has not helped...
>
>> base-commit: 8c64f4cdf4e6cc5682c52523713af8c39c94e6d5
>
>That is ... 6.9?  Why are you basing your patches on such an ancient
>kernel?  If you want me to apply them for 6.12 (not guaranteed in any
>case, it's getting late) you'll need to bring them forward to current
>docs-next.

Yes sorry something must be wrong in with my master tree here, I will
rebase on docs-next and do a respin once I know whether something else
needs to be fixed.

>
>Thanks,
>
>jon
>

Regards,

Sebastian Fricke

Sebastian Fricke Nov. 8, 2024, 8:24 a.m. UTC | #5

Hey Jon,

On 07.11.2024 09:45, Jonathan Corbet wrote:
>Sebastian Fricke <[e-mail]> writes:
>
>> The series contains:
>> - a general debugging guide split into debugging for driver developers and
>> debugging from userspace
>> - a new summary page for all media related documentation. This is inspired by
>> other subsystems, which first of all allows a user to find the subsystem
>> under the subsystems page and secondly eases general navigation through the
>> documentation that is sprinkled onto multiple places.
>> - a guide on how to debug code in the media subsystem, which points to the
>> parts of the general documentation and adds own routines.
>
>So I am just getting into looking at this; the fact that I had a hard
>time applying the series has not helped...
>
>> base-commit: 8c64f4cdf4e6cc5682c52523713af8c39c94e6d5
>
>That is ... 6.9?  Why are you basing your patches on such an ancient
>kernel?  If you want me to apply them for 6.12 (not guaranteed in any
>case, it's getting late) you'll need to bring them forward to current
>docs-next.

Hmmm my Google-Fu is not strong enough, I can't find a docs-next
anywhere neither in https://git.kernel.org/ nor in the Linux Kernel
documentation, can you point me to the tree?

>
>Thanks,
>
>jon
>

Regards,
Sebastian Fricke

Bagas Sanjaya Nov. 8, 2024, 8:58 a.m. UTC | #6

On Fri, Nov 08, 2024 at 09:24:16AM +0100, Sebastian Fricke wrote:
> Hmmm my Google-Fu is not strong enough, I can't find a docs-next
> anywhere neither in https://git.kernel.org/ nor in the Linux Kernel
> documentation, can you point me to the tree?

git fetch git://git.lwn.net/linux.git docs-next

Thanks.

Jonathan Corbet Nov. 8, 2024, 2:45 p.m. UTC | #7

Sebastian Fricke <[e-mail]> writes:

> Hmmm my Google-Fu is not strong enough, I can't find a docs-next
> anywhere neither in https://git.kernel.org/ nor in the Linux Kernel
> documentation, can you point me to the tree?

That's what the MAINTAINERS file is for:

> DOCUMENTATION
> M:	Jonathan Corbet <[e-mail]>
> L:	[e-mail]
> S:	Maintained
> P:	Documentation/doc-guide/maintainer-profile.rst
> T:	git git://git.lwn.net/linux.git docs-next
> F:	Documentation/
> ...

Thanks,

jon