Getting the Sources
===================

The L4Ka::Pistachio/ia64 loader is based on the FreeBSD boot loader
and uses a patchset relative to the FreeBSD source code.  To compile
the loader you will therefore need access to the FreeBSD source code.
You will also need a BSD compatible version of make (no, GNU make will
not work).  If you do not have access to the FreeBSD source code or do
not have a BSD compatible make utility, it is recommended that you
fetch precompiled loader binaries from:

    http://l4ka.org/projects/pistachio/ia64/

If you do want to build the loader binaries yourself you should have a
copy of the FreeBSD 5 source code somewhere in your filesystem.  A
source code snapshot from Apr 28, 2003 is known to work, but newer or
older versions should also function without any problems (there
usually are not many updates to the bootloader).  Refer to
http://www.freebsd.org/ for instructions on how to obtain the source
code.


Building and Installing
=======================

Type `make' in the main bootloader directory (the same directory as
this INSTALL file) to create the bootloader binaries.  The make
process takes the following command line options:

   SRCDIR=...		[default `/usr/src']
	The SRCDIR setting specifies where in the filesystem the
	FreeBSD source code is located.

   ROOTDIR=...		[default `/tftpboot/ia64']
	The ROOTDIR setting specifies where the bootloader binaries
	and loader scripts are to be installed.

Type `make install' to install the compiled binaries.


Using the Loader
================

The install process will install two bootloaders:
`ROOTDIR/boot/efiloader' and `ROOTDIR/boot/skiloader'.  The former is
used for booting on EFI capable hardware (i.e., regular IA-64
hardware).  The latter is used for booting on the HP IA-64 Ski
simulator.

If real hardware is used, the `efiloader' can either be located on an
EFI partition of a local disk or on a TFTP accessible directory in the
network.  The EFI firmware can then be used to choose the right boot
medium.  If you choose to boot over the network you must configure
your local DHCP server to hand out the appropriate location of the
`efiloader' (boot server and boot filename).  For example, if your
bootloader is located on `myserver:/tftpboot/ia64/boot/efiloader'
(where `myserver' has IP address `10.0.0.10'), you must configure the
boot server to `10.0.0.10' and the boot file name to
`/tftpboot/ia64/boot/efiloader' (or `/ia64/boot/efiloader' depending
on how the TFTP daemon on `myserver' is configured).

Also note that the EFI firmware requires that the TFTP daemon supports
RFC2349---negotiation of timeouts and file sizes.  Booting will fail
if the TFTP daemon does not support this.

In order for the L4Ka::Pistachio bootloader to load the kernel and
other binaries, these must be made accessible to the IA-64 machine as
an NFS exported file system.  For the example above, `myserver' would
have to export the `/tftpboot/ia64' directory to the IA-64 machine.
Only read-only access is required for loading the binaries.  Moreover,
the DHCP server should hand out the root directory for the IA-64
machine (`/tftpboot/ia64' in out example).

Once everything is set up correctly the L4Ka::Pistachio/ia64
bootloader will display a simple boot menu.  More advanced bootloader
features are explained below.

Booting on the HP Ski Simulator requires considerably less
infrastructure than real hardware.  Simply cd into the root directory
(e.g., `/tftpboot/ia64') and run `ski boot/skiloader' or `xski
boot/skiloader'.  Once started, a console window will display the boot
menu.


Advanced Usage
==============

The bootloader interface is almost identical to the one used in
FreeBSD.  For a full description of the bootloader use the `help'
command or refer to the loader(8) manual page of FreeBSD.

The only difference between the L4Ka::Pistachio and FreeBSD bootloader
interface is the `load' command.  For L4Ka::Pistachio the `load'
command can be used to load more than a single executable into memory.
Similar to the FreeBSD loader, the first executable loaded will be the
kernel.  In contrast to the FreeBSD loader, however, rather than
preventing multiple executables to be loaded, the L4Ka::Pistachio
loader will simply load and relocate the executables.

The `load' command also supports an extra `-p <type>' switch.  The
<type> argument specifies the type of the executable and can be one of
`s0', `s1', or `rs' for sigma0, sigma1 and root-server respectively.
It is necessary to provide the `-p' switch to the privileged servers
on boot time, or else the kernel will not initialize the servers after
startup.


Boot Menus
==========

You can customize your own boot menu or boot environment using Forth
scripts.  At startup, the bootloader interprets the `boot/boot.4th'
file.  This file can be changed to your needs.  The current example
scripts implements a boot menu that can be used to start the
`pingpong' application.