1KEXEC_LOAD(2)              Linux Programmer's Manual             KEXEC_LOAD(2)
2
3
4

NAME

6       kexec_load, kexec_file_load - load a new kernel for later execution
7

SYNOPSIS

9       #include <linux/kexec.h>
10
11       long kexec_load(unsigned long entry, unsigned long nr_segments,
12                       struct kexec_segment *segments, unsigned long flags);
13
14       long kexec_file_load(int kernel_fd, int initrd_fd,
15                           unsigned long cmdline_len, const char *cmdline,
16                           unsigned long flags);
17
18       Note: There are no glibc wrappers for these system calls; see NOTES.
19

DESCRIPTION

21       The  kexec_load()  system  call loads a new kernel that can be executed
22       later by reboot(2).
23
24       The flags argument is a bit mask that controls  the  operation  of  the
25       call.  The following values can be specified in flags:
26
27       KEXEC_ON_CRASH (since Linux 2.6.13)
28              Execute  the  new  kernel automatically on a system crash.  This
29              "crash kernel" is loaded into an area of reserved memory that is
30              determined  at  boot  time using the crashkernel kernel command-
31              line  parameter.   The  location  of  this  reserved  memory  is
32              exported  to  user  space  via the /proc/iomem file, in an entry
33              labeled "Crash kernel".  A user-space application can parse this
34              file  and  prepare  a  list of segments (see below) that specify
35              this reserved memory as destination.  If this flag is specified,
36              the kernel checks that the target segments specified in segments
37              fall within the reserved region.
38
39       KEXEC_PRESERVE_CONTEXT (since Linux 2.6.27)
40              Preserve the system hardware and software states before  execut‐
41              ing  the  new  kernel.   This  could be used for system suspend.
42              This flag is available only if the kernel  was  configured  with
43              CONFIG_KEXEC_JUMP,  and  is  effective  only  if  nr_segments is
44              greater than 0.
45
46       The high-order bits (corresponding to the  mask  0xffff0000)  of  flags
47       contain  the  architecture  of the to-be-executed kernel.  Specify (OR)
48       the constant KEXEC_ARCH_DEFAULT to use the current architecture, or one
49       of the following architecture constants KEXEC_ARCH_386, KEXEC_ARCH_68K,
50       KEXEC_ARCH_X86_64, KEXEC_ARCH_PPC, KEXEC_ARCH_PPC64,  KEXEC_ARCH_IA_64,
51       KEXEC_ARCH_ARM,  KEXEC_ARCH_S390,  KEXEC_ARCH_SH,  KEXEC_ARCH_MIPS, and
52       KEXEC_ARCH_MIPS_LE.  The architecture must be executable on the CPU  of
53       the system.
54
55       The  entry  argument is the physical entry address in the kernel image.
56       The nr_segments argument is the number of segments pointed  to  by  the
57       segments  pointer; the kernel imposes an (arbitrary) limit of 16 on the
58       number of segments.  The segments argument is an array of kexec_segment
59       structures which define the kernel layout:
60
61           struct kexec_segment {
62               void   *buf;        /* Buffer in user space */
63               size_t  bufsz;      /* Buffer length in user space */
64               void   *mem;        /* Physical address of kernel */
65               size_t  memsz;      /* Physical address length */
66           };
67
68       The kernel image defined by segments is copied from the calling process
69       into the kernel either in regular memory  or  in  reserved  memory  (if
70       KEXEC_ON_CRASH  is  set).   The  kernel  first  performs various sanity
71       checks on the information passed in segments.  If  these  checks  pass,
72       the  kernel  copies  the  segment  data to kernel memory.  Each segment
73       specified in segments is copied as follows:
74
75       *  buf and bufsz identify a  memory  region  in  the  caller's  virtual
76          address  space  that  is the source of the copy.  The value in bufsz
77          may not exceed the value in the memsz field.
78
79       *  mem and memsz specify a physical address range that is the target of
80          the  copy.  The values specified in both fields must be multiples of
81          the system page size.
82
83       *  bufsz bytes are copied from the source buffer to the  target  kernel
84          buffer.   If  bufsz is less than memsz, then the excess bytes in the
85          kernel buffer are zeroed out.
86
87       In case of a normal kexec (i.e., the KEXEC_ON_CRASH flag is  not  set),
88       the  segment data is loaded in any available memory and is moved to the
89       final destination at kexec reboot time (e.g., when the kexec(8) command
90       is executed with the -e option).
91
92       In  case  of kexec on panic (i.e., the KEXEC_ON_CRASH flag is set), the
93       segment data is loaded to reserved memory at the time of the call, and,
94       after  a  crash, the kexec mechanism simply passes control to that ker‐
95       nel.
96
97       The kexec_load() system call is available only if the kernel  was  con‐
98       figured with CONFIG_KEXEC.
99
100   kexec_file_load()
101       The  kexec_file_load()  system  call is similar to kexec_load(), but it
102       takes a different set of arguments.  It reads the kernel to  be  loaded
103       from  the  file  referred  to by the file descriptor kernel_fd, and the
104       initrd (initial RAM disk) to be loaded from file  referred  to  by  the
105       file descriptor initrd_fd.  The cmdline argument is a pointer to a buf‐
106       fer containing the command line for the new  kernel.   The  cmdline_len
107       argument  specifies  size  of  the buffer.  The last byte in the buffer
108       must be a null byte ('\0').
109
110       The flags argument is a bit mask which modifies  the  behavior  of  the
111       call.  The following values can be specified in flags:
112
113       KEXEC_FILE_UNLOAD
114              Unload the currently loaded kernel.
115
116       KEXEC_FILE_ON_CRASH
117              Load  the new kernel in the memory region reserved for the crash
118              kernel (as for KEXEC_ON_CRASH).  This kernel is  booted  if  the
119              currently running kernel crashes.
120
121       KEXEC_FILE_NO_INITRAMFS
122              Loading  initrd/initramfs  is optional.  Specify this flag if no
123              initramfs is being loaded.  If  this  flag  is  set,  the  value
124              passed in initrd_fd is ignored.
125
126       The kexec_file_load() system call was added to provide support for sys‐
127       tems where "kexec" loading should be restricted to  only  kernels  that
128       are  signed.  This system call is available only if the kernel was con‐
129       figured with CONFIG_KEXEC_FILE.
130

RETURN VALUE

132       On success, these system calls returns 0.  On error, -1 is returned and
133       errno is set to indicate the error.
134

ERRORS

136       EADDRNOTAVAIL
137              The KEXEC_ON_CRASH flags was specified, but the region specified
138              by the mem and memsz fields of one of the segments entries  lies
139              outside the range of memory reserved for the crash kernel.
140
141       EADDRNOTAVAIL
142              The value in a mem or memsz field in one of the segments entries
143              is not a multiple of the system page size.
144
145       EBADF  kernel_fd or initrd_fd is not a valid file descriptor.
146
147       EBUSY  Another crash kernel is already being loaded or a  crash  kernel
148              is already in use.
149
150       EINVAL flags is invalid.
151
152       EINVAL The  value  of  a  bufsz  field  in  one of the segments entries
153              exceeds the value in the corresponding memsz field.
154
155       EINVAL nr_segments exceeds KEXEC_SEGMENT_MAX (16).
156
157       EINVAL Two or more of the kernel target buffers overlap.
158
159       EINVAL The value in cmdline[cmdline_len-1] is not '\0'.
160
161       EINVAL The file referred to by kernel_fd or initrd_fd is empty  (length
162              zero).
163
164       ENOEXEC
165              kernel_fd  does  not  refer to an open file, or the kernel can't
166              load this file.  Currently, the file must be a bzImage and  con‐
167              tain  an  x86 kernel that is loadable above 4 GiB in memory (see
168              the kernel source file Documentation/x86/boot.txt).
169
170       ENOMEM Could not allocate memory.
171
172       EPERM  The caller does not have the CAP_SYS_BOOT capability.
173

VERSIONS

175       The kexec_load() system call  first  appeared  in  Linux  2.6.13.   The
176       kexec_file_load() system call first appeared in Linux 3.17.
177

CONFORMING TO

179       These system calls are Linux-specific.
180

NOTES

182       Currently, there is no glibc support for these system calls.  Call them
183       using syscall(2).
184

SEE ALSO

186       reboot(2), syscall(2), kexec(8)
187
188       The kernel source files  Documentation/kdump/kdump.txt  and  Documenta‐
189       tion/admin-guide/kernel-parameters.txt
190

COLOPHON

192       This  page  is  part of release 4.15 of the Linux man-pages project.  A
193       description of the project, information about reporting bugs,  and  the
194       latest     version     of     this    page,    can    be    found    at
195       https://www.kernel.org/doc/man-pages/.
196
197
198
199Linux                             2017-09-15                     KEXEC_LOAD(2)
Impressum