Re: [Fastboot] [RFC] - Kexec man page

[David Wilder]

Hi Milton
I am very sorry it has taken me so long to respond to your comments. I 
just slipped my mind. I have incorporated your comments into this new 
kexec man page. Please let me know what you think.

Dave...


Milton Miller wrote:

On Fri May 5 12:22:47 PDT 2006, David Wilder wrote

Attached is a replacement man page for kexec. Please let me know what
you think.

Included is a html version for easy viewing.

Thanks.



Hi. I was scanning fastboot list and found your post. Since it
doesn't look like you got any feedback I'll give you some.

First of all, thanks for starting the effort. I'll be responding
the the output of TERM=dumb man kexec | sed 's/.^H//' | fmt -65.


SYNOPSIS
/sbin/kexec [-v (--version)] [-f (--force)] [-x
(--no-ifdown)] [-l (--load)] [-p (--load-panic)] [-u
(--unload)] [-e (--exec)] [-t (--type)]
[--mem-min=addr] [--mem-max=addr]



First of all, the long options in the synopsis and option lists are
formatted incorrectly. They are appearing as you have to specify
both -v and the version.

You should have one line for loading, and a second line for -e
and a third for unloading at the minimum. I guess another for --v.

DESCRIPTION
kexec is a system call


you are describing /sbin/kexec. Kexec is a utility

that enables you to load and boot
into another kernel from the currently running kernel.

using the kexec_load(2) and reboot(2) systemm calls.

kexec performs the function of the boot loader

(yes it is the loader)

from
within the kernel.

No, it is userspace. The kernel does the final placement and exec.

Kexec is a utility to prepare, load, and start a new operating 
enviornment replacing the currently running kernel. When the
new environment is the same kernel, it is effectively a reboot
of the existing system.

The primary difference between a
standard system boot and a kexec boot is that the


kernel directly invokes the new kernel instead of calling
the BIOS or firmare. Because the firmware is bypassed, any

hardware initialization normally performed by the BIOS or
firmware (depending on architecture) is not performed
during a kexec boot. This has the effect of reducing the
time required for a reboot.


Make sure you have selected CONFIG_KEXEC=y when
configuring the kernel. The CONFIG_KEXEC option enables
the kexec system call.


To use kexec, your running kernel must have been compiled with 
CONFIG_KEXEC=y, which enables the kexec_load(2) system call.


USAGE
Using kexec consists of

(1) loading the kernel to be rebooted to into
memory, and


operating environment consisting of a kernel, initrd, command line 
paramters, and other architecture specific code and data.

(2) actually rebooting to the
pre-loaded kernel.

To load a kernel, the syntax is as follows:


A kernel is laoded with the -l option.


kexec -l kernel-image
--append=command-line-options --ini-
trd=initrd-image


This should be a line in SYNOPSIS


where kernel-image is the kernel file that you intend to
reboot to.



Note: Compressed kernel images such as bzImage are not
supported by kexec. Use the uncompressed vmlinux.


(This is architecture specific, as I just wrote a zImage varient
to be supported for ppc64. But I don't support zImiage.initrd
today, so not too far frpm correct.)

Something like:

The kexec program recoginses several file formats for the linux
kernel depending on the architecture. It extracts information
from the running kernel and supplied image to run, determines
a memory layout, and adds code necessary to setup the system
as expected by entry point of the image such as setting up a
stack or loading pointers to data in cpu registers. It supplies
the assembled content as a list of data to be placed in specified
memory locations and an the address the cpu should start executing
after the content has been copied to the specified location.

Hmm.. that sounds like a lot of it should be in description.

Here you might say "for most architectues the preferred format
for booting a linux kernel is an elf file", although that may
be pushing it.


Insert the command-line parameters that must be passed to
the new ker- nel into command-line-options. Passing
the exact contents of /proc/cmdline into
command-line-options is the safest way to ensure that
correct values are passed to the rebooting kernel.


When rebooting into a new kernel, a good starting point for the
command line paramters is those passed to the existing kernel They
can be found in the file /proc/cmdline.

(The new enviornment may not be a linux kernel).

The optional initrd-image is the initrd image to be used
during boot.


Many distrobutions require a specific to be loaded with their
kernel to boot. If your existing kernel was supplied an initrd
via your bootloader you will probably need to specify that image
here.

EXAMPLE
For example, if the kernel image you want to
reboot to is /boot/vmlinux, the contents of /proc/cmdline
is root=/dev/hda1, and the path to the initrd is
/boot/initrd, then you would use the following command to
load the kernel:

kexec -l /boot/vmlinux
--append=root=/dev/hda1 --initrd=/boot/initrd


Use something with two command line optons, to show the need for quotes.

OPTIONS
-e (--exec)
Run the currently loaded kernel.



I already commented this should be something like
-e
--exec Run the currently loaded kernel.

-h (--help)
Open a help file for kexec.


Display a synopsis of the avaliable options

--mem-min=addr
Specify the lowest memory address addr to load code
into.

--mem-max=addr
Specify the highest memory address addr to load
code into.


Are these really generic?

ARCHITECTURE OPTIONS

i386 (and x86_64 ?) architecture options


Please add other architectures (eg powerpc 64-bit, ia64, s390)
as you can find their patches.

You should probably go into a bit more detail about the load-panic
option.

Don't take my wording as gospel. I'm sure it can stand further
editing, I'm a techie not a writer.

milton




--
David Wilder
IBM Linux Technology Center
Beaverton, Oregon, USA 
[EMAIL PROTECTED]
(503)578-3789

.\" Process this file with
.\" groff -man -Tascii kexec.8
.\"
.TH kexec 8 "April 2006" Linux "User Manuals"
.SH NAME
kexec \- directly boot into a new kernel
.SH SYNOPSIS
.B /sbin/kexec
.RI \-l|\-\-load\  kernel-image
.RI "[\-\-append=" command\-line\-options]
.RI "[\-\-initrd=" initrd\-image]
[\-\-mem\-min= addr ] [\-\-mem\-max= addr ]
[-t|\-\-type]

.B /sbin/kexec
-e|\-\-exec [-f|\-\-force] [-x|\-\-no-ifdown]

.B /sbin/kexec
-u|\-\-unload

.B /sbin/kexec
-p|\-\-load-panic

.B /sbin/kexec
-v|\-\-version 

.B /sbin/kexec
-h|\-\-help

.SH DESCRIPTION
.B kexec
is a utility that enables you to load and boot into another
kernel from the currently running kernel using the kexec_load(2) and reboot(2) system calls. The kexec utility prepares, loads, and starts a new operating environment replacing the currently running kernel.  When the new environment is the same kernel that is running, it is effectively a reboot of the existing system.
The primary difference between a standard system boot and a
.B kexec
boot is that the running kernel directly invokes the new kernel instead of calling the BIOS or firmware.  Because the firmware is bypassed, any hardware initialization normally performed by the firmware is not performed during a
.B kexec
boot. This has the effect of reducing the time required for a reboot.
.PP
To use kexec, your running kernel must have been compiled with the
.B CONFIG_KEXEC=y
, this enables the kexec_load(2) system call.
.SH USAGE
Using
.B kexec
consists of

.RS
(1) loading the kernel to be rebooted into memory. A kernel is loaded with the \fB-l\fR option.  The operating environment such as initrd and command line parameters is specified using the optional and \fB\-\-initrd\fR \fB\-\-append\fR options.
.RE
.RS
(2) actually rebooting to the pre-loaded kernel using the \fB-e\fR option.
.RE
.PP

.I kernel\-image
is the kernel file that you intend to reboot to.  The kexec program recognizes several file formats for the linux kernel depending on architecture.  For most architectures the perferred format is a linux kernel in elf format (vmlinux).
.PP
When rebooting into a new linux kernel and supplying the \fIkernel\fR parameters, a good staring point are those passed to the existing kernel.  They can be found in the file /proc/cmdline.
.PP
If your environment requires the use of an initrd you will most likley need to specify that image using \-\-initrd=
.I \initrd\-image
option.
.PP

.SH EXAMPLE
.PP
For example, if the kernel image you want to reboot to is
.BR /boot/vmlinux,
and the contents of /proc/cmdline is
.BR "root\=/dev/hda1 vga=0x317 selinux=0"
, and the path to the initrd is
.BR /boot/initrd
, then you would use the following command to load the kernel:

.RS
.B kexec
\-l\  /boot/vmlinux
\-\-append="root=/dev/hda1 vga=0x317 selinux=0" \-\-initrd=/boot/initrd
.RE
.PP
After this kernel is loaded, it can be booted to at any time using the
command:

.RS
.BR kexec \ \-e
.RE

.SH OPTIONS
.TP
\fB\-e\fR, \fB\-\-exec\fR Run the currently loaded kernel.
.TP
\fB\-f\fR, \fB\-\-force\fR Force an immediate \fBkexec\fR
call, do not call shutdown.
.TP
\fB\-h\fR, \fB\-\-help\fR
Open a help file for \fBkexec\fR.
.TP
\fB\-l\fR, \fB\-\-load\fR \fIkernel\fR 
Load the specified \fIkernel\fR into the current kernel.
.TP
\fB\-p\fR, \fB\-\-load\-panic\fR Load the new kernel for use on panic.  This option is used by kdump.
.TP
\fB\-t\fR, \fB\-\-type=\fRtype Specify that the new kernel is of this
.I type.
.TP
\fB\-u\fR, \fB\-\-unload\fR Unload the current \fBkexec\fR target kernel.
.TP
\fB\-v\fR, \fB\-\-version\fR Return the version number of the installed utility.
.TP
\fB\-x\fR, \fB\-\-no\-ifdown\fR
Shut down the running kernel, but restore the interface on reload. (If
this option is used, it must be specified last.)
.TP
.BI \-\-mem\-min= addr
Specify the lowest memory address
.I addr
to load code into.
.TP
.BI \-\-mem\-max= addr
Specify the highest memory address
.I addr
to load code into.

.SH SUPPORTED KERNEL FILE TYPES AND OPTIONS
.B Beoboot-x86
.RS
.TP
.B \-\-args\-elf
Pass ELF boot notes.
.TP
.B \-\-args\-linux
Pass Linux kernel style options.
.TP
.B \-d|\-\-debug
Enable debugging messages.
.TP
.B \-\-real\-mode
Use the kernel's real mode entry point.
.RE
.PP
.B elf-x86
.RS
.TP
.BI \-\-append= string
Append
.I string
to the kernel command line.
.TP
.BI \-\-command\-line= string
Set the kernel command line to
.IR string .
.TP
.BI \-\-initrd= file
Use
.I file
as the kernel's initial ramdisk.
.TP
.BI \-\-ramdisk= file
Use
.I file
as the kernel's initial ramdisk.
.RE
.PP
.B multiboot-x86
.RS
.TP
.BI \-\-command\-line= string
Set the kernel command line to
.IR string .
.TP
.BI \-\-module= "mod arg1 arg2 ..."
Load module
.I mod
with command-line arguments
.I "arg1 arg2 ..."
This parameter can be specified multiple times.
.RE

.SH ARCHITECTURE OPTIONS
.TP
.B \-\-console\-serial
Enable the serial console.
.TP
.B \-\-console\-vga
Enable the VGA console.
.TP
.B \-\-elf32\-core\-headers
Prepare core headers in ELF32 format.
.TP
.B \-\-elf64\-core\-headers
Prepare core headers in ELF64 format.
.TP
.B \-\-reset\-vga
Attempt to reset a standard VGA device.
.TP
.BI \-\-serial= port
Specify the serial
.I port
for debug output.
.TP
.BI \-\-serial\-baud= baud_rate
Specify the
.I baud rate
of the serial port.
_______________________________________________
fastboot mailing list
fastboot@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/fastboot