[PATCH] Documentation: move dev-tools debugging files to process/debugging/

[PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Randy Dunlap]

Move gdb and kgdb debugging documentation to the dedicated
debugging directory (Documentation/process/debugging/).
Adjust the index.rst files to follow the file movement.
Update location of kgdb.rst in MAINTAINERS file.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Sebastian Fricke <sebastian.fricke@collabora.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: workflows@vger.kernel.org
Cc: Jason Wessel <jason.wessel@windriver.com>
Cc: Daniel Thompson <danielt@kernel.org>
Cc: Douglas Anderson <dianders@chromium.org>
Cc: linux-debuggers@vger.kernel.org
Cc: kgdb-bugreport@lists.sourceforge.net
---
 Documentation/dev-tools/index.rst                                       | 2 --
 Documentation/{dev-tools => process/debugging}/gdb-kernel-debugging.rst | 0
 Documentation/process/debugging/index.rst                               | 2 ++
 Documentation/{dev-tools => process/debugging}/kgdb.rst                 | 0
 MAINTAINERS                                                             | 2 +-
 5 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 3c0ac08b2709..c1e73e75f551 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -27,8 +27,6 @@ Documentation/dev-tools/testing-overview.rst
    kmemleak
    kcsan
    kfence
-   gdb-kernel-debugging
-   kgdb
    kselftest
    kunit/index
    ktap
diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst
similarity index 100%
rename from Documentation/dev-tools/gdb-kernel-debugging.rst
rename to Documentation/process/debugging/gdb-kernel-debugging.rst
diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
index f6e4a00dfee3..bc4a816e3d32 100644
--- a/Documentation/process/debugging/index.rst
+++ b/Documentation/process/debugging/index.rst
@@ -12,6 +12,8 @@ general guides
 
    driver_development_debugging_guide
    userspace_debugging_guide
+   gdb-kernel-debugging
+   kgdb
 
 .. only::  subproject and html
 
diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/process/debugging/kgdb.rst
similarity index 100%
rename from Documentation/dev-tools/kgdb.rst
rename to Documentation/process/debugging/kgdb.rst
diff --git a/MAINTAINERS b/MAINTAINERS
index 1e930c7a58b1..1753fe792d04 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12809,7 +12809,7 @@ L:	kgdb-bugreport@lists.sourceforge.net
 S:	Maintained
 W:	http://kgdb.wiki.kernel.org/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git
-F:	Documentation/dev-tools/kgdb.rst
+F:	Documentation/process/debugging/kgdb.rst
 F:	drivers/misc/kgdbts.c
 F:	drivers/tty/serial/kgdboc.c
 F:	include/linux/kdb.h

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Doug Anderson]

Hi,

On Wed, Dec 4, 2024 at 2:17 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
> Move gdb and kgdb debugging documentation to the dedicated
> debugging directory (Documentation/process/debugging/).
> Adjust the index.rst files to follow the file movement.
> Update location of kgdb.rst in MAINTAINERS file.
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Sebastian Fricke <sebastian.fricke@collabora.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: workflows@vger.kernel.org
> Cc: Jason Wessel <jason.wessel@windriver.com>
> Cc: Daniel Thompson <danielt@kernel.org>
> Cc: Douglas Anderson <dianders@chromium.org>
> Cc: linux-debuggers@vger.kernel.org
> Cc: kgdb-bugreport@lists.sourceforge.net
> ---
>  Documentation/dev-tools/index.rst                                       | 2 --
>  Documentation/{dev-tools => process/debugging}/gdb-kernel-debugging.rst | 0

After applying your patch and doing `git grep
gdb-kernel-debugging.rst`, I still see several references to the old
location. Those should be updated as part of this patch, right?



>  Documentation/process/debugging/index.rst                               | 2 ++
>  Documentation/{dev-tools => process/debugging}/kgdb.rst                 | 0

Similarly `git grep kgdb.rst` still has several references to the old location.

>  MAINTAINERS                                                             | 2 +-
>  5 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
> index 3c0ac08b2709..c1e73e75f551 100644
> --- a/Documentation/dev-tools/index.rst
> +++ b/Documentation/dev-tools/index.rst
> @@ -27,8 +27,6 @@ Documentation/dev-tools/testing-overview.rst
>     kmemleak
>     kcsan
>     kfence
> -   gdb-kernel-debugging
> -   kgdb
>     kselftest
>     kunit/index
>     ktap
> diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst
> similarity index 100%
> rename from Documentation/dev-tools/gdb-kernel-debugging.rst
> rename to Documentation/process/debugging/gdb-kernel-debugging.rst
> diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
> index f6e4a00dfee3..bc4a816e3d32 100644
> --- a/Documentation/process/debugging/index.rst
> +++ b/Documentation/process/debugging/index.rst
> @@ -12,6 +12,8 @@ general guides
>
>     driver_development_debugging_guide
>     userspace_debugging_guide
> +   gdb-kernel-debugging
> +   kgdb

Should the list above be kept alphabetical. The list you removed these
entries from was _almost_ alphabetical...

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Randy Dunlap]

On 12/4/24 3:07 PM, Doug Anderson wrote:
> Hi,
> 
> On Wed, Dec 4, 2024 at 2:17 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>>
>> Move gdb and kgdb debugging documentation to the dedicated
>> debugging directory (Documentation/process/debugging/).
>> Adjust the index.rst files to follow the file movement.
>> Update location of kgdb.rst in MAINTAINERS file.
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Sebastian Fricke <sebastian.fricke@collabora.com>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: workflows@vger.kernel.org
>> Cc: Jason Wessel <jason.wessel@windriver.com>
>> Cc: Daniel Thompson <danielt@kernel.org>
>> Cc: Douglas Anderson <dianders@chromium.org>
>> Cc: linux-debuggers@vger.kernel.org
>> Cc: kgdb-bugreport@lists.sourceforge.net
>> ---
>>  Documentation/dev-tools/index.rst                                       | 2 --
>>  Documentation/{dev-tools => process/debugging}/gdb-kernel-debugging.rst | 0
> 
> After applying your patch and doing `git grep
> gdb-kernel-debugging.rst`, I still see several references to the old
> location. Those should be updated as part of this patch, right?
> 
> 
> 
>>  Documentation/process/debugging/index.rst                               | 2 ++
>>  Documentation/{dev-tools => process/debugging}/kgdb.rst                 | 0
> 
> Similarly `git grep kgdb.rst` still has several references to the old location.


Thanks. I should have done that.  :(

>>  MAINTAINERS                                                             | 2 +-
>>  5 files changed, 3 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
>> index 3c0ac08b2709..c1e73e75f551 100644
>> --- a/Documentation/dev-tools/index.rst
>> +++ b/Documentation/dev-tools/index.rst
>> @@ -27,8 +27,6 @@ Documentation/dev-tools/testing-overview.rst
>>     kmemleak
>>     kcsan
>>     kfence
>> -   gdb-kernel-debugging
>> -   kgdb
>>     kselftest
>>     kunit/index
>>     ktap
>> diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst
>> similarity index 100%
>> rename from Documentation/dev-tools/gdb-kernel-debugging.rst
>> rename to Documentation/process/debugging/gdb-kernel-debugging.rst
>> diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
>> index f6e4a00dfee3..bc4a816e3d32 100644
>> --- a/Documentation/process/debugging/index.rst
>> +++ b/Documentation/process/debugging/index.rst
>> @@ -12,6 +12,8 @@ general guides
>>
>>     driver_development_debugging_guide
>>     userspace_debugging_guide
>> +   gdb-kernel-debugging
>> +   kgdb
> 
> Should the list above be kept alphabetical. The list you removed these
> entries from was _almost_ alphabetical...

Not that I know of.  I'll listen for other opinions though.

Thanks.

-- 
~Randy

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Sebastian Fricke]

Greetings!

On 04.12.2024 15:09, Randy Dunlap wrote:
>
>
>On 12/4/24 3:07 PM, Doug Anderson wrote:
>> Hi,
>>
>> On Wed, Dec 4, 2024 at 2:17 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>>>
>>> Move gdb and kgdb debugging documentation to the dedicated
>>> debugging directory (Documentation/process/debugging/).
>>> Adjust the index.rst files to follow the file movement.
>>> Update location of kgdb.rst in MAINTAINERS file.
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>> Cc: Sebastian Fricke <sebastian.fricke@collabora.com>
>>> Cc: Jonathan Corbet <corbet@lwn.net>
>>> Cc: workflows@vger.kernel.org
>>> Cc: Jason Wessel <jason.wessel@windriver.com>
>>> Cc: Daniel Thompson <danielt@kernel.org>
>>> Cc: Douglas Anderson <dianders@chromium.org>
>>> Cc: linux-debuggers@vger.kernel.org
>>> Cc: kgdb-bugreport@lists.sourceforge.net
>>> ---
>>>  Documentation/dev-tools/index.rst                                       | 2 --
>>>  Documentation/{dev-tools => process/debugging}/gdb-kernel-debugging.rst | 0
>>
>> After applying your patch and doing `git grep
>> gdb-kernel-debugging.rst`, I still see several references to the old
>> location. Those should be updated as part of this patch, right?
>>
>>
>>
>>>  Documentation/process/debugging/index.rst                               | 2 ++
>>>  Documentation/{dev-tools => process/debugging}/kgdb.rst                 | 0
>>
>> Similarly `git grep kgdb.rst` still has several references to the old location.
>
>
>Thanks. I should have done that.  :(
>
>>>  MAINTAINERS                                                             | 2 +-
>>>  5 files changed, 3 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
>>> index 3c0ac08b2709..c1e73e75f551 100644
>>> --- a/Documentation/dev-tools/index.rst
>>> +++ b/Documentation/dev-tools/index.rst
>>> @@ -27,8 +27,6 @@ Documentation/dev-tools/testing-overview.rst
>>>     kmemleak
>>>     kcsan
>>>     kfence
>>> -   gdb-kernel-debugging
>>> -   kgdb
>>>     kselftest
>>>     kunit/index
>>>     ktap
>>> diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst
>>> similarity index 100%
>>> rename from Documentation/dev-tools/gdb-kernel-debugging.rst
>>> rename to Documentation/process/debugging/gdb-kernel-debugging.rst
>>> diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
>>> index f6e4a00dfee3..bc4a816e3d32 100644
>>> --- a/Documentation/process/debugging/index.rst
>>> +++ b/Documentation/process/debugging/index.rst
>>> @@ -12,6 +12,8 @@ general guides
>>>
>>>     driver_development_debugging_guide
>>>     userspace_debugging_guide
>>> +   gdb-kernel-debugging
>>> +   kgdb
>>
>> Should the list above be kept alphabetical. The list you removed these
>> entries from was _almost_ alphabetical...
>
>Not that I know of.  I'll listen for other opinions though.

I'd say it is easy enough for us to do, so I'd advocate for making the
list alphabetical (.. even though I forgot to do that in my initial list 😅)

>
>Thanks.
>
>-- 
>~Randy
>

Regards,
Sebastian Fricke

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Randy Dunlap]

On 12/5/24 1:09 AM, Sebastian Fricke wrote:
> Greetings!
> 
> On 04.12.2024 15:09, Randy Dunlap wrote:
>>
>>
>> On 12/4/24 3:07 PM, Doug Anderson wrote:
>>> Hi,
>>>
>>> On Wed, Dec 4, 2024 at 2:17 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>>>>
>>>> Move gdb and kgdb debugging documentation to the dedicated
>>>> debugging directory (Documentation/process/debugging/).
>>>> Adjust the index.rst files to follow the file movement.
>>>> Update location of kgdb.rst in MAINTAINERS file.
>>>>
>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>>> Cc: Sebastian Fricke <sebastian.fricke@collabora.com>
>>>> Cc: Jonathan Corbet <corbet@lwn.net>
>>>> Cc: workflows@vger.kernel.org
>>>> Cc: Jason Wessel <jason.wessel@windriver.com>
>>>> Cc: Daniel Thompson <danielt@kernel.org>
>>>> Cc: Douglas Anderson <dianders@chromium.org>
>>>> Cc: linux-debuggers@vger.kernel.org
>>>> Cc: kgdb-bugreport@lists.sourceforge.net
>>>> ---
>>>>  Documentation/dev-tools/index.rst                                       | 2 --
>>>>  Documentation/{dev-tools => process/debugging}/gdb-kernel-debugging.rst | 0
>>>
>>> After applying your patch and doing `git grep
>>> gdb-kernel-debugging.rst`, I still see several references to the old
>>> location. Those should be updated as part of this patch, right?
>>>
>>>
>>>
>>>>  Documentation/process/debugging/index.rst                               | 2 ++
>>>>  Documentation/{dev-tools => process/debugging}/kgdb.rst                 | 0
>>>
>>> Similarly `git grep kgdb.rst` still has several references to the old location.
>>
>>
>> Thanks. I should have done that.  :(
>>
>>>>  MAINTAINERS                                                             | 2 +-
>>>>  5 files changed, 3 insertions(+), 3 deletions(-)
>>>>
>>>> diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
>>>> index 3c0ac08b2709..c1e73e75f551 100644
>>>> --- a/Documentation/dev-tools/index.rst
>>>> +++ b/Documentation/dev-tools/index.rst
>>>> @@ -27,8 +27,6 @@ Documentation/dev-tools/testing-overview.rst
>>>>     kmemleak
>>>>     kcsan
>>>>     kfence
>>>> -   gdb-kernel-debugging
>>>> -   kgdb
>>>>     kselftest
>>>>     kunit/index
>>>>     ktap
>>>> diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/process/debugging/gdb-kernel-debugging.rst
>>>> similarity index 100%
>>>> rename from Documentation/dev-tools/gdb-kernel-debugging.rst
>>>> rename to Documentation/process/debugging/gdb-kernel-debugging.rst
>>>> diff --git a/Documentation/process/debugging/index.rst b/Documentation/process/debugging/index.rst
>>>> index f6e4a00dfee3..bc4a816e3d32 100644
>>>> --- a/Documentation/process/debugging/index.rst
>>>> +++ b/Documentation/process/debugging/index.rst
>>>> @@ -12,6 +12,8 @@ general guides
>>>>
>>>>     driver_development_debugging_guide
>>>>     userspace_debugging_guide
>>>> +   gdb-kernel-debugging
>>>> +   kgdb
>>>
>>> Should the list above be kept alphabetical. The list you removed these
>>> entries from was _almost_ alphabetical...
>>
>> Not that I know of.  I'll listen for other opinions though.
> 
> I'd say it is easy enough for us to do, so I'd advocate for making the
> list alphabetical (.. even though I forgot to do that in my initial list 😅)

OK, will do.
Thanks.

-- 
~Randy

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Move gdb and kgdb debugging documentation to the dedicated
> debugging directory (Documentation/process/debugging/).
> Adjust the index.rst files to follow the file movement.
> Update location of kgdb.rst in MAINTAINERS file.
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

So ... since these are indeed development tools, I wonder if we should
leave a reference behind in case people are looking for them there?

jon

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Randy Dunlap]

On 12/6/24 8:38 AM, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
> 
>> Move gdb and kgdb debugging documentation to the dedicated
>> debugging directory (Documentation/process/debugging/).
>> Adjust the index.rst files to follow the file movement.
>> Update location of kgdb.rst in MAINTAINERS file.
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> 
> So ... since these are indeed development tools, I wonder if we should
> leave a reference behind in case people are looking for them there?

As far as I'm concerned, all debug tools are development tools, so I'm back
to all of /process/debugging/ should be somewhere else.  ;)

cheers.
-- 
~Randy

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Sebastian Fricke]

Hey Randy,

On 06.12.2024 15:57, Randy Dunlap wrote:
>
>
>On 12/6/24 8:38 AM, Jonathan Corbet wrote:
>> Randy Dunlap <rdunlap@infradead.org> writes:
>>
>>> Move gdb and kgdb debugging documentation to the dedicated
>>> debugging directory (Documentation/process/debugging/).
>>> Adjust the index.rst files to follow the file movement.
>>> Update location of kgdb.rst in MAINTAINERS file.
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>
>> So ... since these are indeed development tools, I wonder if we should
>> leave a reference behind in case people are looking for them there?
>
>As far as I'm concerned, all debug tools are development tools, so I'm back
>to all of /process/debugging/ should be somewhere else.  ;)

I mean this is where things just simply overlap, because debugging is
part of the development process and all debugging tools are development
tools, so I think the question is not whether one of the two places is
the "correct" but instead the user should be able to find the necessary
information by navigating to any of the two places.
So I would say, lets add a reference in the index of the development
tools that highlights the documentation of the debugging tools which are
found in the development process documentation.

>
>cheers.
>-- 
>~Randy

Regards,

Sebastian Fricke

Re: [PATCH] Documentation: move dev-tools debugging files to process/debugging/

[Randy Dunlap]

On 12/7/24 12:50 AM, Sebastian Fricke wrote:
> Hey Randy,
> 
> On 06.12.2024 15:57, Randy Dunlap wrote:
>>
>>
>> On 12/6/24 8:38 AM, Jonathan Corbet wrote:
>>> Randy Dunlap <rdunlap@infradead.org> writes:
>>>
>>>> Move gdb and kgdb debugging documentation to the dedicated
>>>> debugging directory (Documentation/process/debugging/).
>>>> Adjust the index.rst files to follow the file movement.
>>>> Update location of kgdb.rst in MAINTAINERS file.
>>>>
>>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>>
>>> So ... since these are indeed development tools, I wonder if we should
>>> leave a reference behind in case people are looking for them there?
>>
>> As far as I'm concerned, all debug tools are development tools, so I'm back
>> to all of /process/debugging/ should be somewhere else.  ;)
> 
> I mean this is where things just simply overlap, because debugging is
> part of the development process and all debugging tools are development
> tools, so I think the question is not whether one of the two places is
> the "correct" but instead the user should be able to find the necessary
> information by navigating to any of the two places.
> So I would say, lets add a reference in the index of the development
> tools that highlights the documentation of the debugging tools which are
> found in the development process documentation.
> 

Hi,

Sure, I will add entries in dev-tools/index.

Thanks.

-- 
~Randy