[RFC,v2,0/3] Documentation: Debugging guide

Message

Sebastian Fricke Sept. 24, 2024, 8:45 a.m. UTC

The RFC 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]
Signed-off-by: Sebastian Fricke <[e-mail]>

---
Changes in v2:
- 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 (3):
      docs: media: Create separate documentation folder for media
      docs: Add guides section for debugging
      docs: media: Debugging guide for the media subsystem

 .../driver_development_debugging_guide.rst         | 193 +++++++++++++++
 Documentation/debugging/index.rst                  |  66 +++++
 .../debugging/userspace_debugging_guide.rst        | 269 +++++++++++++++++++++
 Documentation/index.rst                            |   2 +
 Documentation/media/guides/debugging_issues.rst    | 174 +++++++++++++
 Documentation/media/guides/index.rst               |  11 +
 Documentation/media/index.rst                      |  20 ++
 Documentation/subsystem-apis.rst                   |   1 +
 8 files changed, 736 insertions(+)
---
base-commit: 68a72104cbcf38ad16500216e213fa4eb21c4be2
change-id: 20240529-b4-media_docs_improve-79ea2d480483

Best regards,

Comments

Sebastian Fricke Oct. 22, 2024, 3:23 p.m. UTC | #1

(CC: Grep KH)

Hello,

On 24.09.2024 10:45, Sebastian Fricke wrote:
>The RFC 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.

I wanted to give this a little push, so far I have received a lot of
good feedback but none from the core and documentation folks. What do
you think about this?

Regards,
Sebastian

>
>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]
>Signed-off-by: Sebastian Fricke <[e-mail]>
>
>---
>Changes in v2:
>- 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 (3):
>      docs: media: Create separate documentation folder for media
>      docs: Add guides section for debugging
>      docs: media: Debugging guide for the media subsystem
>
> .../driver_development_debugging_guide.rst         | 193 +++++++++++++++
> Documentation/debugging/index.rst                  |  66 +++++
> .../debugging/userspace_debugging_guide.rst        | 269 +++++++++++++++++++++
> Documentation/index.rst                            |   2 +
> Documentation/media/guides/debugging_issues.rst    | 174 +++++++++++++
> Documentation/media/guides/index.rst               |  11 +
> Documentation/media/index.rst                      |  20 ++
> Documentation/subsystem-apis.rst                   |   1 +
> 8 files changed, 736 insertions(+)
>---
>base-commit: 68a72104cbcf38ad16500216e213fa4eb21c4be2
>change-id: 20240529-b4-media_docs_improve-79ea2d480483
>
>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.

Bagas Sanjaya Oct. 23, 2024, 6:57 a.m. UTC | #2

On Tue, Oct 22, 2024 at 05:23:16PM +0200, Sebastian Fricke wrote:
> On 24.09.2024 10:45, Sebastian Fricke wrote:
> > The RFC 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.
> 
> I wanted to give this a little push, so far I have received a lot of
> good feedback but none from the core and documentation folks. What do
> you think about this?

Address all reviews then reroll (maybe as non-RFC series).

Thanks.

Jonathan Corbet Oct. 24, 2024, 10:01 p.m. UTC | #3

Sebastian Fricke <[e-mail]> writes:

> The RFC 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.

I've just begun to take a look at this, apologies for taking so long.

Overall:

- I have been trying to reduce the number of top-level directories under
  Documentation/, and this adds two more.  Can we avoid that?  Let's
  start in that direction by putting your debugging guide inside
  Documentation/process, please.

- If we *must* create a separate "media" directory, please make it
  devices/media.  My plan is to move most of the device-specific
  documentation under Documentation/devices, making it match the source
  layout; I just haven't summoned up the energy to start the slog of
  actually doing it.

  But it would be nice to avoid that altogether here.  If we create
  Documentation/process/debugging/, it should be able to hold both your
  general and media-specific guides, and perhaps other
  subsystem-specific guides could eventually land there as well.

- Please adhere to the 80-column limit for written text.  It really does
  make a difference for people reading it.

Thanks,

jon