1 --------------------------------------------------------------------
2 ELILO.EFI: Linux boot loader for
3 EFI/IA-64,EFI/IA-32 and EFI/x86_64 based systems
4 --------------------------------------------------------------------
5 Stephane Eranian <eranian@hpl.hp.com>
9 Copyright (C) 2000-2003 Hewlett-Packard Co.
10 Copyright (C) 2006-2010 Intel Co.
16 This document describes how to use ELILO on for IA-64, IA-32 and x86_64 EFI-based platforms.
17 This document describes ELILO version 3.7.
19 II/ Command line options
22 elilo [-hDpPVvaE] [-d nsec] [-C config] [-i initrd] [-c chooser] [kernel [kernel options...]]
24 -h Display a list of all possible command line options.
26 -V Print the version number and exit.
28 -d nsec Specify the number of 10th of seconds before loading the
31 -C file Specify the config file to use. The default is elilo.conf in the directory
32 that elilo.efi was loaded from.
34 -P Verify config file syntax only. this option causes ELILO to
35 parse the config file and generate a report on the console.
38 -v Turn on verbose mode. ELILO prints more message about what it
39 is doing. For each occurrence of this option the verbosity level
40 is increased by one. The maximum level is 5.
42 -a Always check for alternate kernel image. The default behavior
43 of ELILO is to NOT look for an alternate image. This
44 option overrides this behavior and ELILO is checking for
45 alternate images no matter what. Alternate images are
46 specified using the EliloAlt EFI variable.
48 -p force interactive prompt mode. Valid when no kernel image is
49 specified on the command line.
51 -D print debug output.
53 -E don't force EDD30 variable to TRUE when FALSE.
55 -i file Use file as the initial ramdisk (initrd).
57 -c name Specify which kernel chooser to use. Default is 'simple', and
58 the only other choice at present is 'textmenu'.
60 In addition, elilo supports platform specific options:
64 -r the kernel image can be relocated if initial load address is not
65 available. This options requires a special version of the kernel.
67 -F file will try to load the FPSWA driver indicated by 'file'. Only this file
68 will be attempted. When no specific file is given, elilo will try
69 loading \efi\intel firmware\fpswa.efi from all accessible EFI system
75 All file names (including the kernel file) can include a device name using the
78 dev_name:/path/to/my/kernel
80 The 'dev_name' component depends on the naming scheme selected and the detected
81 devices for your system. Some choosers may print the information automatically
82 or on demand, see chooser specific documentation for more on this. See README.devschemes
83 for more information on device naming schemes. The slash character '/' can be used as
84 a directory separator on any file systems including the EFI file system (FAT32).
90 III/ Configuration File
93 ELILO supports a config file with options similar to the LILO/x86 boot loader.
95 Elilo will use the following sequence (shown in order) when looking for its config
96 file when none is specified on the command line:
98 1/ AABBCCDD.conf (netbooting with regular DHCP)
99 where AABBCCDD is the hexadecimal representation
100 of the IP address assigned during the DHCP phase.
102 2/ elilo-ia64.conf or elilo-ia32.conf or elilo-x86_64.conf
103 The choice depends on the client platform. This step allows
104 the same DHCP/PXE server to provide files for both types of clients.
108 Unless explicitly specified on the command line, elilo looks for its config file
109 in the filesystem and directory it was loaded from. For instance, if elilo.efi
112 fs0:\> \efi\debian\elilo.efi
114 Then elilo will look for its configuration file in fs0:\efi\debian and not
115 in the root directory of fs0:. The prefix fs0:\efi\debian will be used for
116 all other files that elilo needs to download when their paths are specified
120 This rule also applies when a specific config file is passed via the -C
123 fs0:\> \efi\debian\elilo.efi -C elilo.conf
125 This will look for elilo.conf in fs0:\efi\debian and not in fs0:\.
126 To get to the elilo.conf in fs0:\, you need to specify the absolute
129 fs0:\> \efi\debian\elilo.efi -C \elilo.conf
132 The configuration file is an ASCII file and not a UNICODE file.
134 The config file contains additional options to change the behavior of the loader.
135 If the same option is specified in the config file AND on the command line, the
136 latter takes precedence. Not all options available in the config file have an
137 equivalent on command line.
139 When elilo is invoked with the -h option, it prints the list of support command line
140 options but also the list of config file options. For each option it also prints
141 the type of data expected.
143 The config file options are divided in 2 groups:
146 - image options which are specific to a particular kernel image. Each kernel image
147 must be identified with a logical name called a label.
149 - global options which affect the behavior of ELILO and apply to all images.
151 The ELILO config file follows the LILO/x86 syntax. First come the global
152 options, then the list of images and options for each of them, if
153 necessary. At least one image MUST be defined and it is possible to have
154 an empty list of global options.
156 Options have types. Three types are defined:
157 - boolean: set or not set
158 - string : a string of characters which can be quoted if necessary
159 - number (in decimal)
160 - filename: a string interpreted as a file name
163 The config file supports the following options:
167 default=value Name the default image to boot. If not defined ELILO
168 will boot the first defined image.
170 timeout=number The number of 10th of seconds to wait while in
171 interactive mode before auto booting default kernel.
174 delay=number The number of 10th of seconds to wait before
175 auto booting when not in interactive mode.
178 prompt Force interactive mode
180 verbose=number Set level of verbosity [0-5]. Default 0 (no verbose)
182 root=filename Set global root filesystem for Linux/ia64
184 read-only Force root filesystem to be mounted read-only
186 append=string Append a string of options to kernel command line
188 initrd=filename Name of initrd file
190 image=filename Define a new image
192 chooser=name Specify kernel chooser to use: 'simple' or 'textmenu'.
194 message=filename a message that is printed on the main screen if supported by
197 fX=filename Some choosers may take advantage of this option to
198 display the content of a file when a certain function
199 key X is pressed. X can vary from 1-12 to cover
200 function keys F1 to F12.
202 noedd30 do not force the EDD30 EFI variable to TRUE when FALSE. In other
203 words, don't force the EDD30 mode if not set.
207 root=filename Set root filesystem for kernel
209 read-only Force root filesystem to be mounted read-only
211 append=string Append a string of options to kernel command line
213 initrd=filename Name of initrd file
215 label=string Logical name of image (used in interactive mode)
217 description=string One line text description of the image.
219 IA-64 specific options:
220 -----------------------
224 fpswa=file Specify the filename for a specific FPSWA to load.
225 If this option is used then no other file will be tried.
227 relocatable In case of memory allocation error at initial load point of
228 kernel, allow attempt to relocate (assume kernels is relocatable)
232 relocatable In case of memory allocation error at initial load point of
233 kernel, allow attempt to relocate (assume this kernel is relocatable)
235 IA-32 specific options:
236 -----------------------
237 legacy-free Indicate that the host machine does not have a legacy BIOS at all.
240 The user can specify a kernel and related kernel options using the image label. Alternatively,
241 the user can also specify a kernel file that is not specified in the config file. In any case,
242 some of the global options (such as append) are always concatenated to whatever the user type.
244 x86_64 specific options:
245 -----------------------
248 IV/ Booting from the local system
249 -----------------------------
251 The elilo.efi binary must be in an EFI system partition (FAT32). The config
252 file, kernel image, and optional initrd ramdisk can be on the same partition
253 or even another EFI partition. In the following discussion we assume that all
254 files are on the same EFI partition which is recognized by the EFI shell (nshell)
255 as fs0. The kernel and initrd can be copied from the any linux filesystems to the
256 EFI partition using either the mtools (mcopy) or by mounting the EFI partition as
257 a vfat partition. However you do not really need this because most linux
258 distributions install both files in the EFI partition and mount this partition in /boot/efi.
260 To boot a kernel, simply power cycle the machine. Once you get to the EFI
261 shell prompt, change to the filesystem that maps to the partition where elilo is.
266 You might need to make sure that the Shell Path is set such that it will load
267 ELILO from fs0:. You can verify this by typing:
271 At this point you can invoke ELILO:
275 If there is no config file, then it will:
276 - pick up the kernel image named vmlinux if it exists, otherwise it will abort.
277 - pass no argument to the kernel.
279 You can specify the kernel image and its options on the command line.
280 For instance you can do:
282 fs0:\> elilo vmlinux root=/dev/sda5
284 You can specify as many parameters as you want. The syntax follows the kernel
285 rule, i.e., list of value pairs (or even single values) separated by space.
286 A more complicated example would be:
288 fs0:\> elilo -i initrd-2.4.9 vmlinuz-2.4.9 root=/dev/sda2 console=tty0 console="ttyS0,115200n8"
290 In this example, notice the double quotes. They are required because the comma is a control
291 character for nshell.
293 In the case a config file is found, then elilo will behave according to
294 the options in that file. However if elilo is invoked with command line options, they
295 will be combined or they will override (if conflicting) what is defined in the config file.
297 As of version 3.3, elilo is fully compliant with the EFI specification (1.10) with regards
298 to where the bootloader (elilo.efi) must be located in the EFI system partition. In
299 section 11.2.1.3 of the EFI1.10 specification, it is said that in order to avoid conflicts
300 between various loaders for various OSes or distributions of the same OS, every vendor MUST
301 use a dedicated directory: \EFI\vendor\. The bootloader must be placed in this directory.
302 This has always been possible as this is a matter of creating the directory and copying
303 the elilo.efi file in it. However up until version 3.3, elilo would look for its config file
304 and kernel/initrd in the root (/) of the partition it was loaded from. As of version 3.3,
305 elilo will now ONLY look for its configuration file FROM THE DIRECTORY IT WAS LOADED FROM.
306 The same applies to the kernel and initrd files unless absolute paths are specified. Let us
307 look at a simple example:
309 - suppose elilo.efi is in \EFI\DIST if fs0: (for the EFI Shell)
311 - if you invoke elilo as follows:
313 fs0:\> \efi\dist\elilo -v -p
314 default file path: \efi\dist\
315 config file : \efi\dist\elilo.conf
319 Note that this is the same if you invoke elilo directly from \efi or \efi\dist.
321 File references in the configuration file are treated as relative to the directory
322 elilo was loaded from except if they use an absolute path.
324 As of version 3.4 a similar rule applies to the network boot sequence, see netbooting.txt
330 Elilo can be forced into interactive mode using the "prompt" option in the config
331 file or with the -p option. In this mode, the user can select a kernel to load.
333 The interface depends on the chooser, it may be a simple command line prompt as provided
334 by the simple chooser or a more sophisticated screen with scroll menus as provided by
335 textmenu. Most choosers depends on the elilo config file to get the information they
336 display. The simple chooser can operated without the elilo config file. However it
337 is always better to have this file, to create handy logical names for each possible
338 boot choices. The logical names are specified with the "label" option in the config
339 file. They represent a specific kernel "image" and its specific options.
341 In elilo, the user can select a particular kernel image using the corresponding label
342 name. A simple example is as follows:
344 If we suppose that the following is defined in elilo.conf:
350 append="console=tty0 console=ttyS0,115200n8"
352 then the user can specify linux-up at the prompt and elilo will load the
353 vmlinuz-2.4.9 kernel file and the initrd-2.4.9 ramdisk and will pass
355 "root=/dev/sda2 console=tty0 console=ttyS0,115200n8"
357 as command line arguments to the kernel.
359 This behavior is identical to Lilo/x86. However, elilo further allows the user
360 to specify actual kernel files names as well, i.e., kernels that are not defined
361 in the configuration file. If we reuse the above example and the simple chooser,
364 ELILO boot: vmlinux-2.4.18 root=/dev/sda2
366 and elilo will boot the vmlinuz-2.4.18 kernel if it exists.
368 VI/ The alternate kernel image
369 --------------------------
371 Oftentimes when debugging kernels you want to reboot the machine once with
372 your test kernel and, if something goes wrong, you want to fall back to a more
373 stable kernel. In addition you want to be able to do this from a remote machine.
374 Many things can go wrong when doing kernel debugging. It could be that you don't
375 even reach user-mode. In this case however, you still want to fall back to
376 a stable kernel. The feature you'd like from a boot loader is 'boot once and
377 then fall back to safe kernel'.
379 Elilo offers this feature and it's called 'alternate kernel image'.
380 You can configure elilo to load a kernel only once and then whatever
381 happens the next reboot falls back to a different kernel hopefully more stable.
383 To do this, elilo relies on an EFI variable called 'EliloAlt' with a NULL GUID.
384 The content of this variable is a UNICODE string containing the kernel file name
385 and its command line options.
387 When the -a option is specified on the command line or if the "checkalt" option
388 is present in the config file, elilo will check for the presence of this variable.
389 If found and the content is a valid UNICODE string, elilo will use it as the kernel
390 to boot. There is no verification made on the validity of the kernel name or options.
391 Then the variable is deleted. If the variable is rejected because it does not look
392 sane, it is also deleted.
394 The variable can be set from a running Linux system using the /proc/efi/vars
395 interface. In the tools directory of this package, there is a Linux tool called
396 elilovar which can be used to create, modify, print, and delete the EliloAlt
397 variable. Refer to eliloalt.txt for more information on this tool.
399 VII/ Auto booting the machine
400 -----------------------
402 Once you're satisfied with your machine setup, it is good to install an
403 auto boot procedure. You have two options to do this:
404 - from the EFI boot manager menu
407 The first option is preferred and is used by most Linux distributions.
408 Elilo can be invoked directly from the boot manager. You need to get into
409 the 'boot maintenance' menu and use load file a file. This can be tedious
410 so instead it is recommended that you use a Linux tool called efibootmgr
411 which is also shipped in most distributions. With this tool, you can
412 create your own boot option and change the boot order.
416 The second approach use the EFI shell and a shell script with a special name: 'startup.nsh'.
418 When the system boots, it looks for EFI partitions and if it finds
419 a 'startup.nsh' file in ANY of these it will jumpstart execution from it.
421 So the typical way of auto booting your Linux/ia64 system is to simply create
422 such a file with the following content:
424 # cat /boot/startup.nsh
425 elilo vmlinuz root=/dev/sda2
427 Of course, this can be simplified if there is a configuration file.
433 Please refer to netbooting.txt for a complete description of how to boot
437 XII/ Booting on EFI/ia32 platforms
438 -----------------------------
440 Until PC comes with the EFI firmware built in, you need to boot from a
441 floppy that has the EFI firmware on it. Such floppy can be
442 constructed from the EFI sample implementation and toolkit that is
443 available from the Intel Developer Web site at:
445 http://developer.intel.com/technology/efi/
447 To use elilo on IA-32, you can put it on a floppy and
448 on a FAT32 partition (msdos partition). You can also
449 netbooting if you network adapter has support for UNDI/PXE.
451 Elilo/ia32 is capable of booting unmodified 2.2.x. and 2.4.x kernels
452 as they are shipped by distributors today (such as Redhat7.2). You don't need
453 to recompile the kernel with special options. Elilo ONLY takes compressed kernel
454 image which are typically obtained via a 'make bzImage'. Plain elf/32 kernel can't
455 be booted (plain vmlinux will not work). Similarly, existing initial ramdisks can
456 be used without modifications.
458 XIII/ Booting on EFI/x86_64 platforms
459 -----------------------------
461 To use elilo on x86_64, you can put it on a floppy and
462 on a FAT32 partition (msdos partition). You can also
463 netboot if your network adapter has support for UNDI/PXE.
465 Elilo/x86_64 requires efi64 enabled linux kernel (> 2.6.21).
466 You need to compile the kernel with CONFIG_EFI option.
467 x86_64 platforms with UEFI 2.0 firmware deprecate UGA protocol
468 and therefore only the Graphics Output Protocol (GOP) is supported. For
469 such platforms, the kernel must be configured with EFI_FB option. This
470 will enable early boot messages on the console. The elilo for x86_64
471 attempts to query the firmware for GOP and if it fails it defaults to
472 text mode. Elilo ONLY takes compressed kernel image which are
473 typically obtained via a 'make bzImage'. Plain elf/x86_64 kernel can't
474 be booted (plain vmlinux will not work). Similarly, existing initial
475 ramdisks can be used without modifications.
477 The x86_64 implementation converts the EFI memory map into E820 map and
478 passes it in the bootparameter supplied to the OS. For details on
479 bootparameter, see x86_64/sysdeps.h.
485 Stephane Eranian <eranian@hpl.hp.com>
486 David Mosberger <davidm@hpl.hp.com>
487 Johannes Erdfelt <jerdfelt@valinux.com>
488 Richard Hirst <rhirst@linuxcare.com>
489 Chris Ahna <christopher.j.ahna@intel.com>
490 Mike Johnston <michael.johnston@intel.com>
491 Fenghua Yu <fenghua.yu@intel.com>
492 Bibo Mao <bibo.mao@intel.com>
493 Chandramouli Narayanan <mouli@linux.intel.com>
498 You can submit bugs to <eranian@hpl.hp.com> or to the Linux/ia64
499 mailing list at linux-ia64@linuxia64.org. Visit http://www.linuxia64.org
500 to subscribe to this list.
505 UEFI 2.0 specifications are available from the following web site:
507 http://www.uefi.org/home
509 EFI v1.02 specifications are available from the following web site:
511 http://developer.intel.com/technology/efi/
513 The latest sources of ELILO can be downloaded at:
515 ftp://ftp.hpl.hp.com/pub/linux-ia64