[PATCH] kexec_load manpage

[Michael Kerrisk]

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/