Edited kexec_load(2) [kexec_file_load()] man page for review

Hello Vivek (and all),

Thanks for the kexec_file_load() patch [for the kexec_load(2) man page] that you quite some time ago sent. I have merged it and done some substantial editing as well. Could you please take a look at the draft below, and check that the kexec_file_load() material is okay. Please could you especially pay attention to the pieces marked "FIXME(kexec_file_load)", since those are pieces about which i had questions or doubts.

.B #include <linux/kexec.h>

.BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments ","
.BI " struct kexec_segment *" segments \
", unsigned long " flags ");"

.\" FIXME(kexec_file_load):
.\" Why are the return types of kexec_load() and kexec_file_load()
.\" different?
.BI "int kexec_file_load(int " kernel_fd ", int " initrd_fd ","

.br
.BI " unsigned long " cmdline_len \
", const char *" cmdline ","
.BI " unsigned long " flags ");"

.fi
.IR Note :
There are no glibc wrappers for these system calls; see NOTES. .SH DESCRIPTION
The
.BR kexec_load ()
system call loads a new kernel that can be executed later by .BR reboot (2).
.PP
The

.I flags
argument is a bit mask that controls the operation of the call. The following values can be specified in
.IR flags :
.TP
.BR KEXEC_ON_CRASH " (since Linux 2.6.13)"
Execute the new kernel automatically on a system crash. .\" FIXME Explain in more detail how KEXEC_ON_CRASH is actually used

struct kexec_segment {

    void   *buf;        /* Buffer in user space */
    size_t  bufsz;      /* Buffer length in user space */
    void   *mem;        /* Physical address of kernel */
    size_t  memsz;      /* Physical address length */

};
.fi
.in
.PP
.\" FIXME Explain the details of how the kernel image defined by segments .\" is copied from the calling process into previously reserved memory.

.\" FIXME(kexec_file_load):
.\" Is the following rationale accurate? Does it need expanding? The
.BR kexec_file_load ()
.\" See also http://lwn.net/Articles/603116/
system call was added to provide support for systems where "kexec" loading should be restricted to
only kernels that are signed.

The
.BR kexec_load ()
system call is available only if the kernel was configured with .BR CONFIG_KEXEC .
The
.BR kexec_file_load ()
system call is available only if the kernel was configured with .BR CONFIG_KEXEC_FILE .
.\" FIXME(kexec_file_load):
.\" Does kexec_file_load() need any other CONFIG_* options to be defined?

Quoted 10 lines · Michael Kerrisk (man-pages)

Hello Vivek (and all),

Thanks for the kexec_file_load() patch [for the kexec_load(2) man page] that you quite some time ago sent. I have merged it and done some substantial editing as well. Could you please take a look at the draft below, and check that the kexec_file_load() material is okay. Please could you especially pay attention to the pieces marked "FIXME(kexec_file_load)", since those are pieces about which i had questions or doubts.

Hi Michael,

Thanks for editing this man page. I have some thoughts inline.

[..]

Quoted 10 lines

.B #include <linux/kexec.h>

.BI "long kexec_load(unsigned long " entry ", unsigned long " nr_segments ","
.BI " struct kexec_segment *" segments \
", unsigned long " flags ");"

.\" FIXME(kexec_file_load):
.\" Why are the return types of kexec_load() and kexec_file_load()
.\" different?
.BI "int kexec_file_load(int " kernel_fd ", int " initrd_fd ","

I think this is ignorance on my part. It probably should be "long" as SYSCALL_DEFINE() seems to expand to.

asmlinkage long SyS##name(__MAP(x,__SC_LONG,__VA_ARGS__));

Quoted 15 lines

.br
.BI " unsigned long " cmdline_len \
", const char *" cmdline ","
.BI " unsigned long " flags ");"

.fi
.IR Note :
There are no glibc wrappers for these system calls; see NOTES. .SH DESCRIPTION
The
.BR kexec_load ()
system call loads a new kernel that can be executed later by .BR reboot (2).
.PP
The

Quoted 8 lines

.I flags
argument is a bit mask that controls the operation of the call. The following values can be specified in
.IR flags :
.TP
.BR KEXEC_ON_CRASH " (since Linux 2.6.13)"
Execute the new kernel automatically on a system crash. .\" FIXME Explain in more detail how KEXEC_ON_CRASH is actually used

Upon boot first kernel reserves a chunk of contiguous memory (if crashkernel=<> command line paramter is passed). This memory is is used to load the crash kernel (Kernel which will be booted into if first kernel crashes).

Location of this reserved memory is exported to user space through /proc/iomem file.

User space can parse it and prepare list of segments specifying this reserved memory as destination.

Once kernel sees the flag KEXEC_ON_CRASH, it makes sure that all the segments are destined for reserved memory otherwise kernel load operation fails.

[..]

Quoted 11 lines

struct kexec_segment {

    void   *buf;        /* Buffer in user space */
    size_t  bufsz;      /* Buffer length in user space */
    void   *mem;        /* Physical address of kernel */
    size_t  memsz;      /* Physical address length */

};
.fi
.in
.PP
.\" FIXME Explain the details of how the kernel image defined by segments .\" is copied from the calling process into previously reserved memory.

Kernel image defined by segments is copied into kernel either in regular memory

or in reserved memory (if KEXEC_ON_CRASH is set). Kernel first copies list of segments in kernel memory and then goes does various sanity checks on the segments. If everything looks line, kernel copies segment data to kernel memory.

In case of normal kexec, segment data is loaded in any available memory and segment data is moved to final destination at the kexec reboot time.

In case of kexec on panic (KEXEC_ON_CRASH flag set), segment data is directly loaded to reserved memory and after crash kexec simply jumps

to starting point.

[..]

Quoted 8 lines

.\" FIXME(kexec_file_load):
.\" Is the following rationale accurate? Does it need expanding? The
.BR kexec_file_load ()
.\" See also http://lwn.net/Articles/603116/
system call was added to provide support for systems where "kexec" loading should be restricted to
only kernels that are signed.

Yes, this rationale looks good.

Quoted 10 lines

The
.BR kexec_load ()
system call is available only if the kernel was configured with .BR CONFIG_KEXEC .
The
.BR kexec_file_load ()
system call is available only if the kernel was configured with .BR CONFIG_KEXEC_FILE .
.\" FIXME(kexec_file_load):
.\" Does kexec_file_load() need any other CONFIG_* options to be defined?

Yes, it requires some other config options too.

depends on KEXEC
depends on X86_64
depends on CRYPTO=y
depends on CRYPTO_SHA256=y

CONFIG_KEXEC_VERIFY_SIG=y
CONFIG_KEXEC_BZIMAGE_VERIFY_SIG=y
CONFIG_SIGNED_PE_FILE_VERIFICATION=y
CONFIG_PKCS7_MESSAGE_PARSER=y
CONFIG_X509_CERTIFICATE_PARSER=y
CONFIG_ASYMMETRIC_PUBLIC_KEY_SUBTYPE=y

So dependency list seems pretty long. Not sure how many of these should we specify in man page.

Quoted 3 lines

Quoted 3 lines

.BR KEXEC_ON_CRASH " (since Linux 2.6.13)"
Execute the new kernel automatically on a system crash. .\" FIXME Explain in more detail how KEXEC_ON_CRASH is actually used

I wasn't expecting that you would respond to the FIXMEs that were not labeled "kexec_file_load", but I was hoping you might ;-). Thanks! I have a few additional questions to your nice notes.

Quoted 4 lines

Upon boot first kernel reserves a chunk of contiguous memory (if crashkernel=<> command line paramter is passed). This memory is is used to load the crash kernel (Kernel which will be booted into if first kernel crashes).

Can I just confirm: is it in all cases only possible to use kexec_load() and kexec_file_load() if the kernel was booted with the 'crashkernel' parameter set?

Quoted 3 lines

Location of this reserved memory is exported to user space through /proc/iomem file.

Is that export via an entry labeled "Crash kernel" in the /proc/iomem file?

Quoted 3 lines

User space can parse it and prepare list of segments specifying this reserved memory as destination.

I'm not quite clear on "specifying this reserved memory as destination". Is that done by specifying the address in the kexec_segment.mem fields?

Quoted 4 lines

Once kernel sees the flag KEXEC_ON_CRASH, it makes sure that all the segments are destined for reserved memory otherwise kernel load operation fails.

Could you point me to where this checking is done? Also, what is the error (errno) that occurs when the load operation fails? (I think the answers to these questions are "at the start of kimage_alloc_init()" and "EADDRNOTAVAIL", but I'd like to confirm.)

Quoted 14 lines

[..]

Quoted 11 lines

struct kexec_segment {

    void   *buf;        /* Buffer in user space */
    size_t  bufsz;      /* Buffer length in user space */
    void   *mem;        /* Physical address of kernel */
    size_t  memsz;      /* Physical address length */

};
.fi
.in
.PP
.\" FIXME Explain the details of how the kernel image defined by segments .\" is copied from the calling process into previously reserved memory.

Quoted 2 lines

Kernel image defined by segments is copied into kernel either in regular memory

Could you clarify what you mean by "regular memory"?

Quoted 8 lines

or in reserved memory (if KEXEC_ON_CRASH is set). Kernel first copies list of segments in kernel memory and then goes does various sanity checks on the segments. If everything looks line, kernel copies segment data to kernel memory.

In case of normal kexec, segment data is loaded in any available memory and segment data is moved to final destination at the kexec reboot time.

By "moved to final destination", do you mean "moved from user space to the final kernel-space destination"?

Quoted 3 lines

In case of kexec on panic (KEXEC_ON_CRASH flag set), segment data is directly loaded to reserved memory and after crash kexec simply jumps

By "directly", I assume you mean "at the time of the kexec_laod() call", right?

On Wed, Jan 07, 2015 at 10:17:56PM +0100, Michael Kerrisk (man-pages) wrote:

[..]

Quoted 4 lines

Quoted 3 lines

Quoted 3 lines

.BR KEXEC_ON_CRASH " (since Linux 2.6.13)"
Execute the new kernel automatically on a system crash. .\" FIXME Explain in more detail how KEXEC_ON_CRASH is actually used

Quoted 9 lines

I wasn't expecting that you would respond to the FIXMEs that were not labeled "kexec_file_load", but I was hoping you might ;-). Thanks! I have a few additional questions to your nice notes.

Quoted 4 lines

Upon boot first kernel reserves a chunk of contiguous memory (if crashkernel=<> command line paramter is passed). This memory is is used to load the crash kernel (Kernel which will be booted into if first kernel crashes).

Hi Michael,

Quoted 3 lines

Can I just confirm: is it in all cases only possible to use kexec_load() and kexec_file_load() if the kernel was booted with the 'crashkernel' parameter set?

As of now, only kexec_load() and kexec_file_load() system calls can make use of memory reserved by crashkernel=<> kernel parameter. And this is used only if we are trying to load a crash kernel (KEXEC_ON_CRASH flag specified).

Quoted 5 lines

Quoted 2 lines

Location of this reserved memory is exported to user space through /proc/iomem file.

Is that export via an entry labeled "Crash kernel" in the /proc/iomem file?

Yes.

Quoted 5 lines

Quoted 2 lines

User space can parse it and prepare list of segments specifying this reserved memory as destination.

I'm not quite clear on "specifying this reserved memory as destination". Is that done by specifying the address in the kexec_segment.mem fields?

You are absolutely right. User space can specify in kexec_segment.mem field the memory location where it expecting a particular segment to be loaded by kernel.

Quoted 9 lines

Quoted 4 lines

Once kernel sees the flag KEXEC_ON_CRASH, it makes sure that all the segments are destined for reserved memory otherwise kernel load operation fails.

Could you point me to where this checking is done? Also, what is the error (errno) that occurs when the load operation fails? (I think the answers to these questions are "at the start of kimage_alloc_init()" and "EADDRNOTAVAIL", but I'd like to confirm.)

This checking happens in sanity_check_segment_list() which is called by kimage_alloc_init().

And yes, error code returned is -EADDRNOTAVAIL.

Quoted 13 lines

Quoted 13 lines

[..]

Quoted 11 lines

struct kexec_segment {

    void   *buf;        /* Buffer in user space */
    size_t  bufsz;      /* Buffer length in user space */
    void   *mem;        /* Physical address of kernel */
    size_t  memsz;      /* Physical address length */

};
.fi
.in
.PP
.\" FIXME Explain the details of how the kernel image defined by segments .\" is copied from the calling process into previously reserved memory.

Quoted 4 lines

Quoted 2 lines

Kernel image defined by segments is copied into kernel either in regular memory

Could you clarify what you mean by "regular memory"?

I meant memory which is not reserved memory.

Quoted 10 lines

Quoted 7 lines

or in reserved memory (if KEXEC_ON_CRASH is set). Kernel first copies list of segments in kernel memory and then goes does various sanity checks on the segments. If everything looks line, kernel copies segment data to kernel memory.

In case of normal kexec, segment data is loaded in any available memory and segment data is moved to final destination at the kexec reboot time.

By "moved to final destination", do you mean "moved from user space to the final kernel-space destination"?

No. Segment data moves from user space to kernel space once kexec_load() call finishes successfully. But when user does reboot (kexec -e), at that time kernel moves that segment data to its final location. Kernel could not place the segment at its final location during kexec_load() time as that memory is already in use by running kernel. But once we are about to reboot to new kernel, we can overwrite the old kernel's memory.

Quoted 5 lines

Quoted 2 lines

In case of kexec on panic (KEXEC_ON_CRASH flag set), segment data is directly loaded to reserved memory and after crash kexec simply jumps

By "directly", I assume you mean "at the time of the kexec_laod() call", right?

Yes.

Hello Vivek,

Thanks for your comments! I've added some further text to the page based on those comments. See some follow-up questions below.

Quoted 19 lines · Vivek Goyal

On Wed, Jan 07, 2015 at 10:17:56PM +0100, Michael Kerrisk (man-pages) wrote:

[..]

Quoted 4 lines

Quoted 3 lines

Quoted 3 lines

.BR KEXEC_ON_CRASH " (since Linux 2.6.13)"
Execute the new kernel automatically on a system crash. .\" FIXME Explain in more detail how KEXEC_ON_CRASH is actually used

Quoted 9 lines

I wasn't expecting that you would respond to the FIXMEs that were not labeled "kexec_file_load", but I was hoping you might ;-). Thanks! I have a few additional questions to your nice notes.

Quoted 4 lines

Upon boot first kernel reserves a chunk of contiguous memory (if crashkernel=<> command line paramter is passed). This memory is is used to load the crash kernel (Kernel which will be booted into if first kernel crashes).

Hi Michael,

Quoted 8 lines

Quoted 3 lines

Can I just confirm: is it in all cases only possible to use kexec_load() and kexec_file_load() if the kernel was booted with the 'crashkernel' parameter set?

As of now, only kexec_load() and kexec_file_load() system calls can make use of memory reserved by crashkernel=<> kernel parameter. And this is used only if we are trying to load a crash kernel (KEXEC_ON_CRASH flag specified).

Okay.

Quoted 7 lines

Quoted 5 lines

Quoted 2 lines

Location of this reserved memory is exported to user space through /proc/iomem file.

Is that export via an entry labeled "Crash kernel" in the /proc/iomem file?

Yes.

Okay -- thanks.

Quoted 20 lines

Quoted 5 lines

Quoted 2 lines

User space can parse it and prepare list of segments specifying this reserved memory as destination.

I'm not quite clear on "specifying this reserved memory as destination". Is that done by specifying the address in the kexec_segment.mem fields?

You are absolutely right. User space can specify in kexec_segment.mem field the memory location where it expecting a particular segment to be loaded by kernel.

Quoted 9 lines

Quoted 4 lines

Once kernel sees the flag KEXEC_ON_CRASH, it makes sure that all the segments are destined for reserved memory otherwise kernel load operation fails.

Could you point me to where this checking is done? Also, what is the error (errno) that occurs when the load operation fails? (I think the answers to these questions are "at the start of kimage_alloc_init()" and "EADDRNOTAVAIL", but I'd like to confirm.)

Quoted 4 lines

This checking happens in sanity_check_segment_list() which is called by kimage_alloc_init().

And yes, error code returned is -EADDRNOTAVAIL.

Thanks. I added EADDRNOTAVAIL to the ERRORS.

Quoted 13 lines

Quoted 13 lines

Quoted 13 lines

[..]

Quoted 11 lines

struct kexec_segment {

    void   *buf;        /* Buffer in user space */
    size_t  bufsz;      /* Buffer length in user space */
    void   *mem;        /* Physical address of kernel */
    size_t  memsz;      /* Physical address length */

};
.fi
.in
.PP
.\" FIXME Explain the details of how the kernel image defined by segments .\" is copied from the calling process into previously reserved memory.

Quoted 6 lines

Quoted 4 lines

Quoted 2 lines

Kernel image defined by segments is copied into kernel either in regular memory

Could you clarify what you mean by "regular memory"?

I meant memory which is not reserved memory.

Okay.

Quoted 11 lines

Quoted 10 lines

Quoted 7 lines

or in reserved memory (if KEXEC_ON_CRASH is set). Kernel first copies list of segments in kernel memory and then goes does various sanity checks on the segments. If everything looks line, kernel copies segment data to kernel memory.

In case of normal kexec, segment data is loaded in any available memory and segment data is moved to final destination at the kexec reboot time.

By "moved to final destination", do you mean "moved from user space to the final kernel-space destination"?

Quoted 6 lines

No. Segment data moves from user space to kernel space once kexec_load() call finishes successfully. But when user does reboot (kexec -e), at that time kernel moves that segment data to its final location. Kernel could not place the segment at its final location during kexec_load() time as that memory is already in use by running kernel. But once we are about to reboot to new kernel, we can overwrite the old kernel's memory.

Got it.

Quoted 7 lines

Quoted 5 lines

Quoted 2 lines

In case of kexec on panic (KEXEC_ON_CRASH flag set), segment data is directly loaded to reserved memory and after crash kexec simply jumps

By "directly", I assume you mean "at the time of the kexec_laod() call", right?

Yes.

Thanks.

So, returning to the kexeec_segment structure:

struct kexec_segment {
void *buf; /* Buffer in user space */
size_t bufsz; /* Buffer length in user space */
void *mem; /* Physical address of kernel */
size_t memsz; /* Physical address length */
};

Are the following statements correct:
* buf + bufsz identify a memory region in the caller's virtual address space that is the source of the copy
* mem + memsz specify the target memory region of the copy
* mem is physical memory address, as seen from kernel space
* the number of bytes copied from userspace is min(bufsz, memsz)
* if bufsz > memsz, then excess bytes in the user-space buffer are ignored.
* if memsz > bufsz, then excess bytes in the target kernel buffer are filled with zeros.
?

Also, it seems to me that 'mem' need not be page aligned. Is that correct? Should the man page say something about that? (E.g., is it generally desirable that 'mem' should be page aligned?)

Likewise, 'memsz' doesn't need to be a page multiple, IIUC. Should the man page say anything about this? For example, should it note that the initialized kernel segment will be of size:

(mem % PAGE_SIZE + memsz) rounded up to the next multiple of PAGE_SIZE

And should it note that if 'mem' is not a multiple of the page size, then the initial bytes (mem % PAGE_SIZE)) in the first page of the kernel segment will be zeros?

(Hopefully I have read kimage_load_normal_segment() correctly.)

And one further question. Other than the fact that they are used with different system calls, what is the difference between KEXEC_ON_CRASH and KEXEC_FILE_ON_CRASH?

Thanks,

Michael

--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

So, returning to the kexeec_segment structure:

struct kexec_segment {
void *buf; /* Buffer in user space */
size_t bufsz; /* Buffer length in user space */
void *mem; /* Physical address of kernel */
size_t memsz; /* Physical address length */
};

Are the following statements correct:
* buf + bufsz identify a memory region in the caller's virtual address space that is the source of the copy

* mem + memsz specify the target memory region of the copy

* mem is physical memory address, as seen from kernel space

* the number of bytes copied from userspace is min(bufsz, memsz)

* if bufsz > memsz, then excess bytes in the user-space buffer are ignored.

* if memsz > bufsz, then excess bytes in the target kernel buffer are filled with zeros.

Also, it seems to me that 'mem' need not be page aligned. Is that correct? Should the man page say something about that? (E.g., is it generally desirable that 'mem' should be page aligned?)

Likewise, 'memsz' doesn't need to beta page multiple, IIUC. Should the man page say anything about this? For example, should it note that the initialized kernel segment will be of size:

(mem % PAGE_SIZE + memsz) rounded up to the next multiple of PAGE_SIZE

And should it note that if 'mem' is not a multiple of the page size, then the initial bytes (mem % PAGE_SIZE)) in the first page of the kernel segment will be zeros?

(Hopefully I have read kimage_load_normal_segment() correctly.)

And one further question. Other than the fact that they are used with different system calls, what is the difference between KEXEC_ON_CRASH and KEXEC_FILE_ON_CRASH?

On Fri, Jan 16, 2015 at 02:30:25PM +0100, Michael Kerrisk (man-pages) wrote:
[..]

Quoted 1 line

Hi Michael,

Please find my responses below. Sorry, I got stuck in other work and forgot about this thread.

Quoted 9 lines

So, returning to the kexeec_segment structure:

struct kexec_segment {
void *buf; /* Buffer in user space */
size_t bufsz; /* Buffer length in user space */
void *mem; /* Physical address of kernel */
size_t memsz; /* Physical address length */
};

Quoted 3 lines

Are the following statements correct:
* buf + bufsz identify a memory region in the caller's virtual address space that is the source of the copy

Yes.

Quoted 1 line

* mem + memsz specify the target memory region of the copy

Yes.

Quoted 1 line

* mem is physical memory address, as seen from kernel space

Yes.

Quoted 1 line

* the number of bytes copied from userspace is min(bufsz, memsz)

Yes. bufsz can not be more than memsz. There is a check to validate this in kernel.

	result = -EINVAL;
	for (i = 0; i < nr_segments; i++) {
		if (image->segment[i].bufsz > image->segment[i].memsz)
			return result;
	}

Quoted 2 lines

* if bufsz > memsz, then excess bytes in the user-space buffer are ignored.

You will get -EINVAL.

Quoted 2 lines

* if memsz > bufsz, then excess bytes in the target kernel buffer are filled with zeros.

Yes.

Quoted 3 lines

Also, it seems to me that 'mem' need not be page aligned. Is that correct? Should the man page say something about that? (E.g., is it generally desirable that 'mem' should be page aligned?)

mem and memsz need to be page aligned. There is a check for that too.

	mstart = image->segment[i].mem;
	mend   = mstart + image->segment[i].memsz;
	if ((mstart & ~PAGE_MASK) || (mend & ~PAGE_MASK))
		return result;

Quoted 7 lines

Likewise, 'memsz' doesn't need to beta page multiple, IIUC. Should the man page say anything about this? For example, should it note that the initialized kernel segment will be of size:

(mem % PAGE_SIZE + memsz) rounded up to the next multiple of PAGE_SIZE

Quoted 5 lines

And should it note that if 'mem' is not a multiple of the page size, then the initial bytes (mem % PAGE_SIZE)) in the first page of the kernel segment will be zeros?

(Hopefully I have read kimage_load_normal_segment() correctly.)

Both mem and memsz need to be page aligned.

Quoted 3 lines

And one further question. Other than the fact that they are used with different system calls, what is the difference between KEXEC_ON_CRASH and KEXEC_FILE_ON_CRASH?

Right now I can't think of any other difference. They both tell respective system call that this kernel needs to be loaded in reserved memory region for crash kernel.

Quoted 10 lines

Quoted 1 line

* the number of bytes copied from userspace is min(bufsz, memsz)

Yes. bufsz can not be more than memsz. There is a check to validate this in kernel.

	result = -EINVAL;
	for (i = 0; i < nr_segments; i++) {
		if (image->segment[i].bufsz > image->segment[i].memsz)
			return result;
	}

Okay. So it's more precise to leave discussion of min(bufz, memsz) out of the man page just to say: bufsz bytes are transferred; if bufsz < memsz, then the excess bytes in the target region are filled with zeros. Right?

Quoted 1 line

Both mem and memsz need to be page aligned.

And the error if not is EADDRNOTAVAIL, right?

Quoted 5 lines

Quoted 4 lines

And one further question. Other than the fact that they are used with different system calls, what is the difference between KEXEC_ON_CRASH and KEXEC_FILE_ON_CRASH?

Quoted 3 lines

Right now I can't think of any other difference. They both tell respective system call that this kernel needs to be loaded in reserved memory region for crash kernel.

Okay.

I've made various adjustments to the page in the light of your comments above. Thanks!

Quoted 2 lines

I've made various adjustments to the page in the light of your comments above. Thanks!

Thank you for following it up and improving kexec man page.

[Dropping Andi into CC, which I should have done to start with, since he wrote the original page, and might also have some comments]

Hello Vivek,

Quoted 3 lines

Quoted 2 lines

I've made various adjustments to the page in the light of your comments above. Thanks!

Quoted 1 line

Thank you for following it up and improving kexec man page.

You're welcome. So, by now, I've made quite a lot of changes (including adding a number of cases under ERRORS). I think the revised kexec_load/kexec_file_load page is pretty much ready to go, but would you be willing to give the text below a check over first?

Quoted 5 lines · Michael Kerrisk (man-pages)

Hello Vivek,

Quoted 3 lines

Quoted 2 lines

I've made various adjustments to the page in the light of your comments above. Thanks!

Quoted 7 lines

Quoted 1 line

Thank you for following it up and improving kexec man page.

You're welcome. So, by now, I've made quite a lot of changes (including adding a number of cases under ERRORS). I think the revised kexec_load/kexec_file_load page is pretty much ready to go, but would you be willing to give the text below a check over first?

Hi Michael,

I had a quick look and it looks good to me.

Thanks
Vivek

Quoted 16 lines · Vivek Goyal

Quoted 5 lines · Michael Kerrisk (man-pages)

Hello Vivek,

Quoted 3 lines

Quoted 2 lines

I've made various adjustments to the page in the light of your comments above. Thanks!

Quoted 7 lines

Quoted 1 line

Thank you for following it up and improving kexec man page.

You're welcome. So, by now, I've made quite a lot of changes (including adding a number of cases under ERRORS). I think the revised kexec_load/kexec_file_load page is pretty much ready to go, but would you be willing to give the text below a check over first?

Hi Michael,

Quoted 4 lines

I had a quick look and it looks good to me.

Thanks
Vivek

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Quoted 17 lines · Scot Doyle

Quoted 16 lines · Vivek Goyal

Quoted 5 lines · Michael Kerrisk (man-pages)

Hello Vivek,

Quoted 3 lines

Quoted 2 lines

I've made various adjustments to the page in the light of your comments above. Thanks!

Quoted 7 lines

Quoted 1 line

Thank you for following it up and improving kexec man page.

You're welcome. So, by now, I've made quite a lot of changes (including adding a number of cases under ERRORS). I think the revised kexec_load/kexec_file_load page is pretty much ready to go, but would you be willing to give the text below a check over first?

Hi Michael,

Quoted 8 lines

Quoted 4 lines

I had a quick look and it looks good to me.

Thanks
Vivek

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Hmm.., I can't see an explicity dependency between RELOCATABLE and KEXEC. Both KEXEC and KEXEC_FILE should be able to load a kernel even if it had RELOCATABLE=n.

Just that kernel will run from the address it has been built for.

Thanks
Vivek

Quoted 27 lines · Vivek Goyal

Quoted 17 lines · Scot Doyle

Quoted 16 lines · Vivek Goyal

Quoted 5 lines · Michael Kerrisk (man-pages)

Hello Vivek,

Quoted 3 lines

Quoted 2 lines

I've made various adjustments to the page in the light of your comments above. Thanks!

Quoted 7 lines

Quoted 1 line

Thank you for following it up and improving kexec man page.

You're welcome. So, by now, I've made quite a lot of changes (including adding a number of cases under ERRORS). I think the revised kexec_load/kexec_file_load page is pretty much ready to go, but would you be willing to give the text below a check over first?

Hi Michael,

Quoted 8 lines

Quoted 4 lines

I had a quick look and it looks good to me.

Thanks
Vivek

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Quoted 8 lines

Hmm.., I can't see an explicity dependency between RELOCATABLE and KEXEC. Both KEXEC and KEXEC_FILE should be able to load a kernel even if it had RELOCATABLE=n.

Just that kernel will run from the address it has been built for.

Thanks
Vivek

Confusing, right? kexec_file_load returns -ENOEXEC and dmesg says "kexec-bzImage64: XLF_CAN_BE_LOADED_ABOVE_4G is not set." which leads to arch/x86/boot/header.S line 396:

#if defined(CONFIG_RELOCATABLE) && defined(CONFIG_X86_64)  
   /* kernel/boot_param/ramdisk could be loaded above 4g */
# define XLF1 XLF_CAN_BE_LOADED_ABOVE_4G
#else
# define XLF1 0
#endif

Quoted 19 lines · Scot Doyle

Quoted 5 lines · Vivek Goyal

Quoted 3 lines · Scot Doyle

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Quoted 8 lines

Hmm.., I can't see an explicity dependency between RELOCATABLE and KEXEC. Both KEXEC and KEXEC_FILE should be able to load a kernel even if it had RELOCATABLE=n.

Just that kernel will run from the address it has been built for.

Thanks
Vivek

Confusing, right? kexec_file_load returns -ENOEXEC and dmesg says "kexec-bzImage64: XLF_CAN_BE_LOADED_ABOVE_4G is not set." which leads to arch/x86/boot/header.S line 396:

Quoted 6 lines

#if defined(CONFIG_RELOCATABLE) && defined(CONFIG_X86_64)  
   /* kernel/boot_param/ramdisk could be loaded above 4g */
# define XLF1 XLF_CAN_BE_LOADED_ABOVE_4G
#else
# define XLF1 0
#endif

Ah, this one. Actually generic kexec file loading implementation does not impose this restriction. It is the image specific loader part which decides what kind of bzImage it can load.

Current implementation (kexec-bzimage64.c), is only supporting loading bzImages which are 64bit and can be loaded above 4G. This simplifies the implementation of loader.

But there is nothing which prevents one from implementing other image loaders.

So instead of saying that kexec_file_load() depends on CONFIG_RELOCATABLE, it might be better to say in man page that currently this system call supports only loading a bzImage which is 64bit and which can be loaded above 4G too.

Thanks
Vivek

Quoted 43 lines · Vivek Goyal

Quoted 19 lines · Scot Doyle

Quoted 5 lines · Vivek Goyal

Quoted 3 lines · Scot Doyle

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Quoted 8 lines

Hmm.., I can't see an explicity dependency between RELOCATABLE and KEXEC. Both KEXEC and KEXEC_FILE should be able to load a kernel even if it had RELOCATABLE=n.

Just that kernel will run from the address it has been built for.

Thanks
Vivek

Confusing, right? kexec_file_load returns -ENOEXEC and dmesg says "kexec-bzImage64: XLF_CAN_BE_LOADED_ABOVE_4G is not set." which leads to arch/x86/boot/header.S line 396:

Quoted 6 lines

#if defined(CONFIG_RELOCATABLE) && defined(CONFIG_X86_64)
   /* kernel/boot_param/ramdisk could be loaded above 4g */
# define XLF1 XLF_CAN_BE_LOADED_ABOVE_4G
#else
# define XLF1 0
#endif

Ah, this one. Actually generic kexec file loading implementation does not impose this restriction. It is the image specific loader part which decides what kind of bzImage it can load.

Current implementation (kexec-bzimage64.c), is only supporting loading bzImages which are 64bit and can be loaded above 4G. This simplifies the implementation of loader.

But there is nothing which prevents one from implementing other image loaders.

So instead of saying that kexec_file_load() depends on CONFIG_RELOCATABLE, it might be better to say in man page that currently this system call supports only loading a bzImage which is 64bit and which can be loaded above 4G too.

Quoted 2 lines

Thanks
Vivek

Thanks, I agree, and think it would make sense to list them as part of the page's ENOEXEC error.

Quoted 44 lines · Scot Doyle

Quoted 43 lines · Vivek Goyal

Quoted 19 lines · Scot Doyle

Quoted 5 lines · Vivek Goyal

Quoted 3 lines · Scot Doyle

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Quoted 8 lines

Hmm.., I can't see an explicity dependency between RELOCATABLE and KEXEC. Both KEXEC and KEXEC_FILE should be able to load a kernel even if it had RELOCATABLE=n.

Just that kernel will run from the address it has been built for.

Thanks
Vivek

Confusing, right? kexec_file_load returns -ENOEXEC and dmesg says "kexec-bzImage64: XLF_CAN_BE_LOADED_ABOVE_4G is not set." which leads to arch/x86/boot/header.S line 396:

Quoted 6 lines

#if defined(CONFIG_RELOCATABLE) && defined(CONFIG_X86_64)
   /* kernel/boot_param/ramdisk could be loaded above 4g */
# define XLF1 XLF_CAN_BE_LOADED_ABOVE_4G
#else
# define XLF1 0
#endif

Ah, this one. Actually generic kexec file loading implementation does not impose this restriction. It is the image specific loader part which decides what kind of bzImage it can load.

Current implementation (kexec-bzimage64.c), is only supporting loading bzImages which are 64bit and can be loaded above 4G. This simplifies the implementation of loader.

But there is nothing which prevents one from implementing other image loaders.

So instead of saying that kexec_file_load() depends on CONFIG_RELOCATABLE, it might be better to say in man page that currently this system call supports only loading a bzImage which is 64bit and which can be loaded above 4G too.

Quoted 5 lines

Quoted 2 lines

Thanks
Vivek

Thanks, I agree, and think it would make sense to list them as part of the page's ENOEXEC error.

Scott, could you then phras a couple of sentences that capture thge details, so I can add it to the ENOEXEC error?

Thanks,

Michael

Quoted 51 lines · Michael Kerrisk (man-pages)

Quoted 44 lines · Scot Doyle

Quoted 43 lines · Vivek Goyal

Quoted 19 lines · Scot Doyle

Quoted 5 lines · Vivek Goyal

Quoted 3 lines · Scot Doyle

When I tested, kexec_file_load required CONFIG_RELOCATABLE. Is the same true for kexec_load? Would it make sense to note this in the man pages along with the need for CONFIG_KEXEC_FILE, etc? Or as an error message?

Quoted 8 lines

Hmm.., I can't see an explicity dependency between RELOCATABLE and KEXEC. Both KEXEC and KEXEC_FILE should be able to load a kernel even if it had RELOCATABLE=n.

Just that kernel will run from the address it has been built for.

Thanks
Vivek

Confusing, right? kexec_file_load returns -ENOEXEC and dmesg says "kexec-bzImage64: XLF_CAN_BE_LOADED_ABOVE_4G is not set." which leads to arch/x86/boot/header.S line 396:

Quoted 6 lines

#if defined(CONFIG_RELOCATABLE) && defined(CONFIG_X86_64)
   /* kernel/boot_param/ramdisk could be loaded above 4g */
# define XLF1 XLF_CAN_BE_LOADED_ABOVE_4G
#else
# define XLF1 0
#endif

Ah, this one. Actually generic kexec file loading implementation does not impose this restriction. It is the image specific loader part which decides what kind of bzImage it can load.

Current implementation (kexec-bzimage64.c), is only supporting loading bzImages which are 64bit and can be loaded above 4G. This simplifies the implementation of loader.

But there is nothing which prevents one from implementing other image loaders.

So instead of saying that kexec_file_load() depends on CONFIG_RELOCATABLE, it might be better to say in man page that currently this system call supports only loading a bzImage which is 64bit and which can be loaded above 4G too.

Quoted 5 lines

Quoted 2 lines

Thanks
Vivek

Thanks, I agree, and think it would make sense to list them as part of the page's ENOEXEC error.

Quoted 6 lines

Scott, could you then phras a couple of sentences that capture thge details, so I can add it to the ENOEXEC error?

Thanks,

Michael

Yes, maybe something like "kernel_fd does not refer to an open file, or the file type is not supported. Currently, the file must be a bzImage and contain an x86 kernel loadable above 4G in memory (see Documentation/x86/boot.txt)."?

boot.txt explains that loading above 4G implies 64-bit and is specified via a bit in xloadflags added in Linux 3.8.