linux-kernel - Re: [PATCH RFC v2 0/3] Documentation: Debugging guide

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20241022152316.yr6jpjtcwidxytpe@basti-XPS-13-9310>
Date: Tue, 22 Oct 2024 17:23:16 +0200
From: Sebastian Fricke <sebastian.fricke@...labora.com>
To: Jonathan Corbet <corbet@....net>
Cc: 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,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Subject: Re: [PATCH RFC v2 0/3] Documentation: Debugging guide

(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 <corbet@....net>
>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 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 <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.