	--------------------------------------------------------------------
	ELILO.EFI: Linux bootloader for EFI/IA-64 or EFI/IA-32 based systems
	--------------------------------------------------------------------
	         Stephane Eranian <eranian@hpl.hp.com>

		              August  2001

	       Copyright (C) 2000-2001 Hewlett-Packard Co.


I/ Introduction
   ------------

This document mostly describes how to use ELILO on EFI-based platforms.
For IA-64 platforms, elilo is used to load Linux/ia64 kernels. 
The same code base can also be used on IA-32 (Pentium-based)
platforms to load Linux/x86 kernels. This document describes ELILO version 3.1. 
Go to section  VIII for more information on ELILO/ia32.

II/ Command line options
    --------------------

	elilo [-hDpPVva] [-d nsec] [-C config] [-i initrd] [kernel [kernel options...]]


	-h	Display a list of all possible command line options.

	-V	Print the version number and exit.

	-d nsec Specify the number of 10th of seconds before loading the
		kernel.

	-C file Specify the config file to use. The default is elilo.conf

	-P	Verify config file syntax only. this option causes ELILO to 
		parse the config file and generate a report on the console.
		No kernel is loaded.

	-v	Turn on verbose mode. ELILO prints more message about what it 
		is doing. For each occurence of this option the verbosity level
		is increased by one. The maximum level is 5.

	-a	Always check for alternate kernel image. The default behavior
		of ELILO is to NOT look for an alternate image. This 
		option overrides this behavior and ELILO is checking for 
		alternate images no matter what. Alternate images are
		specified using EFI variables.

	-p      force interactive prompt mode. Valid when no kernel image is 
		specified on the command line

	-D	print debug output

	-i file Use file as the initial ramdisk (bootstrapping system).

	As of version 3.0 all filenames can include a device name using the following syntax:

		dev_name:/path/to/my/file

	The 'dev_name' component depends on the naming scheme selected and the detected
	devices for your system. The current mapping is printed at verbosity level 1 or
	more. While at the interactive prompt the '?' reprints the map.

	See README.devschemes for more information on naming schemes.

	As of version 3.1, it is possible to use foward slash ('/') in a path
	name even when access a FAT32 filesystem.

III/ Configuration File
     ------------------

     This version of ELILO now supports a config file with options similar to
     the LILO/x86 loader.

     The list of supported options is printed when ELILO is invoked with the 
     -h flag. 

     Options are divided in 2 groups:
     	- global options which affect the behavior of ELILO and apply to all
	images.
	- image options which are specific to a particular image.

     The ELILO config file follows the LILO/x86 syntax. First come the global
     options, then the list of images and options for each of them, if
     necessary. At least one image must be defined.

     Options have types. Three types are defined:
     	- boolean: set or not set
	- string : a string of characters which can be quoted if necessary
	- number 

     See the netbooting section for more information about the config file
     when booting over the network.

     The list of currently supported options is:

    Global Options:
    ---------------
    default=value	Name the default image to boot. If not defined ELILO
    		 	will boot the first defined image.

    timeout=number	The number of 10th of seconds to wait while in
    			interactive mode before autobooting default kernel.
			Default is infinity.

    delay=number	The number of 10th of seconds to wait before
    			autobooting when not in interactive mode. 
			Default is 0.
   
    prompt		Force interactive mode

    verbose=number	Set level of verbosity [0-5]. Default 0 (no verbose)

    root=filename	Set global root filesystem for Linux/ia64

    read-only		Force root filesystem to be mounted read-only

    append=string	Append a string of options to kernel command line

    initrd=filename	Name of initrd file

    image=filename	Define a new image

    Image options:
    --------------
    root=filename	Set root filesystem for kernel

    read-only		Force root filesystem to be mounted read-only

    append=string	Append a string of options to kernel command line

    initrd=filename	Name of initrd file

    label=string	Logical name of image (used in interactive mode)

  IA-64 specific options:
  -----------------------

    Global options:
    ---------------
    fpswa=file          Specify the filename for a specific FPSWA to load. 
			If this option is used then no other file will be tried.

    relocatable		In case of memory allocation error at initial load point of
    			kernel, allow attempt to relocate (assume kernels is relocatable)

    Image options:
    --------------
    relocatable		In case of memory allocation error at initial load point of
    			kernel, allow attempt to relocate (assume this kernel is relocatable)

  IA-32 specific options:
  -----------------------
  	none defined yet.

III/ Booting a kernel from local system
     -----------------------------------

This discussion assumes your system has at least one EFI 
system partition from which to boot from. The first recognized bootable 
partition is always mapped to handle fs0. 

To be able to boot a Linux kernel from EFI, you simply need to copy the kernel 
image onto the EFI system partition. This can be easily accomplished using 
the mtools or by mounting the EFI paritition (vfat or msdos) and copying the 
file. Similarly the ELILO config file (elilo.conf) can be copied to the same
partition. PLEASE NOTE THAT THIS FILE MUST BE AN ASCII FILE AND NOT A UNICODE
FILE.

In the following discussion, we assume that:
	- you have a kernel image in the EFI partition called vmlinux
	- that partition is called fs0
	- you have installed in that partition the elilo.efi executable
	- you optionally have an elilo.conf config file

So to boot a kernel, simply power cycle the machine. Once you get to the EFI
shell prompt, simply go to the first bootable device fs0, by simply doing:

	Shell> fs0:
	fs0:\>

You might need to make sure that the Shell Path is set such that it will load
ELILO from fs0:. You can verify this by typing:
	fs0:\> set
   	path : fs0:\
	
At this point you can invoke ELILO:

	fs0:\> elilo

If there is no config file, then it will:
	- pick up the kernel image name vmlinux if it exists, otherwise it
	  will return with an error.

	- pass no argument to the kernel, except for the BOOT_IMAGE=
	  string (see later for discussion).
	
You can specify command line options to ELILO just like you would do on the 
PC elilo boot prompt. For instance if you want to specify an alternate root
filesystem, you can say:

	fs0:\> elilo vmlinux root=/dev/sda5

You can specify as many paramters as you want. They syntax follows the kernel
rule, i.e., list of value pairs (or even single values) separated by space.
A more complicated example would be:

	fs0:\> elilo vmlinux root=/dev/sda2 console=tty console=ttyS0,115200n8


In the case a config file is found, then elilo will behaves according to
the definition in that file. However if elilo was invoked with options,
the kernel name or image name (as defined by the config file) will be used
instead of the config default image.

It is important to note that as opposed to LILO/x86, ELILO supports options
where the kernel file name or the logical label name is used. For each name,
it will first look to see if a label (image) with that name exists. If it
exists then it will follow the config file. If the label does not exist then
it will treat the name as a filename.

Using the "prompt" option in the config file, ELILO can enter an interactive
mode where it waits for the user to specify a kernel name and options.
If no input is received before "timeout" 10th of seconds, ELILO will
autoboot the default image. The user can press the "Tab" key to see the list
of defined labels. Pressing "Esc" or CTRL-D or CRTL-C in this mode will 
abort ELILO. Note that it is not possible to specify an initial ramdisk from 
the interactive prompt. To specify an initrd from the command line, you must
use the "-i" option. From the config file, simply use the "initrd" option.


Once the selection is made, ELILO will attempt to load the kernel and possibly
the initial ramdisk (initrd). At any time during the load process, the user
can interrupt by pressing a key. In this case, ELILO will go back to the
interactive mode. 

Once the kernel is loaded, ELILO will load the optional initrd. There again
it is still possible to abort the boot.


In order for users to figure out which kernel was booted with which options
ELILO ALWAYS adds an argument to pass to the kernel. It is the BOOT_IMAGE
option. It contains the name of the kernel and arguemnts. For instance,
from the example above, you would get:
	BOOT_IMAGE=vmlinux.se root=/dev/sda2

This is a useful feature during system installation to figure out which kernel
was booted.

IV/ The alternate kernel image
    --------------------------

Often times when debugging kernels you want to reboot the machine once with
your test kernel and, if something goes wrong, you want to fall back to a more
stable kernel. In addition you want to be able to do this from remote. Many
things can go wrong when doing kernel debugging. It could be that you don't
even reach user-mode. In this case however, you still want to fall back to
a stable kernel. The feature you'd like from a bootloader is 'boot once and
then fall back to safe kernel'.

This version of ELILO offers this feature and it's called 'alternate kernel 
image'.  You can configure ELILO to load a kernel only once and then whatever 
happens the next reboot falls back to a different kernel hopefully more stable.

To do this, ELILO relies on an EFI variable called 'EliloAlt'
The content of this variable is very simple: it is whatever you would normally
specify on the command line. 

The general theory of operations is that ELILO looks for the existence of
the EliloAlt' variable.

If it finds it then, it takes its content and figures out which kernel
and which arguments to use. then it deletes the variable, loads the kernel
and launch it. Next time, you reboot you fall back to a different kernel
unless you recreate the variable.

You can create an EFI variable using the /proc/efi/vars interface of the 
Linux kernel. You need to use the NULL GUID for this variable.

By default, ELILO does not check for the exitence of the variable. This 
feature is turned on by using the "-a" command line argument.

V/ Autobooting the machine
   -----------------------

Once you're satisfied with your machine setup, it is good to install an 
autoboot procedure. Using EFI, this is easily accomplished using a 'Shell' 
script with a special name: 'startup.nsh'.

When the system boots, it looks for bootable partitions and if it finds
a 'startup.nsh' file in ANY of these it will jumpstart execution from it.

So the typical way of autobooting your Linux/ia64 system is to simply create
such a file with the following content:

	# cat /boot/startup.nsh
	elilo vmlinux root=/dev/sda2

Of course, this can be simplified if there is a configuration file.

VI/ Netbooting with ELILO
    ---------------------

EFI-based systems are capable of netbooting using the PXE protocol or
the standard DHCP protocol. 

To enable the option, it is necessary to add this option in the EFI boot
manager by selecting the Ethernet card as a possible boot device. You can
add an option to the menu that will trigger the discovery phase of the
protocols.

On the server side, you need a DHCP daemon. The standard ones shipped with
Linux will work for pure DHCP protocol. If you want to use PXE, then you
need to use a PXE-aware DHCPD. At this point in time, there is no official
version of such a daemon but it should happen momentarily now.

For regular DHCP, the server does not need any special tricks. The only
limitations are those of the regular DHCP protocol. 

The netboot process will bring over the network:
	- the bootloader binary (elilo.efi)
	- an optional config file (elilo.conf)
	- the Linux kernel
	- an optional initrd

IMPORTANT INFORMATION ABOUT config file:
----------------------------------------

	As of version 3.0 of elilo, the loader will try 2 different configuration
	files to accomodate machine-specific and generic configuration in a
	scalable way.  The first config file is named after the IP address
	assigned by the DHCP/PXE protocol. For instance, if the IP address is
	192.168.2.1, then elilo will first to try load a config file called
	C0A80201.conf. This file is expected to be a machine-specific file
	which would be used one the machine has joined a larger cluster for instance.
	Now, it this file is not found, elilo will try 'elilo.conf' which is 
	considered a generic config file. It this one also fails, then elilo
	will use a builtin constant for the kernel name (vmlinux).

Those files are transfered using the TFTP protocol. Therefore the machine 
used as server must have the TFTP daemon enabled.

For PXE-based server, the same rules apply and the same files are downloaded
still using TFTP. PXE offers more flexibility as to where the data is
downloaded from and more support for failures. PXE also offer a user-friendly
menu-based boot selection menu.

A sample regular dhcpd configuration file (dhcpd.conf) is provided in this 
package. A sample PXE-aware configure file (dhcpd-pxe.conf) is also
provided.

More information on the PXE protocol can be found at the following web site:

		http://developer.intel.com/ial/wfm/

The source code for the standard and (possibly) PXE-enhanced DHCPD can be
downloaded from:
		http://www.isc.org/	

VI/ Credits
    -------

	Intel Corp.
	Stephane Eranian <eranian@hpl.hp.com>
	David Mosberger  <davidm@hpl.hp.com>
	Johannes Erdfelt <jerdfelt@valinux.com>

VII/ Bug reports
    -----------

	This is still beta software and contains some limitations and bugs.

	Please contact <eranian@hpl.hp.com> if you have any questions.

VIII/ Booting on EFI/ia32 platforms

	Until PC comes with EFI firmware builtin, you need to boot from a
	floppy that has the EFI firmware on it. Such a floppy cna be
	constructed from the EFI sample implementation and toolkit that is
	available from the Intel Developer Web site at:

		http://developer.intel.com/technology/efi/

	Once booted with the floppy and if your PC is recent enough, you
	are able to netboot Linux/ia32 the way we explained it for IA-64
	above. Alternatively, the Linux/ia32 kernel (typically vmlinuz)
	can be loaded from an EFI system partition (Fat32) or directly
	from the ext2 filsystem (like from /boot). 

IX/ Reference
      ---------

	EFI v1.02 specifictions are available from the following web site:

	http://developer.intel.com/technology/efi/

	The latest sources of ELILO can be downloaded at:

		ftp://ftp.hpl.hp.com/pub/linux-ia64

