| blob | 74f14235581bc1dad909ce8dea5e692acfcc02f8 |
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