Documentation: kdump: update kdump guide

+120 -72

1 changed file

expand all

Documentation

admin-guide

kdump

kdump.rst

+120 -72

Documentation/admin-guide/kdump/kdump.rst

··· 2 2 Documentation for Kdump - The kexec-based Crash Dumping Solution 3 3 ================================================================ 4 4 5 - This document includes overview, setup and installation, and analysis 5 + This document includes overview, setup, installation, and analysis 6 6 information. 7 7 8 8 Overview ··· 13 13 the system panics). The system kernel's memory image is preserved across 14 14 the reboot and is accessible to the dump-capture kernel. 15 15 16 - You can use common commands, such as cp and scp, to copy the 17 - memory image to a dump file on the local disk, or across the network to 18 - a remote system. 16 + You can use common commands, such as cp, scp or makedumpfile to copy 17 + the memory image to a dump file on the local disk, or across the network 18 + to a remote system. 19 19 20 20 Kdump and kexec are currently supported on the x86, x86_64, ppc64, ia64, 21 21 s390x, arm and arm64 architectures. ··· 26 26 The kexec -p command loads the dump-capture kernel into this reserved 27 27 memory. 28 28 29 - On x86 machines, the first 640 KB of physical memory is needed to boot, 30 - regardless of where the kernel loads. Therefore, kexec backs up this 31 - region just before rebooting into the dump-capture kernel. 29 + On x86 machines, the first 640 KB of physical memory is needed for boot, 30 + regardless of where the kernel loads. For simpler handling, the whole 31 + low 1M is reserved to avoid any later kernel or device driver writing 32 + data into this area. Like this, the low 1M can be reused as system RAM 33 + by kdump kernel without extra handling. 32 34 33 - Similarly on PPC64 machines first 32KB of physical memory is needed for 34 - booting regardless of where the kernel is loaded and to support 64K page 35 - size kexec backs up the first 64KB memory. 35 + On PPC64 machines first 32KB of physical memory is needed for booting 36 + regardless of where the kernel is loaded and to support 64K page size 37 + kexec backs up the first 64KB memory. 36 38 37 39 For s390x, when kdump is triggered, the crashkernel region is exchanged 38 40 with the region [0, crashkernel region size] and then the kdump kernel ··· 48 46 parameter. Optionally the size of the ELF header can also be passed 49 47 when using the elfcorehdr=[size[KMG]@]offset[KMG] syntax. 50 48 51 - 52 49 With the dump-capture kernel, you can access the memory image through 53 50 /proc/vmcore. This exports the dump as an ELF-format file that you can 54 - write out using file copy commands such as cp or scp. Further, you can 55 - use analysis tools such as the GNU Debugger (GDB) and the Crash tool to 56 - debug the dump file. This method ensures that the dump pages are correctly 57 - ordered. 58 - 51 + write out using file copy commands such as cp or scp. You can also use 52 + makedumpfile utility to analyze and write out filtered contents with 53 + options, e.g with '-d 31' it will only write out kernel data. Further, 54 + you can use analysis tools such as the GNU Debugger (GDB) and the Crash 55 + tool to debug the dump file. This method ensures that the dump pages are 56 + correctly ordered. 59 57 60 58 Setup and Installation 61 59 ====================== ··· 127 125 System kernel config options 128 126 ---------------------------- 129 127 130 - 1) Enable "kexec system call" in "Processor type and features.":: 128 + 1) Enable "kexec system call" or "kexec file based system call" in 129 + "Processor type and features.":: 131 130 132 - CONFIG_KEXEC=y 131 + CONFIG_KEXEC=y or CONFIG_KEXEC_FILE=y 132 + 133 + And both of them will select KEXEC_CORE:: 134 + 135 + CONFIG_KEXEC_CORE=y 136 + 137 + Subsequently, CRASH_CORE is selected by KEXEC_CORE:: 138 + 139 + CONFIG_CRASH_CORE=y 133 140 134 141 2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo 135 142 filesystems." This is usually enabled by default:: ··· 186 175 187 176 CONFIG_HIGHMEM4G 188 177 189 - 2) On i386 and x86_64, disable symmetric multi-processing support 190 - under "Processor type and features":: 178 + 2) With CONFIG_SMP=y, usually nr_cpus=1 need specified on the kernel 179 + command line when loading the dump-capture kernel because one 180 + CPU is enough for kdump kernel to dump vmcore on most of systems. 191 181 192 - CONFIG_SMP=n 182 + However, you can also specify nr_cpus=X to enable multiple processors 183 + in kdump kernel. In this case, "disable_cpu_apicid=" is needed to 184 + tell kdump kernel which cpu is 1st kernel's BSP. Please refer to 185 + admin-guide/kernel-parameters.txt for more details. 193 186 194 - (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line 195 - when loading the dump-capture kernel, see section "Load the Dump-capture 196 - Kernel".) 187 + With CONFIG_SMP=n, the above things are not related. 197 188 198 - 3) If one wants to build and use a relocatable kernel, 199 - Enable "Build a relocatable kernel" support under "Processor type and 189 + 3) A relocatable kernel is suggested to be built by default. If not yet, 190 + enable "Build a relocatable kernel" support under "Processor type and 200 191 features":: 201 192 202 193 CONFIG_RELOCATABLE=y ··· 245 232 as a dump-capture kernel if desired. 246 233 247 234 The crashkernel region can be automatically placed by the system 248 - kernel at run time. This is done by specifying the base address as 0, 235 + kernel at runtime. This is done by specifying the base address as 0, 249 236 or omitting it all together:: 250 237 251 238 crashkernel=256M@0 ··· 253 240 or:: 254 241 255 242 crashkernel=256M 256 - 257 - If the start address is specified, note that the start address of the 258 - kernel will be aligned to 64Mb, so if the start address is not then 259 - any space below the alignment point will be wasted. 260 243 261 244 Dump-capture kernel config options (Arch Dependent, arm) 262 245 ---------------------------------------------------------- ··· 269 260 on non-VHE systems even if it is configured. This is because the CPU 270 261 will not be reset to EL2 on panic. 271 262 272 - Extended crashkernel syntax 263 + crashkernel syntax 273 264 =========================== 265 + 1) crashkernel=size@offset 274 266 275 - While the "crashkernel=size[@offset]" syntax is sufficient for most 276 - configurations, sometimes it's handy to have the reserved memory dependent 277 - on the value of System RAM -- that's mostly for distributors that pre-setup 278 - the kernel command line to avoid a unbootable system after some memory has 279 - been removed from the machine. 280 - 281 - The syntax is:: 282 - 283 - crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset] 284 - range=start-[end] 285 - 286 - For example:: 287 - 288 - crashkernel=512M-2G:64M,2G-:128M 289 - 290 - This would mean: 291 - 292 - 1) if the RAM is smaller than 512M, then don't reserve anything 293 - (this is the "rescue" case) 294 - 2) if the RAM size is between 512M and 2G (exclusive), then reserve 64M 295 - 3) if the RAM size is larger than 2G, then reserve 128M 296 - 297 - 298 - 299 - Boot into System Kernel 300 - ======================= 301 - 302 - 1) Update the boot loader (such as grub, yaboot, or lilo) configuration 303 - files as necessary. 304 - 305 - 2) Boot the system kernel with the boot parameter "crashkernel=Y@X", 306 - where Y specifies how much memory to reserve for the dump-capture kernel 307 - and X specifies the beginning of this reserved memory. For example, 267 + Here 'size' specifies how much memory to reserve for the dump-capture kernel 268 + and 'offset' specifies the beginning of this reserved memory. For example, 308 269 "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory 309 270 starting at physical address 0x01000000 (16MB) for the dump-capture kernel. 310 271 311 - On x86 and x86_64, use "crashkernel=64M@16M". 272 + The crashkernel region can be automatically placed by the system 273 + kernel at run time. This is done by specifying the base address as 0, 274 + or omitting it all together:: 275 + 276 + crashkernel=256M@0 277 + 278 + or:: 279 + 280 + crashkernel=256M 281 + 282 + If the start address is specified, note that the start address of the 283 + kernel will be aligned to a value (which is Arch dependent), so if the 284 + start address is not then any space below the alignment point will be 285 + wasted. 286 + 287 + 2) range1:size1[,range2:size2,...][@offset] 288 + 289 + While the "crashkernel=size[@offset]" syntax is sufficient for most 290 + configurations, sometimes it's handy to have the reserved memory dependent 291 + on the value of System RAM -- that's mostly for distributors that pre-setup 292 + the kernel command line to avoid a unbootable system after some memory has 293 + been removed from the machine. 294 + 295 + The syntax is:: 296 + 297 + crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset] 298 + range=start-[end] 299 + 300 + For example:: 301 + 302 + crashkernel=512M-2G:64M,2G-:128M 303 + 304 + This would mean: 305 + 306 + 1) if the RAM is smaller than 512M, then don't reserve anything 307 + (this is the "rescue" case) 308 + 2) if the RAM size is between 512M and 2G (exclusive), then reserve 64M 309 + 3) if the RAM size is larger than 2G, then reserve 128M 310 + 311 + 3) crashkernel=size,high and crashkernel=size,low 312 + 313 + If memory above 4G is preferred, crashkernel=size,high can be used to 314 + fulfill that. With it, physical memory is allowed to be allocated from top, 315 + so could be above 4G if system has more than 4G RAM installed. Otherwise, 316 + memory region will be allocated below 4G if available. 317 + 318 + When crashkernel=X,high is passed, kernel could allocate physical memory 319 + region above 4G, low memory under 4G is needed in this case. There are 320 + three ways to get low memory: 321 + 322 + 1) Kernel will allocate at least 256M memory below 4G automatically 323 + if crashkernel=Y,low is not specified. 324 + 2) Let user specify low memory size instead. 325 + 3) Specified value 0 will disable low memory allocation:: 326 + 327 + crashkernel=0,low 328 + 329 + Boot into System Kernel 330 + ----------------------- 331 + 1) Update the boot loader (such as grub, yaboot, or lilo) configuration 332 + files as necessary. 333 + 334 + 2) Boot the system kernel with the boot parameter "crashkernel=Y@X". 335 + 336 + On x86 and x86_64, use "crashkernel=Y[@X]". Most of the time, the 337 + start address 'X' is not necessary, kernel will search a suitable 338 + area. Unless an explicit start address is expected. 312 339 313 340 On ppc64, use "crashkernel=128M@32M". 314 341 ··· 376 331 377 332 For i386 and x86_64: 378 333 379 - - Use vmlinux if kernel is not relocatable. 380 334 - Use bzImage/vmlinuz if kernel is relocatable. 335 + - Use vmlinux if kernel is not relocatable. 381 336 382 337 For ppc64: 383 338 ··· 437 392 438 393 For i386, x86_64 and ia64: 439 394 440 - "1 irqpoll maxcpus=1 reset_devices" 395 + "1 irqpoll nr_cpus=1 reset_devices" 441 396 442 397 For ppc64: 443 398 ··· 445 400 446 401 For s390x: 447 402 448 - "1 maxcpus=1 cgroup_disable=memory" 403 + "1 nr_cpus=1 cgroup_disable=memory" 449 404 450 405 For arm: 451 406 ··· 453 408 454 409 For arm64: 455 410 456 - "1 maxcpus=1 reset_devices" 411 + "1 nr_cpus=1 reset_devices" 457 412 458 413 Notes on loading the dump-capture kernel: 459 414 ··· 533 488 534 489 cp /proc/vmcore <dump-file> 535 490 491 + You can also use makedumpfile utility to write out the dump file 492 + with specified options to filter out unwanted contents, e.g:: 493 + 494 + makedumpfile -l --message-level 1 -d 31 /proc/vmcore <dump-file> 536 495 537 496 Analysis 538 497 ======== ··· 584 535 Contact 585 536 ======= 586 537 587 - - Vivek Goyal (vgoyal@redhat.com) 588 - - Maneesh Soni (maneesh@in.ibm.com) 538 + - kexec@lists.infradead.org 589 539 590 540 GDB macros 591 541 ==========

Configure Feed

Configure Feed