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