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