refit for Debian
----------------

Installation
------------

EFI files are available in /usr/lib/refit/; copy the refit and tools
subdirectories somewhere accessible from Mac OS X, boot into Mac OS X, then:
 - install the files in a directory named "efi" at the root of a FAT or
   HFS+ partition
 - 'bless' refit.efi (see man bless on Mac OS X)

The first partition of your disk is a ca. 200 MB FAT partition that is used
by the EFI ROM. It's usually empty, and is a good place to install refit.

To 'bless' rEFIt, cd to the directory where refit.efi is located, and run
 $ sudo bless --folder "$PWD" --file "$PWD/refit.efi" --labelfile "$PWD/refit.vollabel" --setBoot
You may need to use the --mount option to bless; see man bless for details.


32bit vs. 64bit EFI binaries and fat EFI binaries
-------------------------------------------------

Intel Macs can use 32bit or 64bit binaries; it depends on the exact model of machine
you have.

Any machine equipped with a Santa Rosa CPU or later uses a 64bit EFI firmware
and thus uses 64bit EFI binaries (x64 in EFI terminology).

Any machine before that uses a 32bit EFI firmware and thus uses 32bit (ia32)
EFI binaries.

When installing an EFI application, you need to install the appropriate binary
depending on your machine, unless that application is shipped as a fat EFI
binary.

Fat EFI binaries are a way to overcome this problem. The binaries contain both
ia32 code and x64 code and the firmware picks up the appropriate code when
loading the binaries.

Everything under /usr/lib/refit/refit and /usr/lib/refit/tools is a fat
binary; binaries under /usr/lib/refit/ia32 and /usr/lib/refit/x64 are
respectively ia32 binaries and x64 binaries.

rEFIt (and tools) is currently the only EFI application in Debian shipped
as a fat EFI binary.

There's a doubt as to whether fat EFI binaries are supported by non Apple
machines, so this situation will probably remain.


Building a bootable rEFIt CD/DVD
--------------------------------

Creating a bootable EFI CD/DVD with rEFIt is quite easy. Start by creating a
directory that will hold the files needed for the bootable image:

 $ mkdir bootimg

Create an EFI directory:

 $ mkdir bootimg/efi

Copy the rEFIt files:

 $ cp -a /usr/lib/refit/* bootimg/efi

Now we rename, move around and remove some files:

 $ mv bootimg/efi/refit bootimg/efi/boot
 $ rm bootimg/efi/boot/refit.efi
 $ mv bootimg/efi/ia32/refit.efi bootimg/efi/boot/bootia32.efi
 $ rmdir bootimg/efi/ia32
 $ mv bootimg/efi/x64/refit.efi bootimg/efi/boot/bootx64.efi
 $ rmdir bootimg/efi/x64

The efi/boot directory layout is mandated by the EFI spec. The bootia32.efi
and bootx64.efi are respectively ia32 and x64 binaries that the EFI firmware
will run. We first delete refit.efi because that binary is a fat EFI binary,
and here we need to separate binaries. If you only need to boot a ia32 machine,
you can leave out the bootx64.efi file, and vice versa.

At that point, you can add to the image whatever utilities you want to have
on the boot image. You can also add a rescue system, that is a linux kernel,
an initrd and elilo.efi together with its configuration file. Pay attention
to the architecture of the elilo.efi binary.

To make the actual boot image, first determine its size:

 $ du -sk bootimg

Round up the number to make some room for the metadata (5% will do) and make
it a multiple of 16 ($size / 16 * 16), then create an msdos filesystem image
using this number for the count= parameter:

 $ dd if=/dev/zero of=boot.img bs=1k count=1024

Format the image:

 $ mkfs.msdos -n "rEFItbootCD" boot.img

And copy the files into the image:

 $ mcopy -iboot.img -s bootimg/efi ::/

Finally, build a bootable CD/DVD image:

 $ mkdir -p cdimg/boot
 $ cp boot.img cdimg/boot
 $ genisoimage -J -iso-level 3 -r -R -o rEFItCD.iso -b boot/boot.img \
   -c boot/boot.cat -V rEFItBootCD -no-emul-boot ./cdimg

 (on the CD image, /boot can be an arbitrary location, and boot.{img,cat} can
 be arbritrary names -- adapt the genisoimage command line to suit your needs)

Burn the resulting rEFItCD.iso to a CD or DVD. When mounting the CD, you
should see 2 files on it, boot/boot.img and boot/boot.cat.


Reboot the machine with the CD in the drive; hold down the Alt (Option)
key when the machine starts, until the Apple Chooser shows up. You'll see
hard drives icons and 2 CD icons: one labelled "Windows" and one labelled
"EFI Boot".

Use the CD icon labelled "EFI boot" to boot on the CD, and rEFIt will start.
Do not use the other CD icon; it's a legacy boot entry and it won't boot.


Differences from upstream
-------------------------

rEFIt in Debian is built against gnu-efi. As gnu-efi doesn't support EFI 1.10,
a number of rEFIt features have been taken out. Though rEFIt remains usable
and able to boot the machine, those features are not available:
 - loading EFI drivers (ext2/ext3, reiserfs, ...)
 - machine shutdown


EFI shell and tools
-------------------

The EFI shell and tools distributed with the binary distribution of rEFIt come
from the TianoCore (Intel) EFI Toolkit. A large part of the EFI Toolkit
codebase is licensed under the 4-clause BSD license, which incompatible with
the GPL, making it impossible to build the tools against gnu-efi.

 -- Julien BLACHE <jblache@debian.org>, Fri, 30 May 2008 20:10:32 +0200
