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