[PATCH 18/39] docs: admin-guide: add kdump documentation into it

[PATCH 18/39] docs: admin-guide: add kdump documentation into it

[Mauro Carvalho Chehab]

The Kdump documentation describes procedures with admins use
in order to solve issues on their systems.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/admin-guide/bug-hunting.rst            | 4 ++--
 Documentation/admin-guide/index.rst                  | 1 +
 Documentation/{ => admin-guide}/kdump/gdbmacros.txt  | 0
 Documentation/{ => admin-guide}/kdump/index.rst      | 1 -
 Documentation/{ => admin-guide}/kdump/kdump.rst      | 0
 Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst | 0
 Documentation/admin-guide/kernel-parameters.txt      | 6 +++---
 Documentation/powerpc/firmware-assisted-dump.rst     | 2 +-
 Documentation/translations/zh_CN/oops-tracing.txt    | 4 ++--
 Documentation/watchdog/hpwdt.rst                     | 2 +-
 MAINTAINERS                                          | 2 +-
 arch/arm/Kconfig                                     | 2 +-
 arch/arm64/Kconfig                                   | 2 +-
 arch/sh/Kconfig                                      | 2 +-
 arch/x86/Kconfig                                     | 4 ++--
 15 files changed, 16 insertions(+), 16 deletions(-)
 rename Documentation/{ => admin-guide}/kdump/gdbmacros.txt (100%)
 rename Documentation/{ => admin-guide}/kdump/index.rst (97%)
 rename Documentation/{ => admin-guide}/kdump/kdump.rst (100%)
 rename Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst (100%)

diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
index b761aa2a51d2..44b8a4edd348 100644
--- a/Documentation/admin-guide/bug-hunting.rst
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -90,9 +90,9 @@ the disk is not available then you have three options:
     run a null modem to a second machine and capture the output there
     using your favourite communication program.  Minicom works well.
 
-(3) Use Kdump (see Documentation/kdump/kdump.rst),
+(3) Use Kdump (see Documentation/admin-guide/kdump/kdump.rst),
     extract the kernel ring buffer from old memory with using dmesg
-    gdbmacro in Documentation/kdump/gdbmacros.txt.
+    gdbmacro in Documentation/admin-guide/kdump/gdbmacros.txt.
 
 Finding the bug's location
 --------------------------
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 9899b78dbe50..65e821a03aca 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -39,6 +39,7 @@ problems and bugs in particular.
    ramoops
    dynamic-debug-howto
    init
+   kdump/index
    perf/index
 
 This is the beginning of a section with information of interest to
diff --git a/Documentation/kdump/gdbmacros.txt b/Documentation/admin-guide/kdump/gdbmacros.txt
similarity index 100%
rename from Documentation/kdump/gdbmacros.txt
rename to Documentation/admin-guide/kdump/gdbmacros.txt
diff --git a/Documentation/kdump/index.rst b/Documentation/admin-guide/kdump/index.rst
similarity index 97%
rename from Documentation/kdump/index.rst
rename to Documentation/admin-guide/kdump/index.rst
index 2b17fcf6867a..8e2ebd0383cd 100644
--- a/Documentation/kdump/index.rst
+++ b/Documentation/admin-guide/kdump/index.rst
@@ -1,4 +1,3 @@
-:orphan:
 
 ================================================================
 Documentation for Kdump - The kexec-based Crash Dumping Solution
diff --git a/Documentation/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst
similarity index 100%
rename from Documentation/kdump/kdump.rst
rename to Documentation/admin-guide/kdump/kdump.rst
diff --git a/Documentation/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst
similarity index 100%
rename from Documentation/kdump/vmcoreinfo.rst
rename to Documentation/admin-guide/kdump/vmcoreinfo.rst
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index e38b96d061f4..9b535c0e22f3 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -708,14 +708,14 @@
 			[KNL, x86_64] select a region under 4G first, and
 			fall back to reserve region above 4G when '@offset'
 			hasn't been specified.
-			See Documentation/kdump/kdump.rst for further details.
+			See Documentation/admin-guide/kdump/kdump.rst for further details.
 
 	crashkernel=range1:size1[,range2:size2,...][@offset]
 			[KNL] Same as above, but depends on the memory
 			in the running system. The syntax of range is
 			start-[end] where start and end are both
 			a memory unit (amount[KMG]). See also
-			Documentation/kdump/kdump.rst for an example.
+			Documentation/admin-guide/kdump/kdump.rst for an example.
 
 	crashkernel=size[KMG],high
 			[KNL, x86_64] range could be above 4G. Allow kernel
@@ -1207,7 +1207,7 @@
 			Specifies physical address of start of kernel core
 			image elf header and optionally the size. Generally
 			kexec loader will pass this option to capture kernel.
-			See Documentation/kdump/kdump.rst for details.
+			See Documentation/admin-guide/kdump/kdump.rst for details.
 
 	enable_mtrr_cleanup [X86]
 			The kernel tries to adjust MTRR layout from continuous
diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/powerpc/firmware-assisted-dump.rst
index d7fa7c35dd12..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.rst
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -61,7 +61,7 @@ as follows:
          the default calculated size. Use this option if default
          boot memory size is not sufficient for second kernel to
          boot successfully. For syntax of crashkernel= parameter,
-         refer to Documentation/kdump/kdump.rst. If any offset is
+         refer to Documentation/admin-guide/kdump/kdump.rst. If any offset is
          provided in crashkernel= parameter, it will be ignored
          as fadump uses a predefined offset to reserve memory
          for boot memory dump preservation in case of a crash.
diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt
index 368ddd05b304..c5f3bda7abcb 100644
--- a/Documentation/translations/zh_CN/oops-tracing.txt
+++ b/Documentation/translations/zh_CN/oops-tracing.txt
@@ -53,8 +53,8 @@ cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“
 （2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null
 modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。
 
-（3）使用Kdump（请参看Documentation/kdump/kdump.rst），
-使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
+（3）使用Kdump（请参看Documentation/admin-guide/kdump/kdump.rst），
+使用在Documentation/admin-guide/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
 环形缓冲区。
 
 完整信息
diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst
index 94a96371113e..49c647dba8aa 100644
--- a/Documentation/watchdog/hpwdt.rst
+++ b/Documentation/watchdog/hpwdt.rst
@@ -59,7 +59,7 @@ Last reviewed: 08/20/2018
  and loop forever.  This is generally not what a watchdog user wants.
 
  For those wishing to learn more please see:
-	Documentation/kdump/kdump.rst
+	Documentation/admin-guide/kdump/kdump.rst
 	Documentation/admin-guide/kernel-parameters.txt (panic=)
 	Your Linux Distribution specific documentation.
 
diff --git a/MAINTAINERS b/MAINTAINERS
index d35ff73f718a..4c622a19ab7d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8622,7 +8622,7 @@ R:	Vivek Goyal <vgoyal@redhat.com>
 L:	kexec@lists.infradead.org
 W:	http://lse.sourceforge.net/kdump/
 S:	Maintained
-F:	Documentation/kdump/
+F:	Documentation/admin-guide/kdump/
 
 KEENE FM RADIO TRANSMITTER DRIVER
 M:	Hans Verkuil <hverkuil@xs4all.nl>
diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index 8bf8985ec667..d5bd4350fcbd 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -2025,7 +2025,7 @@ config CRASH_DUMP
 	  kdump/kexec. The crash dump kernel must be compiled to a
 	  memory address not used by the main kernel
 
-	  For more details see Documentation/kdump/kdump.rst
+	  For more details see Documentation/admin-guide/kdump/kdump.rst
 
 config AUTO_ZRELADDR
 	bool "Auto calculation of the decompressed kernel image address"
diff --git a/arch/arm64/Kconfig b/arch/arm64/Kconfig
index accb045997c6..e1ea69994e0f 100644
--- a/arch/arm64/Kconfig
+++ b/arch/arm64/Kconfig
@@ -997,7 +997,7 @@ config CRASH_DUMP
 	  reserved region and then later executed after a crash by
 	  kdump/kexec.
 
-	  For more details see Documentation/kdump/kdump.rst
+	  For more details see Documentation/admin-guide/kdump/kdump.rst
 
 config XEN_DOM0
 	def_bool y
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index 31a7d12db705..c2858ac6a46a 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -626,7 +626,7 @@ config CRASH_DUMP
 	  to a memory address not used by the main kernel using
 	  PHYSICAL_START.
 
-	  For more details see Documentation/kdump/kdump.rst
+	  For more details see Documentation/admin-guide/kdump/kdump.rst
 
 config KEXEC_JUMP
 	bool "kexec jump (EXPERIMENTAL)"
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index c9d59ca5e3ac..489fd833b980 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -2057,7 +2057,7 @@ config CRASH_DUMP
 	  to a memory address not used by the main kernel or BIOS using
 	  PHYSICAL_START, or it must be built as a relocatable image
 	  (CONFIG_RELOCATABLE=y).
-	  For more details see Documentation/kdump/kdump.rst
+	  For more details see Documentation/admin-guide/kdump/kdump.rst
 
 config KEXEC_JUMP
 	bool "kexec jump"
@@ -2094,7 +2094,7 @@ config PHYSICAL_START
 	  the reserved region.  In other words, it can be set based on
 	  the "X" value as specified in the "crashkernel=YM@XM"
 	  command line boot parameter passed to the panic-ed
-	  kernel. Please take a look at Documentation/kdump/kdump.rst
+	  kernel. Please take a look at Documentation/admin-guide/kdump/kdump.rst
 	  for more details about crash dumps.
 
 	  Usage of bzImage for capturing the crash dump is recommended as
-- 
2.21.0

[PATCH 37/39] docs: adds some directories to the main documentation index

[Mauro Carvalho Chehab]

The contents of those directories were orphaned at the documentation
body.

While those directories could likely be moved to be inside some guide,
I'm opting to just adding their indexes to the main one, removing the
:orphan: and adding the SPDX header.

For the drivers, the rationale is that the documentation contains
a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on
separate directories, as we've be doing with similar subsystem-specific
docs that were not split yet.

For the others, well... I'm too lazy to do the move. Also, it
seems to make sense to keep at least some of those at the main
dir (like kbuild, for example). In any case, a latter patch
could do the move.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/cdrom/index.rst           |  2 +-
 Documentation/fault-injection/index.rst |  2 +-
 Documentation/fb/index.rst              |  2 +-
 Documentation/fpga/index.rst            |  2 +-
 Documentation/ide/index.rst             |  2 +-
 Documentation/index.rst                 | 14 ++++++++++++++
 Documentation/kbuild/index.rst          |  2 +-
 Documentation/livepatch/index.rst       |  2 +-
 Documentation/netlabel/index.rst        |  2 +-
 Documentation/pcmcia/index.rst          |  2 +-
 Documentation/power/index.rst           |  2 +-
 Documentation/target/index.rst          |  2 +-
 Documentation/timers/index.rst          |  2 +-
 Documentation/watchdog/index.rst        |  2 +-
 14 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/Documentation/cdrom/index.rst b/Documentation/cdrom/index.rst
index efbd5d111825..338ad5f94e7c 100644
--- a/Documentation/cdrom/index.rst
+++ b/Documentation/cdrom/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 =====
 cdrom
diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst
index 92b5639ed07a..8408a8a91b34 100644
--- a/Documentation/fault-injection/index.rst
+++ b/Documentation/fault-injection/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ===============
 fault-injection
diff --git a/Documentation/fb/index.rst b/Documentation/fb/index.rst
index d47313714635..baf02393d8ee 100644
--- a/Documentation/fb/index.rst
+++ b/Documentation/fb/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ============
 Frame Buffer
diff --git a/Documentation/fpga/index.rst b/Documentation/fpga/index.rst
index 2c87d1ea084f..f80f95667ca2 100644
--- a/Documentation/fpga/index.rst
+++ b/Documentation/fpga/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ====
 fpga
diff --git a/Documentation/ide/index.rst b/Documentation/ide/index.rst
index 45bc12d3957f..813dfe611a31 100644
--- a/Documentation/ide/index.rst
+++ b/Documentation/ide/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ==================================
 Integrated Drive Electronics (IDE)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e69d2fde7735..075c732501a2 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -35,6 +35,7 @@ trying to get it to work optimally on a given system.
    :maxdepth: 2
 
    admin-guide/index
+   kbuild/index
 
 Firmware-related documentation
 ------------------------------
@@ -77,6 +78,9 @@ merged much easier.
    kernel-hacking/index
    trace/index
    maintainer/index
+   fault-injection/index
+   livepatch/index
+
 
 Kernel API documentation
 ------------------------
@@ -94,12 +98,22 @@ needed).
    core-api/index
    accounting/index
    block/index
+   cdrom/index
+   ide/index
+   fb/index
+   fpga/index
    hid/index
    iio/index
    infiniband/index
    leds/index
    media/index
+   netlabel/index
    networking/index
+   pcmcia/index
+   power/index
+   target/index
+   timers/index
+   watchdog/index
    input/index
    hwmon/index
    gpu/index
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
index 42d4cbe4460c..e323a3f2cc81 100644
--- a/Documentation/kbuild/index.rst
+++ b/Documentation/kbuild/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ===================
 Kernel Build System
diff --git a/Documentation/livepatch/index.rst b/Documentation/livepatch/index.rst
index edd291d51847..17674a9e21b2 100644
--- a/Documentation/livepatch/index.rst
+++ b/Documentation/livepatch/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ===================
 Kernel Livepatching
diff --git a/Documentation/netlabel/index.rst b/Documentation/netlabel/index.rst
index 47f1e0e5acd1..984e1b191b12 100644
--- a/Documentation/netlabel/index.rst
+++ b/Documentation/netlabel/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ========
 NetLabel
diff --git a/Documentation/pcmcia/index.rst b/Documentation/pcmcia/index.rst
index 779c8527109e..7ae1f62fca14 100644
--- a/Documentation/pcmcia/index.rst
+++ b/Documentation/pcmcia/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ======
 pcmcia
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
index 20415f21e48a..002e42745263 100644
--- a/Documentation/power/index.rst
+++ b/Documentation/power/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ================
 Power Management
diff --git a/Documentation/target/index.rst b/Documentation/target/index.rst
index b68f48982392..4b24f81f747e 100644
--- a/Documentation/target/index.rst
+++ b/Documentation/target/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ==================
 TCM Virtual Device
diff --git a/Documentation/timers/index.rst b/Documentation/timers/index.rst
index 91f6f8263c48..df510ad0c989 100644
--- a/Documentation/timers/index.rst
+++ b/Documentation/timers/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ======
 timers
diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst
index 33a0de631e84..c177645081d8 100644
--- a/Documentation/watchdog/index.rst
+++ b/Documentation/watchdog/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ======================
 Linux Watchdog Support
-- 
2.21.0

Re: [PATCH 37/39] docs: adds some directories to the main documentation index

[Bartlomiej Zolnierkiewicz]

On 6/28/19 2:30 PM, Mauro Carvalho Chehab wrote:
> The contents of those directories were orphaned at the documentation
> body.
> 
> While those directories could likely be moved to be inside some guide,
> I'm opting to just adding their indexes to the main one, removing the
> :orphan: and adding the SPDX header.
> 
> For the drivers, the rationale is that the documentation contains
> a mix of Kernelspace, uAPI and admin-guide. So, better to keep them on
> separate directories, as we've be doing with similar subsystem-specific
> docs that were not split yet.
> 
> For the others, well... I'm too lazy to do the move. Also, it
> seems to make sense to keep at least some of those at the main
> dir (like kbuild, for example). In any case, a latter patch
> could do the move.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Acked-by: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>

> ---
>  Documentation/cdrom/index.rst           |  2 +-
>  Documentation/fault-injection/index.rst |  2 +-
>  Documentation/fb/index.rst              |  2 +-
>  Documentation/fpga/index.rst            |  2 +-
>  Documentation/ide/index.rst             |  2 +-
>  Documentation/index.rst                 | 14 ++++++++++++++
>  Documentation/kbuild/index.rst          |  2 +-
>  Documentation/livepatch/index.rst       |  2 +-
>  Documentation/netlabel/index.rst        |  2 +-
>  Documentation/pcmcia/index.rst          |  2 +-
>  Documentation/power/index.rst           |  2 +-
>  Documentation/target/index.rst          |  2 +-
>  Documentation/timers/index.rst          |  2 +-
>  Documentation/watchdog/index.rst        |  2 +-
>  14 files changed, 27 insertions(+), 13 deletions(-)
Best regards,
--
Bartlomiej Zolnierkiewicz
Samsung R&D Institute Poland
Samsung Electronics

Re: [PATCH 18/39] docs: admin-guide: add kdump documentation into it

[Alex Shi]

在 2019/6/28 下午8:30, Mauro Carvalho Chehab 写道:
> The Kdump documentation describes procedures with admins use
> in order to solve issues on their systems.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  Documentation/admin-guide/bug-hunting.rst            | 4 ++--
>  Documentation/admin-guide/index.rst                  | 1 +
>  Documentation/{ => admin-guide}/kdump/gdbmacros.txt  | 0
>  Documentation/{ => admin-guide}/kdump/index.rst      | 1 -
>  Documentation/{ => admin-guide}/kdump/kdump.rst      | 0
>  Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst | 0

I am not sure if it's convenience for people to have more levels in docs.

But I guess, move archs into a Documentation/arch/ dir should be fine. like Documentation/arch/{x86,arm,arm64,ia64,m68k,s390,powerpc,...}

Thanks
Alex

Re: [PATCH 18/39] docs: admin-guide: add kdump documentation into it

[Dave Young]

On 06/28/19 at 09:30am, Mauro Carvalho Chehab wrote:
> The Kdump documentation describes procedures with admins use
> in order to solve issues on their systems.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  Documentation/admin-guide/bug-hunting.rst            | 4 ++--
>  Documentation/admin-guide/index.rst                  | 1 +
>  Documentation/{ => admin-guide}/kdump/gdbmacros.txt  | 0
>  Documentation/{ => admin-guide}/kdump/index.rst      | 1 -
>  Documentation/{ => admin-guide}/kdump/kdump.rst      | 0
>  Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst | 0
>  Documentation/admin-guide/kernel-parameters.txt      | 6 +++---
>  Documentation/powerpc/firmware-assisted-dump.rst     | 2 +-
>  Documentation/translations/zh_CN/oops-tracing.txt    | 4 ++--
>  Documentation/watchdog/hpwdt.rst                     | 2 +-
>  MAINTAINERS                                          | 2 +-
>  arch/arm/Kconfig                                     | 2 +-
>  arch/arm64/Kconfig                                   | 2 +-
>  arch/sh/Kconfig                                      | 2 +-
>  arch/x86/Kconfig                                     | 4 ++--
>  15 files changed, 16 insertions(+), 16 deletions(-)
>  rename Documentation/{ => admin-guide}/kdump/gdbmacros.txt (100%)
>  rename Documentation/{ => admin-guide}/kdump/index.rst (97%)
>  rename Documentation/{ => admin-guide}/kdump/kdump.rst (100%)
>  rename Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst (100%)
> 
> diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst
> index b761aa2a51d2..44b8a4edd348 100644
> --- a/Documentation/admin-guide/bug-hunting.rst
> +++ b/Documentation/admin-guide/bug-hunting.rst
> @@ -90,9 +90,9 @@ the disk is not available then you have three options:
>      run a null modem to a second machine and capture the output there
>      using your favourite communication program.  Minicom works well.
>  
> -(3) Use Kdump (see Documentation/kdump/kdump.rst),
> +(3) Use Kdump (see Documentation/admin-guide/kdump/kdump.rst),
>      extract the kernel ring buffer from old memory with using dmesg
> -    gdbmacro in Documentation/kdump/gdbmacros.txt.
> +    gdbmacro in Documentation/admin-guide/kdump/gdbmacros.txt.
>  
>  Finding the bug's location
>  --------------------------
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 9899b78dbe50..65e821a03aca 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -39,6 +39,7 @@ problems and bugs in particular.
>     ramoops
>     dynamic-debug-howto
>     init
> +   kdump/index
>     perf/index
>  
>  This is the beginning of a section with information of interest to
> diff --git a/Documentation/kdump/gdbmacros.txt b/Documentation/admin-guide/kdump/gdbmacros.txt
> similarity index 100%
> rename from Documentation/kdump/gdbmacros.txt
> rename to Documentation/admin-guide/kdump/gdbmacros.txt
> diff --git a/Documentation/kdump/index.rst b/Documentation/admin-guide/kdump/index.rst
> similarity index 97%
> rename from Documentation/kdump/index.rst
> rename to Documentation/admin-guide/kdump/index.rst
> index 2b17fcf6867a..8e2ebd0383cd 100644
> --- a/Documentation/kdump/index.rst
> +++ b/Documentation/admin-guide/kdump/index.rst
> @@ -1,4 +1,3 @@
> -:orphan:
>  
>  ================================================================
>  Documentation for Kdump - The kexec-based Crash Dumping Solution
> diff --git a/Documentation/kdump/kdump.rst b/Documentation/admin-guide/kdump/kdump.rst
> similarity index 100%
> rename from Documentation/kdump/kdump.rst
> rename to Documentation/admin-guide/kdump/kdump.rst
> diff --git a/Documentation/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst
> similarity index 100%
> rename from Documentation/kdump/vmcoreinfo.rst
> rename to Documentation/admin-guide/kdump/vmcoreinfo.rst
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index e38b96d061f4..9b535c0e22f3 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -708,14 +708,14 @@
>  			[KNL, x86_64] select a region under 4G first, and
>  			fall back to reserve region above 4G when '@offset'
>  			hasn't been specified.
> -			See Documentation/kdump/kdump.rst for further details.
> +			See Documentation/admin-guide/kdump/kdump.rst for further details.
>  
>  	crashkernel=range1:size1[,range2:size2,...][@offset]
>  			[KNL] Same as above, but depends on the memory
>  			in the running system. The syntax of range is
>  			start-[end] where start and end are both
>  			a memory unit (amount[KMG]). See also
> -			Documentation/kdump/kdump.rst for an example.
> +			Documentation/admin-guide/kdump/kdump.rst for an example.
>  
>  	crashkernel=size[KMG],high
>  			[KNL, x86_64] range could be above 4G. Allow kernel
> @@ -1207,7 +1207,7 @@
>  			Specifies physical address of start of kernel core
>  			image elf header and optionally the size. Generally
>  			kexec loader will pass this option to capture kernel.
> -			See Documentation/kdump/kdump.rst for details.
> +			See Documentation/admin-guide/kdump/kdump.rst for details.
>  
>  	enable_mtrr_cleanup [X86]
>  			The kernel tries to adjust MTRR layout from continuous
> diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/powerpc/firmware-assisted-dump.rst
> index d7fa7c35dd12..9ca12830a48e 100644
> --- a/Documentation/powerpc/firmware-assisted-dump.rst
> +++ b/Documentation/powerpc/firmware-assisted-dump.rst
> @@ -61,7 +61,7 @@ as follows:
>           the default calculated size. Use this option if default
>           boot memory size is not sufficient for second kernel to
>           boot successfully. For syntax of crashkernel= parameter,
> -         refer to Documentation/kdump/kdump.rst. If any offset is
> +         refer to Documentation/admin-guide/kdump/kdump.rst. If any offset is
>           provided in crashkernel= parameter, it will be ignored
>           as fadump uses a predefined offset to reserve memory
>           for boot memory dump preservation in case of a crash.
> diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt
> index 368ddd05b304..c5f3bda7abcb 100644
> --- a/Documentation/translations/zh_CN/oops-tracing.txt
> +++ b/Documentation/translations/zh_CN/oops-tracing.txt
> @@ -53,8 +53,8 @@ cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“
>  （2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null
>  modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。
>  
> -（3）使用Kdump（请参看Documentation/kdump/kdump.rst），
> -使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
> +（3）使用Kdump（请参看Documentation/admin-guide/kdump/kdump.rst），
> +使用在Documentation/admin-guide/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
>  环形缓冲区。
>  
>  完整信息
> diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst
> index 94a96371113e..49c647dba8aa 100644
> --- a/Documentation/watchdog/hpwdt.rst
> +++ b/Documentation/watchdog/hpwdt.rst
> @@ -59,7 +59,7 @@ Last reviewed: 08/20/2018
>   and loop forever.  This is generally not what a watchdog user wants.
>  
>   For those wishing to learn more please see:
> -	Documentation/kdump/kdump.rst
> +	Documentation/admin-guide/kdump/kdump.rst
>  	Documentation/admin-guide/kernel-parameters.txt (panic=)
>  	Your Linux Distribution specific documentation.
>  
> diff --git a/MAINTAINERS b/MAINTAINERS
> index d35ff73f718a..4c622a19ab7d 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8622,7 +8622,7 @@ R:	Vivek Goyal <vgoyal@redhat.com>
>  L:	kexec@lists.infradead.org
>  W:	http://lse.sourceforge.net/kdump/
>  S:	Maintained
> -F:	Documentation/kdump/
> +F:	Documentation/admin-guide/kdump/
>  
>  KEENE FM RADIO TRANSMITTER DRIVER
>  M:	Hans Verkuil <hverkuil@xs4all.nl>
> diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
> index 8bf8985ec667..d5bd4350fcbd 100644
> --- a/arch/arm/Kconfig
> +++ b/arch/arm/Kconfig
> @@ -2025,7 +2025,7 @@ config CRASH_DUMP
>  	  kdump/kexec. The crash dump kernel must be compiled to a
>  	  memory address not used by the main kernel
>  
> -	  For more details see Documentation/kdump/kdump.rst
> +	  For more details see Documentation/admin-guide/kdump/kdump.rst
>  
>  config AUTO_ZRELADDR
>  	bool "Auto calculation of the decompressed kernel image address"
> diff --git a/arch/arm64/Kconfig b/arch/arm64/Kconfig
> index accb045997c6..e1ea69994e0f 100644
> --- a/arch/arm64/Kconfig
> +++ b/arch/arm64/Kconfig
> @@ -997,7 +997,7 @@ config CRASH_DUMP
>  	  reserved region and then later executed after a crash by
>  	  kdump/kexec.
>  
> -	  For more details see Documentation/kdump/kdump.rst
> +	  For more details see Documentation/admin-guide/kdump/kdump.rst
>  
>  config XEN_DOM0
>  	def_bool y
> diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
> index 31a7d12db705..c2858ac6a46a 100644
> --- a/arch/sh/Kconfig
> +++ b/arch/sh/Kconfig
> @@ -626,7 +626,7 @@ config CRASH_DUMP
>  	  to a memory address not used by the main kernel using
>  	  PHYSICAL_START.
>  
> -	  For more details see Documentation/kdump/kdump.rst
> +	  For more details see Documentation/admin-guide/kdump/kdump.rst
>  
>  config KEXEC_JUMP
>  	bool "kexec jump (EXPERIMENTAL)"
> diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
> index c9d59ca5e3ac..489fd833b980 100644
> --- a/arch/x86/Kconfig
> +++ b/arch/x86/Kconfig
> @@ -2057,7 +2057,7 @@ config CRASH_DUMP
>  	  to a memory address not used by the main kernel or BIOS using
>  	  PHYSICAL_START, or it must be built as a relocatable image
>  	  (CONFIG_RELOCATABLE=y).
> -	  For more details see Documentation/kdump/kdump.rst
> +	  For more details see Documentation/admin-guide/kdump/kdump.rst
>  
>  config KEXEC_JUMP
>  	bool "kexec jump"
> @@ -2094,7 +2094,7 @@ config PHYSICAL_START
>  	  the reserved region.  In other words, it can be set based on
>  	  the "X" value as specified in the "crashkernel=YM@XM"
>  	  command line boot parameter passed to the panic-ed
> -	  kernel. Please take a look at Documentation/kdump/kdump.rst
> +	  kernel. Please take a look at Documentation/admin-guide/kdump/kdump.rst
>  	  for more details about crash dumps.
>  
>  	  Usage of bzImage for capturing the crash dump is recommended as
> -- 
> 2.21.0
> 

Acked-by: Dave Young <dyoung@redhat.com>

Thanks
Dave

Re: [PATCH 18/39] docs: admin-guide: add kdump documentation into it

[Dave Young]

On 07/05/19 at 11:43am, Alex Shi wrote:
> 
> 
> 在 2019/6/28 下午8:30, Mauro Carvalho Chehab 写道:
> > The Kdump documentation describes procedures with admins use
> > in order to solve issues on their systems.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >  Documentation/admin-guide/bug-hunting.rst            | 4 ++--
> >  Documentation/admin-guide/index.rst                  | 1 +
> >  Documentation/{ => admin-guide}/kdump/gdbmacros.txt  | 0
> >  Documentation/{ => admin-guide}/kdump/index.rst      | 1 -
> >  Documentation/{ => admin-guide}/kdump/kdump.rst      | 0
> >  Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst | 0
> 
> I am not sure if it's convenience for people to have more levels in docs.
> 
> But I guess, move archs into a Documentation/arch/ dir should be fine. like Documentation/arch/{x86,arm,arm64,ia64,m68k,s390,powerpc,...}

Alex, moving kdump to admin-guide sounds reasonable to me.  I also agree
with you for those arch dependent files can be moved to
Documentation/arch/, maybe you are talking about some other patches in
the series for the arch/? 

Thanks
dave

Re: [PATCH 18/39] docs: admin-guide: add kdump documentation into it

[Mauro Carvalho Chehab]

Em Fri, 5 Jul 2019 13:59:04 +0800
Dave Young <dyoung@redhat.com> escreveu:

> On 07/05/19 at 11:43am, Alex Shi wrote:
> > 
> > 
> > 在 2019/6/28 下午8:30, Mauro Carvalho Chehab 写道:  
> > > The Kdump documentation describes procedures with admins use
> > > in order to solve issues on their systems.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > > ---
> > >  Documentation/admin-guide/bug-hunting.rst            | 4 ++--
> > >  Documentation/admin-guide/index.rst                  | 1 +
> > >  Documentation/{ => admin-guide}/kdump/gdbmacros.txt  | 0
> > >  Documentation/{ => admin-guide}/kdump/index.rst      | 1 -
> > >  Documentation/{ => admin-guide}/kdump/kdump.rst      | 0
> > >  Documentation/{ => admin-guide}/kdump/vmcoreinfo.rst | 0  
> > 
> > I am not sure if it's convenience for people to have more levels in docs.
> > 
> > But I guess, move archs into a Documentation/arch/ dir should be fine. like Documentation/arch/{x86,arm,arm64,ia64,m68k,s390,powerpc,...}  
> 
> Alex, moving kdump to admin-guide sounds reasonable to me.  I also agree
> with you for those arch dependent files can be moved to
> Documentation/arch/, maybe you are talking about some other patches in
> the series for the arch/? 

Alex,

It makes sense for me to have a Documentation/arch directory, and place
the arch-specific docs over there.

There's actually a technical advantage on doing that: Sphinx is dumb
with regards to PDF/LaTeX output: it requires all top documents to be
listed at Documentation/conf.py, under this var:

	latex_documents = [
		...
	]

As it creates one runtime Makefile at Documentation/output per listed
document there. So, the more we group such documents, the less merge
conflicts we'll have at Documentation/conf.py.

Btw, there's a [TECH TOPIC] proposal for KS/2019 meant to discuss 
Documentation.

I suspect we could discuss the pros/cons of doing such change there.

My personal view is that we should keep the Documentation/ root dir as
clean as possible as a long term goal.

On the other hand, it makes the path bigger and harder to rename.

On a side note, last time we discussed documentation at KS I remember
I proposed to shortcut "Documentation/" to just "docs/". The consensus
on that time were to keep the big name. I still think that a shorter
one could help people to remind where documentation will be located.

Thanks,
Mauro