man2/kexec_load.2

   1 .\" Copyright (C) 2010 Intel Corporation, Author: Andi Kleen
   2 .\" and Copyright 2014, Vivek Goyal <vgoyal@redhat.com>
   3 .\" and Copyright (c) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH KEXEC_LOAD 2 2021-03-22 "Linux" "Linux Programmer's Manual"
   8 .SH NAME
   9 kexec_load, kexec_file_load \- load a new kernel for later execution
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .BR "#include <linux/kexec.h>" "      /* Definition of " KEXEC_* " constants */"
  16 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  17 .B #include <unistd.h>
  18 .PP
  19 .BI "long syscall(SYS_kexec_load, unsigned long " entry ,
  20 .BI "             unsigned long " nr_segments \
  21 ", struct kexec_segment *" segments ,
  22 .BI "             unsigned long " flags );
  23 .BI "long syscall(SYS_kexec_file_load, int " kernel_fd ", int " initrd_fd ,
  24 .BI "             unsigned long " cmdline_len ", const char *" cmdline ,
  25 .BI "             unsigned long " flags );
  26 .fi
  27 .PP
  28 .IR Note :
  29 glibc provides no wrappers for these system calls,
  30 necessitating the use of
  31 .BR syscall (2).
  32 .SH DESCRIPTION
  33 The
  34 .BR kexec_load ()
  35 system call loads a new kernel that can be executed later by
  36 .BR reboot (2).
  37 .PP
  38 The
  39 .I flags
  40 argument is a bit mask that controls the operation of the call.
  41 The following values can be specified in
  42 .IR flags :
  43 .TP
  44 .BR KEXEC_ON_CRASH " (since Linux 2.6.13)"
  45 Execute the new kernel automatically on a system crash.
  46 This "crash kernel" is loaded into an area of reserved memory that
  47 is determined at boot time using the
  48 .I crashkernel
  49 kernel command-line parameter.
  50 The location of this reserved memory is exported to user space via the
  51 .I /proc/iomem
  52 file, in an entry labeled "Crash kernel".
  53 A user-space application can parse this file and prepare a list of
  54 segments (see below) that specify this reserved memory as destination.
  55 If this flag is specified, the kernel checks that the
  56 target segments specified in
  57 .I segments
  58 fall within the reserved region.
  59 .TP
  60 .BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)"
  61 Preserve the system hardware and
  62 software states before executing the new kernel.
  63 This could be used for system suspend.
  64 This flag is available only if the kernel was configured with
  65 .BR CONFIG_KEXEC_JUMP ,
  66 and is effective only if
  67 .I nr_segments
  68 is greater than 0.
  69 .PP
  70 The high-order bits (corresponding to the mask 0xffff0000) of
  71 .I flags
  72 contain the architecture of the to-be-executed kernel.
  73 Specify (OR) the constant
  74 .B KEXEC_ARCH_DEFAULT
  75 to use the current architecture,
  76 or one of the following architecture constants
  77 .BR KEXEC_ARCH_386 ,
  78 .BR KEXEC_ARCH_68K ,
  79 .BR KEXEC_ARCH_X86_64 ,
  80 .BR KEXEC_ARCH_PPC ,
  81 .BR KEXEC_ARCH_PPC64 ,
  82 .BR KEXEC_ARCH_IA_64 ,
  83 .BR KEXEC_ARCH_ARM ,
  84 .BR KEXEC_ARCH_S390 ,
  85 .BR KEXEC_ARCH_SH ,
  86 .BR KEXEC_ARCH_MIPS ,
  87 and
  88 .BR KEXEC_ARCH_MIPS_LE .
  89 The architecture must be executable on the CPU of the system.
  90 .PP
  91 The
  92 .I entry
  93 argument is the physical entry address in the kernel image.
  94 The
  95 .I nr_segments
  96 argument is the number of segments pointed to by the
  97 .I segments
  98 pointer;
  99 the kernel imposes an (arbitrary) limit of 16 on the number of segments.
 100 The
 101 .I segments
 102 argument is an array of
 103 .I kexec_segment
 104 structures which define the kernel layout:
 105 .PP
 106 .in +4n
 107 .EX
 108 struct kexec_segment {
 109     void   *buf;        /* Buffer in user space */
 110     size_t  bufsz;      /* Buffer length in user space */
 111     void   *mem;        /* Physical address of kernel */
 112     size_t  memsz;      /* Physical address length */
 113 };
 114 .EE
 115 .in
 116 .PP
 117 The kernel image defined by
 118 .I segments
 119 is copied from the calling process into
 120 the kernel either in regular
 121 memory or in reserved memory (if
 122 .B KEXEC_ON_CRASH
 123 is set).
 124 The kernel first performs various sanity checks on the
 125 information passed in
 126 .IR segments .
 127 If these checks pass, the kernel copies the segment data to kernel memory.
 128 Each segment specified in
 129 .I segments
 130 is copied as follows:
 131 .IP * 3
 132 .I buf
 133 and
 134 .I bufsz
 135 identify a memory region in the caller's virtual address space
 136 that is the source of the copy.
 137 The value in
 138 .I bufsz
 139 may not exceed the value in the
 140 .I memsz
 141 field.
 142 .IP *
 143 .I mem
 144 and
 145 .I memsz
 146 specify a physical address range that is the target of the copy.
 147 The values specified in both fields must be multiples of
 148 the system page size.
 149 .IP *
 150 .I bufsz
 151 bytes are copied from the source buffer to the target kernel buffer.
 152 If
 153 .I bufsz
 154 is less than
 155 .IR memsz ,
 156 then the excess bytes in the kernel buffer are zeroed out.
 157 .PP
 158 In case of a normal kexec (i.e., the
 159 .B KEXEC_ON_CRASH
 160 flag is not set), the segment data is loaded in any available memory
 161 and is moved to the final destination at kexec reboot time (e.g., when the
 162 .BR kexec (8)
 163 command is executed with the
 164 .I \-e
 165 option).
 166 .PP
 167 In case of kexec on panic (i.e., the
 168 .B KEXEC_ON_CRASH
 169 flag is set), the segment data is
 170 loaded to reserved memory at the time of the call, and, after a crash,
 171 the kexec mechanism simply passes control to that kernel.
 172 .PP
 173 The
 174 .BR kexec_load ()
 175 system call is available only if the kernel was configured with
 176 .BR CONFIG_KEXEC .
 177 .SS kexec_file_load()
 178 The
 179 .BR kexec_file_load ()
 180 system call is similar to
 181 .BR kexec_load (),
 182 but it takes a different set of arguments.
 183 It reads the kernel to be loaded from the file referred to by
 184 the file descriptor
 185 .IR kernel_fd ,
 186 and the initrd (initial RAM disk)
 187 to be loaded from file referred to by the file descriptor
 188 .IR initrd_fd .
 189 The
 190 .I cmdline
 191 argument is a pointer to a buffer containing the command line
 192 for the new kernel.
 193 The
 194 .I cmdline_len
 195 argument specifies size of the buffer.
 196 The last byte in the buffer must be a null byte (\(aq\e0\(aq).
 197 .PP
 198 The
 199 .I flags
 200 argument is a bit mask which modifies the behavior of the call.
 201 The following values can be specified in
 202 .IR flags :
 203 .TP
 204 .B KEXEC_FILE_UNLOAD
 205 Unload the currently loaded kernel.
 206 .TP
 207 .B KEXEC_FILE_ON_CRASH
 208 Load the new kernel in the memory region reserved for the crash kernel
 209 (as for
 210 .BR KEXEC_ON_CRASH ).
 211 This kernel is booted if the currently running kernel crashes.
 212 .TP
 213 .B KEXEC_FILE_NO_INITRAMFS
 214 Loading initrd/initramfs is optional.
 215 Specify this flag if no initramfs is being loaded.
 216 If this flag is set, the value passed in
 217 .I initrd_fd
 218 is ignored.
 219 .PP
 220 The
 221 .BR kexec_file_load ()
 222 .\" See also http://lwn.net/Articles/603116/
 223 system call was added to provide support for systems
 224 where "kexec" loading should be restricted to
 225 only kernels that are signed.
 226 This system call is available only if the kernel was configured with
 227 .BR CONFIG_KEXEC_FILE .
 228 .SH RETURN VALUE
 229 On success, these system calls returns 0.
 230 On error, \-1 is returned and
 231 .I errno
 232 is set to indicate the error.
 233 .SH ERRORS
 234 .TP
 235 .B EADDRNOTAVAIL
 236 .\" See kernel/kexec.::sanity_check_segment_list in the 3.19 kernel source
 237 The
 238 .B KEXEC_ON_CRASH
 239 flags was specified, but the region specified by the
 240 .I mem
 241 and
 242 .I memsz
 243 fields of one of the
 244 .I segments
 245 entries lies outside the range of memory reserved for the crash kernel.
 246 .TP
 247 .B EADDRNOTAVAIL
 248 The value in a
 249 .I mem
 250 or
 251 .I memsz
 252 field in one of the
 253 .I segments
 254 entries is not a multiple of the system page size.
 255 .TP
 256 .B EBADF
 257 .I kernel_fd
 258 or
 259 .I initrd_fd
 260 is not a valid file descriptor.
 261 .TP
 262 .B EBUSY
 263 Another crash kernel is already being loaded
 264 or a crash kernel is already in use.
 265 .TP
 266 .B EINVAL
 267 .I flags
 268 is invalid.
 269 .TP
 270 .B EINVAL
 271 The value of a
 272 .I bufsz
 273 field in one of the
 274 .I segments
 275 entries exceeds the value in the corresponding
 276 .I memsz
 277 field.
 278 .TP
 279 .B EINVAL
 280 .I nr_segments
 281 exceeds
 282 .B KEXEC_SEGMENT_MAX
 283 (16).
 284 .TP
 285 .B EINVAL
 286 Two or more of the kernel target buffers overlap.
 287 .TP
 288 .B EINVAL
 289 The value in
 290 .I cmdline[cmdline_len\-1]
 291 is not \(aq\e0\(aq.
 292 .TP
 293 .B EINVAL
 294 The file referred to by
 295 .I kernel_fd
 296 or
 297 .I initrd_fd
 298 is empty (length zero).
 299 .TP
 300 .B ENOEXEC
 301 .I kernel_fd
 302 does not refer to an open file, or the kernel can't load this file.
 303 Currently, the file must be a bzImage and contain an x86 kernel that
 304 is loadable above 4\ GiB in memory (see the kernel source file
 305 .IR Documentation/x86/boot.txt ).
 306 .TP
 307 .B ENOMEM
 308 Could not allocate memory.
 309 .TP
 310 .B EPERM
 311 The caller does not have the
 312 .B CAP_SYS_BOOT
 313 capability.
 314 .SH VERSIONS
 315 The
 316 .BR kexec_load ()
 317 system call first appeared in Linux 2.6.13.
 318 The
 319 .BR kexec_file_load ()
 320 system call first appeared in Linux 3.17.
 321 .SH STANDARDS
 322 These system calls are Linux-specific.
 323 .SH SEE ALSO
 324 .BR reboot (2),
 325 .BR syscall (2),
 326 .BR kexec (8)
 327 .PP
 328 The kernel source files
 329 .I Documentation/kdump/kdump.txt
 330 and
 331 .I Documentation/admin\-guide/kernel\-parameters.txt