diff options
Diffstat (limited to 'man/man2/kexec_load.2')
| -rw-r--r-- | man/man2/kexec_load.2 | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/man/man2/kexec_load.2 b/man/man2/kexec_load.2 new file mode 100644 index 000000000..58a894f30 --- /dev/null +++ b/man/man2/kexec_load.2 @@ -0,0 +1,331 @@ +.\" Copyright (C) 2010 Intel Corporation, Author: Andi Kleen +.\" and Copyright 2014, Vivek Goyal <vgoyal@redhat.com> +.\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH kexec_load 2 (date) "Linux man-pages (unreleased)" +.SH NAME +kexec_load, kexec_file_load \- load a new kernel for later execution +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/kexec.h>" " /* Definition of " KEXEC_* " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.P +.BI "long syscall(SYS_kexec_load, unsigned long " entry , +.BI " unsigned long " nr_segments \ +", struct kexec_segment *" segments , +.BI " unsigned long " flags ); +.BI "long syscall(SYS_kexec_file_load, int " kernel_fd ", int " initrd_fd , +.BI " unsigned long " cmdline_len ", const char *" cmdline , +.BI " unsigned long " flags ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR kexec_load () +system call loads a new kernel that can be executed later by +.BR reboot (2). +.P +The +.I flags +argument is a bit mask that controls the operation of the call. +The following values can be specified in +.IR flags : +.TP +.BR KEXEC_ON_CRASH " (since Linux 2.6.13)" +Execute the new kernel automatically on a system crash. +This "crash kernel" is loaded into an area of reserved memory that +is determined at boot time using the +.I crashkernel +kernel command-line parameter. +The location of this reserved memory is exported to user space via the +.I /proc/iomem +file, in an entry labeled "Crash kernel". +A user-space application can parse this file and prepare a list of +segments (see below) that specify this reserved memory as destination. +If this flag is specified, the kernel checks that the +target segments specified in +.I segments +fall within the reserved region. +.TP +.BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)" +Preserve the system hardware and +software states before executing the new kernel. +This could be used for system suspend. +This flag is available only if the kernel was configured with +.BR CONFIG_KEXEC_JUMP , +and is effective only if +.I nr_segments +is greater than 0. +.P +The high-order bits (corresponding to the mask 0xffff0000) of +.I flags +contain the architecture of the to-be-executed kernel. +Specify (OR) the constant +.B KEXEC_ARCH_DEFAULT +to use the current architecture, +or one of the following architecture constants +.BR KEXEC_ARCH_386 , +.BR KEXEC_ARCH_68K , +.BR KEXEC_ARCH_X86_64 , +.BR KEXEC_ARCH_PPC , +.BR KEXEC_ARCH_PPC64 , +.BR KEXEC_ARCH_IA_64 , +.BR KEXEC_ARCH_ARM , +.BR KEXEC_ARCH_S390 , +.BR KEXEC_ARCH_SH , +.BR KEXEC_ARCH_MIPS , +and +.BR KEXEC_ARCH_MIPS_LE . +The architecture must be executable on the CPU of the system. +.P +The +.I entry +argument is the physical entry address in the kernel image. +The +.I nr_segments +argument is the number of segments pointed to by the +.I segments +pointer; +the kernel imposes an (arbitrary) limit of 16 on the number of segments. +The +.I segments +argument is an array of +.I kexec_segment +structures which define the kernel layout: +.P +.in +4n +.EX +struct kexec_segment { + void *buf; /* Buffer in user space */ + size_t bufsz; /* Buffer length in user space */ + void *mem; /* Physical address of kernel */ + size_t memsz; /* Physical address length */ +}; +.EE +.in +.P +The kernel image defined by +.I segments +is copied from the calling process into +the kernel either in regular +memory or in reserved memory (if +.B KEXEC_ON_CRASH +is set). +The kernel first performs various sanity checks on the +information passed in +.IR segments . +If these checks pass, the kernel copies the segment data to kernel memory. +Each segment specified in +.I segments +is copied as follows: +.IP \[bu] 3 +.I buf +and +.I bufsz +identify a memory region in the caller's virtual address space +that is the source of the copy. +The value in +.I bufsz +may not exceed the value in the +.I memsz +field. +.IP \[bu] +.I mem +and +.I memsz +specify a physical address range that is the target of the copy. +The values specified in both fields must be multiples of +the system page size. +.IP \[bu] +.I bufsz +bytes are copied from the source buffer to the target kernel buffer. +If +.I bufsz +is less than +.IR memsz , +then the excess bytes in the kernel buffer are zeroed out. +.P +In case of a normal kexec (i.e., the +.B KEXEC_ON_CRASH +flag is not set), the segment data is loaded in any available memory +and is moved to the final destination at kexec reboot time (e.g., when the +.BR kexec (8) +command is executed with the +.I \-e +option). +.P +In case of kexec on panic (i.e., the +.B KEXEC_ON_CRASH +flag is set), the segment data is +loaded to reserved memory at the time of the call, and, after a crash, +the kexec mechanism simply passes control to that kernel. +.P +The +.BR kexec_load () +system call is available only if the kernel was configured with +.BR CONFIG_KEXEC . +.SS kexec_file_load() +The +.BR kexec_file_load () +system call is similar to +.BR kexec_load (), +but it takes a different set of arguments. +It reads the kernel to be loaded from the file referred to by +the file descriptor +.IR kernel_fd , +and the initrd (initial RAM disk) +to be loaded from file referred to by the file descriptor +.IR initrd_fd . +The +.I cmdline +argument is a pointer to a buffer containing the command line +for the new kernel. +The +.I cmdline_len +argument specifies size of the buffer. +The last byte in the buffer must be a null byte (\[aq]\e0\[aq]). +.P +The +.I flags +argument is a bit mask which modifies the behavior of the call. +The following values can be specified in +.IR flags : +.TP +.B KEXEC_FILE_UNLOAD +Unload the currently loaded kernel. +.TP +.B KEXEC_FILE_ON_CRASH +Load the new kernel in the memory region reserved for the crash kernel +(as for +.BR KEXEC_ON_CRASH ). +This kernel is booted if the currently running kernel crashes. +.TP +.B KEXEC_FILE_NO_INITRAMFS +Loading initrd/initramfs is optional. +Specify this flag if no initramfs is being loaded. +If this flag is set, the value passed in +.I initrd_fd +is ignored. +.P +The +.BR kexec_file_load () +.\" See also http://lwn.net/Articles/603116/ +system call was added to provide support for systems +where "kexec" loading should be restricted to +only kernels that are signed. +This system call is available only if the kernel was configured with +.BR CONFIG_KEXEC_FILE . +.SH RETURN VALUE +On success, these system calls returns 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EADDRNOTAVAIL +.\" See kernel/kexec.::sanity_check_segment_list in the 3.19 kernel source +The +.B KEXEC_ON_CRASH +flags was specified, but the region specified by the +.I mem +and +.I memsz +fields of one of the +.I segments +entries lies outside the range of memory reserved for the crash kernel. +.TP +.B EADDRNOTAVAIL +The value in a +.I mem +or +.I memsz +field in one of the +.I segments +entries is not a multiple of the system page size. +.TP +.B EBADF +.I kernel_fd +or +.I initrd_fd +is not a valid file descriptor. +.TP +.B EBUSY +Another crash kernel is already being loaded +or a crash kernel is already in use. +.TP +.B EINVAL +.I flags +is invalid. +.TP +.B EINVAL +The value of a +.I bufsz +field in one of the +.I segments +entries exceeds the value in the corresponding +.I memsz +field. +.TP +.B EINVAL +.I nr_segments +exceeds +.B KEXEC_SEGMENT_MAX +(16). +.TP +.B EINVAL +Two or more of the kernel target buffers overlap. +.TP +.B EINVAL +The value in +.I cmdline[cmdline_len\-1] +is not \[aq]\e0\[aq]. +.TP +.B EINVAL +The file referred to by +.I kernel_fd +or +.I initrd_fd +is empty (length zero). +.TP +.B ENOEXEC +.I kernel_fd +does not refer to an open file, or the kernel can't load this file. +Currently, the file must be a bzImage and contain an x86 kernel that +is loadable above 4\ GiB in memory (see the kernel source file +.IR Documentation/x86/boot.txt ). +.TP +.B ENOMEM +Could not allocate memory. +.TP +.B EPERM +The caller does not have the +.B CAP_SYS_BOOT +capability. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR kexec_load () +Linux 2.6.13. +.TP +.BR kexec_file_load () +Linux 3.17. +.SH SEE ALSO +.BR reboot (2), +.BR syscall (2), +.BR kexec (8) +.P +The kernel source files +.I Documentation/kdump/kdump.txt +and +.I Documentation/admin\-guide/kernel\-parameters.txt |