| .\" 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> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH KEXEC_LOAD 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| kexec_load, kexec_file_load \- load a new kernel for later execution |
| .SH SYNOPSIS |
| .nf |
| .B #include <linux/kexec.h> |
| .PP |
| .BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments , |
| .BI " struct kexec_segment *" segments , |
| .BI " unsigned long " flags ); |
| .BI "long kexec_file_load(int " kernel_fd ", int " initrd_fd , |
| .BI " unsigned long " cmdline_len ", const char *" cmdline , |
| .BI " unsigned long " flags ); |
| .fi |
| .PP |
| .IR Note : |
| There are no glibc wrappers for these system calls; see NOTES. |
| .SH DESCRIPTION |
| The |
| .BR kexec_load () |
| system call loads a new kernel that can be executed later by |
| .BR reboot (2). |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| 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: |
| .PP |
| .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 |
| .PP |
| 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 |
| .BR 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 * 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 * |
| .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 * |
| .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. |
| .PP |
| In case of a normal kexec (i.e., the |
| .BR 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). |
| .PP |
| In case of kexec on panic (i.e., the |
| .BR 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. |
| .PP |
| 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 |
| .IR cmdline |
| argument is a pointer to a buffer containing the command line |
| for the new kernel. |
| The |
| .IR cmdline_len |
| argument specifies size of the buffer. |
| The last byte in the buffer must be a null byte (\(aq\e0\(aq). |
| .PP |
| The |
| .IR flags |
| argument is a bit mask which modifies the behavior of the call. |
| The following values can be specified in |
| .IR flags : |
| .TP |
| .BR KEXEC_FILE_UNLOAD |
| Unload the currently loaded kernel. |
| .TP |
| .BR 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 |
| .BR 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 |
| .IR initrd_fd |
| is ignored. |
| .PP |
| 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 |
| .IR nr_segments |
| exceeds |
| .BR 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 |
| .BR CAP_SYS_BOOT |
| capability. |
| .SH VERSIONS |
| The |
| .BR kexec_load () |
| system call first appeared in Linux 2.6.13. |
| The |
| .BR kexec_file_load () |
| system call first appeared in Linux 3.17. |
| .SH CONFORMING TO |
| These system calls are Linux-specific. |
| .SH NOTES |
| Glibc does not provide a wrapper for these system calls; call them using |
| .BR syscall (2). |
| .SH SEE ALSO |
| .BR reboot (2), |
| .BR syscall (2), |
| .BR kexec (8) |
| .PP |
| The kernel source files |
| .IR Documentation/kdump/kdump.txt |
| and |
| .IR Documentation/admin\-guide/kernel\-parameters.txt |