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