]>
Commit | Line | Data |
---|---|---|
57afc6df MK |
1 | .\" Copyright (C) 2010 Intel Corporation, Author: Andi Kleen |
2 | .\" and Copyright 2014, Vivek Goyal <vgoyal@redhat.com> | |
e4f282ab | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
e4f282ab MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
4784c377 | 25 | .\" |
8980a500 | 26 | .TH KEXEC_LOAD 2 2014-08-19 "Linux" "Linux Programmer's Manual" |
0bd8e0bf | 27 | .SH NAME |
7ca02469 | 28 | kexec_load, kexec_file_load \- load a new kernel for later execution |
0bd8e0bf | 29 | .SH SYNOPSIS |
046cebb3 | 30 | .nf |
ce06aee2 | 31 | .B #include <linux/kexec.h> |
7ca02469 | 32 | |
0bd8e0bf | 33 | .BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments "," |
ece948b4 MK |
34 | .BI " struct kexec_segment *" segments \ |
35 | ", unsigned long " flags ");" | |
7ca02469 | 36 | |
2139e7cf | 37 | .BI "long kexec_file_load(int " kernel_fd ", int " initrd_fd "," |
7ca02469 VG |
38 | .br |
39 | .BI " unsigned long " cmdline_len \ | |
40 | ", const char *" cmdline "," | |
7ca02469 | 41 | .BI " unsigned long " flags ");" |
45c99e3e | 42 | |
046cebb3 | 43 | .fi |
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. |
bea08fec | 60 | .\" FIXME Explain in more detail how KEXEC_ON_CRASH is actually used |
ece948b4 | 61 | .TP |
50cebc04 | 62 | .BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)" |
ece948b4 MK |
63 | Preserve the system hardware and |
64 | software states before executing the new kernel. | |
65 | This could be used for system suspend. | |
33a0ccb2 | 66 | This flag is available only if the kernel was configured with |
ece948b4 | 67 | .BR CONFIG_KEXEC_JUMP , |
33a0ccb2 | 68 | and is effective only if |
ece948b4 MK |
69 | .I nr_segments |
70 | is greater than 0. | |
71 | .PP | |
7d14eaf1 | 72 | The high-order bits (corresponding to the mask 0xffff0000) of |
0bd8e0bf | 73 | .I flags |
ece948b4 MK |
74 | contain the architecture of the to-be-executed kernel. |
75 | Specify (OR) the constant | |
76 | .B KEXEC_ARCH_DEFAULT | |
77 | to use the current architecture, | |
78 | or one of the following architecture constants | |
79 | .BR KEXEC_ARCH_386 , | |
b81463d6 | 80 | .BR KEXEC_ARCH_68K , |
ece948b4 MK |
81 | .BR KEXEC_ARCH_X86_64 , |
82 | .BR KEXEC_ARCH_PPC , | |
83 | .BR KEXEC_ARCH_PPC64 , | |
84 | .BR KEXEC_ARCH_IA_64 , | |
85 | .BR KEXEC_ARCH_ARM , | |
86 | .BR KEXEC_ARCH_S390 , | |
87 | .BR KEXEC_ARCH_SH , | |
88 | .BR KEXEC_ARCH_MIPS , | |
89 | and | |
90 | .BR KEXEC_ARCH_MIPS_LE . | |
0bd8e0bf AK |
91 | The architecture must be executable on the CPU of the system. |
92 | ||
ece948b4 MK |
93 | The |
94 | .I entry | |
02a4b9e9 | 95 | argument is the physical entry address in the kernel image. |
ece948b4 | 96 | The |
0bd8e0bf | 97 | .I nr_segments |
ece948b4 | 98 | argument is the number of segments pointed to by the |
0bd8e0bf | 99 | .I segments |
0fe0cc46 MK |
100 | pointer; |
101 | the kernel imposes an (arbitrary) limit of 16 on the number of segments. | |
ece948b4 MK |
102 | The |
103 | .I segments | |
104 | argument is an array of | |
105 | .I kexec_segment | |
0bd8e0bf AK |
106 | structures which define the kernel layout: |
107 | .in +4n | |
108 | .nf | |
109 | ||
110 | struct kexec_segment { | |
ece948b4 MK |
111 | void *buf; /* Buffer in user space */ |
112 | size_t bufsz; /* Buffer length in user space */ | |
02a4b9e9 MK |
113 | void *mem; /* Physical address of kernel */ |
114 | size_t memsz; /* Physical address length */ | |
0bd8e0bf AK |
115 | }; |
116 | .fi | |
117 | .in | |
118 | .PP | |
bea08fec MK |
119 | .\" FIXME Explain the details of how the kernel image defined by segments |
120 | .\" is copied from the calling process into previously reserved memory. | |
0bd8e0bf AK |
121 | The kernel image defined by |
122 | .I segments | |
123 | is copied from the calling process into previously reserved memory. | |
7ca02469 VG |
124 | .SS kexec_file_load() |
125 | The | |
126 | .BR kexec_file_load () | |
127 | system call is similar to | |
89a2edf1 MK |
128 | .BR kexec_load (), |
129 | but it takes a different set of arguments. | |
130 | It reads the kernel to be loaded from the file referred to by the descriptor | |
131 | .IR kernel_fd , | |
e19cb546 MK |
132 | and the initrd (initial RAM disk) |
133 | to be loaded from file referred to by the descriptor | |
7ca02469 | 134 | .IR initrd_fd . |
2f145838 MK |
135 | The |
136 | .IR cmdline | |
137 | argument is a pointer to a string containing the command line | |
138 | for the new kernel; the | |
7ca02469 | 139 | .IR cmdline_len |
2f145838 | 140 | argument specifies the length of the string in |
7ca02469 VG |
141 | .IR cmdline . |
142 | ||
143 | The | |
144 | .IR flags | |
89a2edf1 MK |
145 | argument is a bit mask which modifies the behavior of the call. |
146 | The following values can be specified in | |
147 | .IR flags : | |
7ca02469 VG |
148 | .TP |
149 | .BR KEXEC_FILE_UNLOAD | |
89a2edf1 | 150 | Unload the currently loaded kernel. |
7ca02469 VG |
151 | .TP |
152 | .BR KEXEC_FILE_ON_CRASH | |
89a2edf1 MK |
153 | Load the new kernel in the memory region reserved for the crash kernel. |
154 | This kernel is booted if the currently running kernel crashes. | |
7ca02469 VG |
155 | .TP |
156 | .BR KEXEC_FILE_NO_INITRAMFS | |
89a2edf1 MK |
157 | Loading initrd/initramfs is optional. |
158 | Specify this flag if no initramfs is being loaded. | |
159 | If this flag is set, the value passed in | |
7ca02469 | 160 | .IR initrd_fd |
89a2edf1 | 161 | is ignored. |
ece948b4 | 162 | .SH RETURN VALUE |
89a2edf1 MK |
163 | On success, these system calls returns 0. |
164 | On error, \-1 is returned and | |
ece948b4 MK |
165 | .I errno |
166 | is set to indicate the error. | |
167 | .SH ERRORS | |
168 | .TP | |
169 | .B EBUSY | |
170 | Another crash kernel is already being loaded | |
171 | or a crash kernel is already in use. | |
172 | .TP | |
173 | .B EINVAL | |
174 | .I flags | |
531bc088 DB |
175 | is invalid; or |
176 | .IR nr_segments | |
177 | is too large | |
ece948b4 MK |
178 | .\" KEXEC_SEGMENT_MAX == 16 |
179 | .TP | |
89a2edf1 MK |
180 | .B ENOEXEC |
181 | .I kernel_fd | |
182 | does not refer to an open file, or the kernel can't load this file. | |
183 | .TP | |
ece948b4 MK |
184 | .B EPERM |
185 | The caller does not have the | |
186 | .BR CAP_SYS_BOOT | |
187 | capability. | |
2a09a261 MK |
188 | .SH VERSIONS |
189 | The | |
190 | .BR kexec_load () | |
53bdbeec | 191 | system call first appeared in Linux 2.6.13. |
798711f7 MK |
192 | The |
193 | .BR kexec_file_load () | |
194 | system call first appeared in Linux 3.17. | |
d1e833fe | 195 | .SH CONFORMING TO |
75cd2564 | 196 | These system calls are Linux-specific. |
0bd8e0bf | 197 | .SH NOTES |
89a2edf1 MK |
198 | Currently, there is no glibc support for these system calls. |
199 | Call them using | |
ece948b4 | 200 | .BR syscall (2). |
0bd8e0bf | 201 | .PP |
66a9882e | 202 | The required constants are in the Linux kernel source file |
ece948b4 MK |
203 | .IR linux/kexec.h , |
204 | which is not currently exported to glibc. | |
ece948b4 | 205 | Therefore, these constants must be defined manually. |
577dd8b1 | 206 | |
6fd7d530 MK |
207 | The |
208 | .BR kexec_file_load () | |
209 | .\" See also http://lwn.net/Articles/603116/ | |
210 | system call was added to provide support for systems | |
211 | where "kexec" loading should be restricted to | |
212 | only kernels that are signed. | |
213 | ||
a2c8cd37 MK |
214 | The |
215 | .BR kexec_load () | |
216 | system call is available only if the kernel was configured with | |
577dd8b1 | 217 | .BR CONFIG_KEXEC . |
a2c8cd37 MK |
218 | The |
219 | .BR kexec_file_load () | |
220 | system call is available only if the kernel was configured with | |
221 | .BR CONFIG_KEXEC_FILE . | |
0bd8e0bf | 222 | .SH SEE ALSO |
3e5c319e | 223 | .BR reboot (2), |
b1340c30 MK |
224 | .BR syscall (2), |
225 | .BR kexec (8) | |
c328e5b3 MK |
226 | |
227 | The kernel source file | |
228 | .IR Documentation/kdump/kdump.txt . |