kexec_load.2: Additions and edits by mtk

Various wording and layout improvements.
Fixed the name of a constant: s/KEXEC_ARCH_I386/KEXEC_ARCH_386/.
Added RETURN VALUE and ERRORS sections.
Removed details of using syscall; the reader can find them in
syscall(2).
Added some details for KEXEC_PRESERVE_CONTEXT.
Revised the text mentioning the kernel header, since it is
not yet exported, and it's not certain that it will be.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/kexec_load.2

@@ -21,97 +21,126 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
-.TH KEXEC_LOAD 2 2010-06-16 "Linux" "Linux Programmer's Manual"
+.TH KEXEC_LOAD 2 2010-10-31 "Linux" "Linux Programmer's Manual"
 .SH NAME
-kexec_load \- Load a new kernel for later execution.
+kexec_load \- load a new kernel for later execution
 .SH SYNOPSIS
 .b #include <linux/kexec.h>
 .br
 .BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments ","
 .br
-.BI       "struct kexec_segment *" segments ", unsigned long " flags ");"
+.BI "                struct kexec_segment *" segments \
+", unsigned long " flags ");"
 .SH DESCRIPTION
-.BR kexec_load 
+The
-loads a new kernel that can be executed later
+.BR kexec_load ()
-by 
+system call loads a new kernel that can be executed later by
-.I reboot(2).
+.BR reboot(2) .
-An alternative approach is to specify
+.PP
+The
+.I flags
+argument is a mask whose high-order bits control the operation of the call.
+The following values can be specified in
+.IR flags :
+.TP
 .B KEXEC_ON_CRASH
-in the 
+Execute the new kernel automatically on a system crash.
+.\" FIXME figure out how this is really used
+.TP
+.B KEXEC_PRESERVE_CONTEXT
+Preserve the system hardware and
+software states before executing the new kernel.
+This could be used for system suspend.
+This flag is only available if the kernel was configured with
+.BR CONFIG_KEXEC_JUMP ,
+and is only effective if
+.I nr_segments
+is greater than 0.
+.PP
+The low-order bits of
 .I flags
-argument and then the new kernel will be automatically executed on a 
+contain the architecture of the to-be-executed kernel.
-system crash. 
+Specify (OR) the constant
-.\" XXX figure out how this is really used 
+.B KEXEC_ARCH_DEFAULT
-With 
+to use the current architecture,
-.B KEXEC_PRESERVE_CONTEXT 
+or one of the following architecture constants
-specified in 
+.BR KEXEC_ARCH_386 ,
-.I flags
+.BR KEXEC_ARCH_X86_64 ,
-kexec will preserve the system hard and 
+.BR KEXEC_ARCH_PPC ,
-software state before executing the kexec kernel. This 
+.BR KEXEC_ARCH_PPC64 ,
-could be used for system suspend.
+.BR KEXEC_ARCH_IA_64 ,
-
+.BR KEXEC_ARCH_ARM ,
-.I flags
+.BR KEXEC_ARCH_S390 ,
-also contains the architecture of the executed kernel or
+.BR KEXEC_ARCH_SH ,
-be 
+.BR KEXEC_ARCH_MIPS ,
-.I KEXEC_ARCH_DEFAULT
+and
-for the current architecture.
+.BR KEXEC_ARCH_MIPS_LE .
-Valid architectures are 
-.I KEXEC_ARCH_I386,
-.I KEXEC_ARCH_X86_64,
-.I KEXEC_ARCH_PPC,
-.I KEXEC_ARCH_PPC64,
-.I KEXEC_ARCH_IA_64,
-.I KEXEC_ARCH_ARM,
-.I KEXEC_ARCH_S390,
-.I KEXEC_ARCH_SH,
-.I KEXEC_ARCH_MIPS,
-.I KEXEC_ARCH_MIPS_LE.
 The architecture must be executable on the CPU of the system.
 
-.I entry 
+The
-is the virtual entry address in the kernel image.
+.I entry
+argument is the virtual entry address in the kernel image.
+The
 .I nr_segments
-is the number of segments pointed to by the 
+argument is the number of segments pointed to by the
 .I segments
-pointer. 
+pointer.
-.I segments 
+The
-is an array of 
+.I segments
-.I struct kexec_segment
+argument is an array of
+.I kexec_segment
 structures which define the kernel layout:
 .in +4n
 .nf
 
 struct kexec_segment {
-	void   *buf;	/* Buffer in user space */
+    void   *buf;        /* Buffer in user space */
-	size_t  bufsz;	/* Buffer length in user space */
+    size_t  bufsz;      /* Buffer length in user space */
-	void   *mem;	/* Virtual address of kernel */
+    void   *mem;        /* Virtual address of kernel */
-	size_t  memsz;	/* Virtual address length */
+    size_t  memsz;      /* Virtual address length */
 };
 .fi
 .in
 .PP
-.\" XXX elaborate on this
+.\" FIXME elaborate on the following:
 The kernel image defined by
 .I segments
 is copied from the calling process into previously reserved memory.
-.SH CONFORMING TO
+.SH RETURN VALUE
-This system call is Linux-specific.
+On success,
+.BR kexec_load ()
+returns 0.
+On error, -1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EBUSY
+Another crash kernel is already being loaded
+or a crash kernel is already in use.
+.TP
+.B EINVAL
+.I flags
+is invalid; of
+.IR nr_segments is too large
+.\" KEXEC_SEGMENT_MAX == 16
+.TP
+.B EPERM
+The caller does not have the
+.BR CAP_SYS_BOOT
+capability.
 .SH NOTES
-kexec_load is currently not defined in glibc. To call it use:
+Currently, there is no glibc support for
-.in +4n
+.BR kexec_load ().
-.nf
+Call it using
-#define _GNU_SOURCE
+.BR syscall (2).
-#include <syscall.h>
-#include <asm/unistd.h>
-#include <linux/kexec.h>
-
-ret = syscall(__NR_kexec_load, entry, nr_segments, segments, flags);
-.fi
-.in
 .PP
-.I linux/kexec.h as a exported header is only available in 2.6.38
+The required constants are in the kernel source file
-and later kernels, in earlier kernels the constants need to be copied
+.IR linux/kexec.h ,
-out of the kernel source.
+which is not currently exported to glibc.
+.\" FIXME Andi submitted a patch for this.
+.\" Check if it got accepted later.
+Therefore, these constants must be defined manually.
 .SH SEE ALSO
 .BR syscall (2),
 .BR reboot (2)