[PATCH] kexec_load manpage

Sun Oct 24 10:56:24 EDT 2010

Hey Andi,

I'd like to push this page out the door, but I'm blocked doing so
until I hear back from you regarding the question below (plus a new
version of the page, if needed please).

Thanks,

Michael

On Sat, Sep 11, 2010 at 6:46 AM, Michael Kerrisk <mtk.manpages at gmail.com> wrote:
> Hi Andi,
>
> Ping!
>
> Cheers,
>
> Michael
>
>
> On Sat, Jun 26, 2010 at 3:23 PM, Michael Kerrisk <mtk.manpages at gmail.com> wrote:
>> Hi Andi,
>>
>> Are Eric's suggestions of "physical" below correct? If so, could you
>> amend the page and resubmit?
>>
>> Also, I'd prefer to have the reboot.2 and kexec_load.2 page as
>> separate patches, so could you split them on the resend please?
>>
>> Thanks,
>>
>> Michael
>>
>> On Sat, Jun 19, 2010 at 9:18 PM, Eric W. Biederman
>> <ebiederm at xmission.com> wrote:
>>> Andi Kleen <andi at firstfloor.org> writes:
>>>
>>>> Here are the beginnings of a kexec_load manpage.
>>>>
>>>> Probably needs some more review from Eric and may need some additional
>>>> information.
>>>>
>>>> The syscall is actually only usable with a kernel patch to export
>>>> the header I just sent separately.
>>>
>>> The syscall has been used for years with a separate non-kernel header.
>>>
>>>
>>> Eric
>>>
>>>
>>>> Also added the kexec subcall to reboot(2)
>>>>
>>>> -Andi
>>>>
>>>> diff --git a/man2/kexec_load.2 b/man2/kexec_load.2
>>>> new file mode 100644
>>>> index 0000000..f486641
>>>> --- /dev/null
>>>> +++ b/man2/kexec_load.2
>>>> @@ -0,0 +1,94 @@
>>>> +.TH KEXEC_LOAD 2 2010-06-16 "Linux" "Linux Programmer's Manual"
>>>> +.SH NAME
>>>> +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 ");"
>>>> +.SH DESCRIPTION
>>>> +.BR kexec_load
>>>> +loads a new kernel that can be executed later
>>>> +by
>>>> +.I reboot(2).
>>>> +An alternative approach is to specify
>>>> +.B KEXEC_ON_CRASH
>>>> +in the
>>>> +.I flags
>>>> +argument and then the new kernel will be automatically executed on a
>>>> +system crash.
>>>> +.\" XXX figure out how this is really used
>>>> +With
>>>> +.B KEXEC_PRESERVE_CONTEXT
>>>> +specified in
>>>> +.I flags
>>>> +kexec will preserve the system hard and
>>>> +software state before executing the kexec kernel. This
>>>> +could be used for system suspend.
>>>> +
>>>> +.I flags
>>>> +also contains the architecture of the executed kernel or
>>>> +be
>>>> +.I KEXEC_ARCH_DEFAULT
>>>> +for the current architecture.
>>>> +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
>>>> +is the virtual entry address in the kernel image.
>>>
>>> Physical.
>>>
>>>> +.I nr_segments
>>>> +is the number of segments pointed to by the
>>>> +.I segments
>>>> +pointer.
>>>> +.I segments
>>>> +is an array of
>>>> +.I struct kexec_segment
>>>> +structures which define the kernel layout:
>>>> +.in +4n
>>>> +.nf
>>>> +
>>>> +struct kexec_segment {
>>>> +     void   *buf;    /* Buffer in user space */
>>>> +     size_t  bufsz;  /* Buffer length in user space */
>>>> +     void   *mem;    /* Virtual address of kernel */
>>>> +     size_t  memsz;  /* Virtual address length */
>>>
>>> There are again physical addresses.
>>>
>>> There is an expectation that at hand off from sys_kexec that
>>> virtual and physical addresses will be identity mapped.  But
>>> this isn't the old Alpha booting convention where you have
>>> a virtual address and then you have to parse the page table
>>> to figure out where your kernel was actually loaded.
>>>
>>>> +};
>>>> +.fi
>>>> +.in
>>>> +.PP
>>>> +.\" XXX elaborate on this
>>>> +The kernel image defined by
>>>> +.I segments
>>>> +is copied from the calling process into previously reserved memory.
>>>> +.SH CONFORMING TO
>>>> +This system call is Linux-specific.
>>>> +.SH NOTES
>>>> +kexec_load is currently not defined in glibc. To call it use:
>>>> +.in +4n
>>>> +.nf
>>>> +#define _GNU_SOURCE
>>>> +#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
>>>> +and later kernels, in earlier kernels the constants need to be copied
>>>> +out of the kernel source.
>>>> +.SH SEE ALSO
>>>> +.BR syscall (2),
>>>> +.BR reboot (2)
>>>> diff --git a/man2/reboot.2 b/man2/reboot.2
>>>> index 253bd34..87204b1 100644
>>>> --- a/man2/reboot.2
>>>> +++ b/man2/reboot.2
>>>> @@ -139,6 +139,11 @@ For the i386 architecture, the additional argument does not do
>>>>  anything at present (2.1.122), but the type of reboot can be
>>>>  determined by kernel command-line arguments ("reboot=...") to be
>>>>  either warm or cold, and either hard or through the BIOS.
>>>> +.TP
>>>> +.B LINUX_REBOOT_KEXEC
>>>> +executes a kernel that has been loaded earlier
>>>> +with
>>>> +.I kexec_load(2).
>>>>  .SH "RETURN VALUE"
>>>>  For the values of
>>>>  .I cmd
>>>> @@ -177,4 +182,5 @@ and should not be used in programs intended to be portable.
>>>>  .BR capabilities (7),
>>>>  .BR ctrlaltdel (8),
>>>>  .BR halt (8),
>>>> -.BR reboot (8)
>>>> +.BR reboot (8),
>>>> +.BR kexec_load (2)
>>>
>>
>>
>>
>> --
>> Michael Kerrisk
>> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>> Author of "The Linux Programming Interface" http://blog.man7.org/
>>
>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Author of "The Linux Programming Interface"; http://man7.org/tlpi/
>

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/