Message-ID: <20241107140345.idv7y6udrypns4zd@basti-XPS-13-9310>
Date: Thu, 7 Nov 2024 15:03:45 +0100
From: Sebastian Fricke <sebastian.fricke@...labora.com>
To: Jonathan Corbet <corbet@....net>
Cc: bagasdotme@...il.com, linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org, linux-media@...r.kernel.org,
	laurent.pinchart@...asonboard.com, hverkuil-cisco@...all.nl,
	mauro.chehab@...ux.intel.com, kernel@...labora.com,
	bob.beckett@...labora.com, nicolas.dufresne@...labora.com
Subject: Re: [PATCH 0/2] Documentation: Debugging guide

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 <corbet@....net>
>Cc: bagasdotme@...il.com
>Cc: linux-doc@...r.kernel.org
>Cc: linux-kernel@...r.kernel.org
>Cc: linux-media@...r.kernel.org
>Cc: laurent.pinchart@...asonboard.com
>Cc: hverkuil-cisco@...all.nl
>Cc: mauro.chehab@...ux.intel.com
>Cc: kernel@...labora.com
>Cc: bob.beckett@...labora.com
>Cc: nicolas.dufresne@...labora.com
>Signed-off-by: Sebastian Fricke <sebastian.fricke@...labora.com>
>
>---
>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 <sebastian.fricke@...labora.com>
Sebastian Fricke
Consultant Software Engineer

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

Powered by blists - more mailing lists