\documentclass[a4paper,titlepage,11pt]{article}


% Font style abstractions

\newcommand{\file}[1]{\texttt{#1}}
\newcommand{\key}[1]{\framebox{\texttt{#1}}}
\newcommand{\name}[1]{\emph{#1}}
\newcommand{\src}[1]{\texttt{#1}}
\newcommand{\val}[1]{\texttt{#1}}
\newcommand{\var}[1]{\emph{#1}}
\newcommand{\email}[1]{\texttt{#1}}
\newcommand{\url}[1]{\texttt{#1}}


% Abbreviations

\newcommand{\lilo}{\name{Lilo}}
\newcommand{\amililo}{\name{Amiga Linux/m68k Loader}}
\newcommand{\linux}{\name{Linux/m68k}}
\newcommand{\linuxgen}{\name{Linux}}
\newcommand{\linuxintel}{\name{Linux/i386}}
\newcommand{\amiga}{\name{Amiga}}
\newcommand{\amigaos}{\name{AmigaOS}}
\newcommand{\amiboot}{\name{Amiboot}}
\newcommand{\hdtoolbox}{\name{HdToolBox}}
\newcommand{\rdb}{\name{Rigid Disk Block}}
\newcommand{\kickstart}{\name{Kick\-start}}
\newcommand{\exttwo}{\name{ext2fs}}
\newcommand{\affs}{\name{affs}}
\newcommand{\minix}{\name{minix}}

\newcommand{\os}{operating system}


% Hyphenation rules

\hyphenation{Dos-Ty-pes}


\begin{document}

% -----------------------------------------------------------------------------


\title{Amiga Linux/m68k Loader \\ \vskip 2mm \large Version 1.0}
\author{Geert Uytterhoeven}
\date{\today}
\maketitle
\tableofcontents
\newpage


% -----------------------------------------------------------------------------


\section{Introduction}

The \amililo\ (short: \lilo) allows you to load
\linux\ from a disk boot block. You can choose among multiple kernel
images --- without having to transport those kernels from a \linux\
partition to an \amigaos\ partition --- and can boot even \amigaos\
itself. This greatly eases the boot process for normal users and provides a
development boost for kernel hackers.


\subsection{Features}

\begin{itemize}
\item Can boot \linux\ and \amigaos.
\item Supports multiple kernel images.
\item Supports both \name{ELF} and \name{a.out} (\name{QMAGIC} and
\name{ZMAGIC}) kernels.
\item Supports multiple command lines.
\item Supports the standard \amiga\ console and an \name{ANSI} terminal
connected to the builtin serial port.
\item Supports automatic and interactive booting, with an optional timeout.
\item Supports ramdisk images.
\item Boot code can be installed on \amigaos\ and \linux\ partitions.
\item Password protection on a per kernel base.
\item Boot monitor with a separate password.
\item Can backup and restore boot blocks.
\end{itemize}


\subsection{System requirements}

\begin{itemize}
\item An \amiga\ that can run \linux.
\item A working installation of \linux\ \name{2.0.x}.
\item \kickstart\ \name{V36} or higher.
\item \hdtoolbox.
\end{itemize}


\subsection{Why \lilo\ for \amiga?}

I decided to write a version of \lilo\ for the \amiga\ because I was
tired of putting \linux\ kernels on a floppy and read them back with
the \name{FLAT-handler} to test them. At that time this was the only decent way
to transport files from a \linux\ partition to an \amigaos\
partition, since you can't access files on an \exttwo\ partition under
\amigaos\footnote{However, this is going to change. For more information,
take a look at
\url{http://theory.{\linebreak}cs.bonn.edu/{\footnotesize$\sim$}fasten/}.}.

Now we have \name{Ethernet} support file transport became much easier --- I
usually \name{FTP} my files to a \name{Sun SPARCstation 1} or \linuxintel
box, and get them back through \name{AmiTCP/IP} ---, but it's still a real
hassle just to test a new kernel. And what with people who want to wipe
\amigaos\ completely off of their hard disk? But here is \lilo!

The support for a terminal connected to the builtin serial port
was added when my \name{A1960} monitor died (again) and I desperately needed
such a feature.


% -----------------------------------------------------------------------------


\section{Installing \lilo}

\textbf{Important notes:}
\begin{itemize}
\item To perform the actions described below, you must be \name{root} on your
\linux\ system, unless noted otherwise.

\item Some of these actions might be dangerous for the integrity of your
system.  Always think twice, \ldots then think again, and \textbf{use this at
your own risk!}
\end{itemize}

First you need to choose a partition to install the \lilo\ boot block on.
This can be any \linux\ partition or \emph{bootable} \amigaos\
partition. If you want to use \lilo\ to boot \amigaos\ too, you must
install the \lilo\ boot block on the \amigaos\ partition you want to
boot from.

This boot partition is represented by a block special device file (created with
\name{mknod}), which is usually located in the \file{/dev} directory. By
convention block special device files for \name{SCSI} drives are represented by
entries of the kind \file{/dev/sd*}, while \name{IDE} drives are associated
with the \file{/dev/hd*} entries.

I have e.g.\ 2 \name{IDE} drives in my \name{A4000/040}: a \name{Conner
CP30544} (master) of 540 MB and the original \name{Seagate ST3144A} (slave) of
130 MB\footnote{This changed due to my (\linux's? \name{X11R6.1}'s?)
hunger for diskspace, but I left the original example for the sake of
simplicity.}.  The \name{Conner} has six partitions, while the \name{Seagate}
has only one partition.  So I have the following block special device files:
\begin{center} \begin{tabular}{|c|l|l|l|}
\hline
Unit & Block special device file & File system & Usage \\
\hline \hline
0 & \file{/dev/hda}  & ---     & Whole disk \\
\cline{2-4}
  & \file{/dev/hda1} & \affs   & \amigaos\ \file{WB\_3.x:} \\
  & \file{/dev/hda2} & \affs   & \amigaos\ \file{App:} \\
  & \file{/dev/hda3} & \exttwo & \linux\ \file{/} \\
  & \file{/dev/hda4} & \exttwo & \linux\ \file{/var} \\
  & \file{/dev/hda5} & \exttwo & \linux\ \file{/usr} \\
  & \file{/dev/hda6} & ---     & \amigaos(\name{VMM}) Swap \\
  &                  &         & \linux\ Swap \\
\hline \hline
1 & \file{/dev/hdb}  & ---     & Whole disk \\
\cline{2-4}
  & \file{/dev/hdb1} & \affs   & \amigaos\ \file{Backup:} \\
\hline
\end{tabular} \end{center}

Since I wanted to use \lilo\ to boot both \amigaos\ (from
\file{/dev/hda1}) and \linux\ (from \file{/dev/hda3}), I had to
install \lilo\ on \file{/dev/hda1}.


\subsection{Installing the \lilo\ boot block}

Now edit the file \file{/etc/lilo.conf}. Refer to Section~\ref{sec:conf} for
the configuration file syntax.

Then install the \lilo\ boot block with the following command line:
\begin{quote}
\val{lilo [--force]}
\end{quote}
with
\begin{description}
\item[\val{--force}] To prevent data loss in case of a mistake, \lilo\ will
never overwrite an unknown boot block, unless you use this force option.
\end{description}

If there exists no backup of the boot block yet --- i.e.\ if you're installing
\lilo\ for the first time --- it will automatically create a backup of the
old boot block in the file \file{/boot/backup.xx.yy} with \val{xx} and
\val{yy} the major and minor numbers of the device you installed the
boot block on. This will allow you to uninstall \lilo\ completely or
to recover from mistakes.

In most cases you can just enter
\begin{quote}
\val{lilo}
\end{quote}
or
\begin{quote}
\val{lilo --force}
\end{quote}
if you're installing a \lilo\ boot block on a partition with an
\exttwo\ or \minix\ file system for the first time because those
partitions don't have a known boot block at that moment.

\textbf{Warning: Every time you change or move any kernel image or config file
you \emph{must} rerun \file{lilo}}!  Just enter
\begin{quote}
\val{lilo}
\end{quote}
to update all important data.


\subsection{Updating the \rdb}

If this is the first time you install \lilo\ you need to use
\hdtoolbox\ (under \amigaos) to update the \rdb\ of
the device your boot partition is located on. Make sure to remember the
original values of all options you change, in case you might want to uninstall
\lilo!

Start \hdtoolbox\ and perform the following actions\footnote{This list
reflects the \amigaos\ 3.1 version of \hdtoolbox. Other versions are
slightly different.}:
\begin{itemize}
\item Select the corresponding device for your boot partition and click on
\val{Partition Drive} to get the \val{Partitioning} menu.

\item Choose the partition and enable \val{Advanced Options}.

\item If the partition isn't already bootable, make it bootable by enabling
\val{Bootable}. You may want to change the \val{Boot Priority} too.

\item Click on \val{Change...} to get the \val{File System Characteristics}
menu.

\item If you did \emph{not} install the \lilo\ boot block on an
\amigaos\ partition:
\begin{itemize}
\item Set \val{File System} to \val{Custom File System}.

\item Fill in an appropriate value after \val{Identifier =}.  I suggest
\linebreak \val{0x45585432} (\val{EXT2} in \name{HEX ASCII}) for a partition
with \exttwo\ and \val{0x4D494E49} (\val{MINI} in \name{HEX ASCII}) for a
partition with the \minix\ file system.  Alternatively you could use
\val{0x554E4901} (\val{UNI$\backslash$01}\footnote{This value was originally
reserved for a \name{UNIX} boot file system, i.e.\ for the boot partition of
\name{Amiga UNIX System V Release 4}, also known as \name{AMIX}.} in \name{HEX
ASCII}) if you do not intend to access the partition under \amigaos.

\item Don't worry about the warning you will get later that tells you the data
on the partition will be lost. \hdtoolbox\ doesn't know that \exttwo
and the \minix\ file system don't use the \val{File System} field in the
\rdb.
\end{itemize}

\item Enable \val{Use custom boot code}\footnote{\emph{Never} enable this for
an \amigaos\ partition that contains the \emph{original} \amigaos\ boot
block, since this is definitely not bootable!} and set \val{Number of custom
boot \linebreak blocks} to \val{2}.  This value assumes the \val{File system
block size} is set to it's default value of \val{512}.

\item Click on \val{OK}, on \val{OK} and on \val{Save Changes to Drive}.
\end{itemize}

If you installed the \lilo\ boot block on another partition than the
previous time, you also need to use \hdtoolbox\ to update your \rdb.


\subsection{Uninstalling \lilo}

To uninstall a \lilo\ boot block, just restore the \rdb\
options for that partition to their original values (using \hdtoolbox),
and use the \val{--uninstall} option of \lilo:
\begin{quote}
\val{lilo --uninstall}
\end{quote}
This will automatically restore the boot block that was backed up during the
first time installation.


% -----------------------------------------------------------------------------


\section{Files used by \lilo}

\subsection{\file{/boot/loader}}

This is a template for an \amigaos\ executable that displays the boot menu
and loads the desired \os\ on booting.

\subsection{\file{/boot/loader.patched}}

This is the actual raw PC-relative executable that displays the boot
menu and loads the desired \os\ on booting. It is created by
\lilo\ by patching \file{/boot/loader} and by adding a PC-relative
header that decodes the \amigaos\ executable file format.

\subsection{\file{/boot/map}}

This file contains all configuration options and all necessary information to
find all files, as defined by \file{/etc/lilo.conf}. It is created by
\lilo.

For more information about the used file format, see section~\ref{sec:tags}.

\subsection{\file{/boot/backup.xx.yy}}

This file contains a backup of the original boot block on the device with major
number \val{xx} and minor number \val{yy}. It's created by \lilo\ if you
install a boot block on the corresponding device and no backup exists yet.

\subsection{\file{/sbin/lilo}}

This is the \linux\ executable that installs \lilo.


\subsection{\file{/etc/lilo.conf}}
\label{sec:conf}

This is the \lilo\ configuration file, an \name{ASCII} file which defines
the boot configuration for \lilo.  It contains a header with global
options, one or more boot records, and zero or more file definitions.

The character \val{\#} indicates that the rest of the line is a comment and thus to be ignored. All numbers in this file can be entered in decimal (e.g.\
\val{53270}), hexadecimal (e.g.\ \val{0xD016}) or octal (e.g.\ \val{0150026})
form\footnote{Nostalgy magic: Do you recognize this number? It's the magic
address for the side border trick on the \name{Commodore 64}.}.


\subsubsection{Header}

The header looks like
\begin{quote}
\val{header} \\
\rule{1em}{0mm} \var{options} \\
\rule{1em}{0mm} \ldots \\
\val{endheader}
\end{quote}

Valid header options are:
\begin{description}
\item[\val{bootdev "}\var{name}\val{"}] Specify the block special device to
install the boot block on (e.g.\ \val{/dev/hda1}).

\item[\val{altdev "}\var{device}\val{"} \var{unit}] Specify the \amigaos\ name
and unit number for an alternate boot device (e.g.\ \val{scsi.device} and
\val{0}).

In most cases you don't need this option, but if the device that contains your
kernel images and the files \file{/boot/loader.patched} and \file{/boot/map} is
different from the device you want to install the boot block on (specified with
the \val{bootdev} option), you need to specify the \amigaos\ device name and
unit number that corresponds with the device those files reside on.

\item[\val{default "}\var{label}\val{"}] Specify that the boot record with
label \var{label} is the default boot \os. Default is the first boot record.

\item[\val{auto} \var{flag}] If \var{flag} is \val{true}, \lilo\ will
automatically boot the default \os, unless you hold a qualifier (\key{ALT},
\key{AMIGA}, \key{CTRL}, \key{SHIFT}, \key{CAPS LOCK} or one of the
mouse-buttons) or press a key on the auxiliary console during booting.
If \var{flag} is \val{false}, a boot prompt will always appear.
So use \val{true} if you think `Why do I need a boot menu? I already have one
in ROM!'.  Default is \val{false}.

\item[\val{timeout} \var{number}] Specify the number of seconds to wait at the
boot prompt before the default \os\ is chosen automatically. Use \val{0} for an
infinite timeout value. Default is \val{20}.

\item[\val{aux} \var{flag}] If \var{flag} is \val{true}, the loader will not
only use the standard console, but also the auxiliary console (a terminal on
the builtin serial port). Default is \val{false}.

\item[\val{baud} \var{number}] Specify the speed (in bps --- bits per second)
for the auxiliary console (if enabled). Default is \val{9600} (\name{ROM}
default).

\item[\val{password "}\var{name}\val{"}] Specify the master password.  This
password will be asked for if you want to enter the boot monitor on booting.
Default is an empty string.

\item[\val{debug} \var{flag}] If \var{flag} is \val{true} the loader will enter
debug mode and display additional information during startup. Default is
\val{false}.

\item[\val{prompt "}\var{text}\val{"}] Specify the loader prompt. The following
character sequences are interpreted specially:
\begin{center} \begin{tabular}{|l|l|}
\hline
Sequence                     & Interpretation \\
\hline \hline
\val{$\backslash$b}          & \name{Backspace} \\
\val{$\backslash$e}          & \name{Escape} \\
\val{$\backslash$n}          & \name{Line Feed} \\
\val{$\backslash$r}          & \name{Carriage Return} \\
\val{$\backslash$t}          & \name{Tab} \\
\val{$\backslash\backslash$} & \val{$\backslash$} \\
\hline
\end{tabular} \end{center}
The default prompt is `\val{Boot image: }'.

\item[\val{kickrange} \var{min} \var{max}] If the current \kickstart\
version lies outside the range \var{min}--\var{max}, \lilo\ will always
boot \amigaos\ in case of a non-interactive boot. Use this if you have
strange hardware that doesn't allow you to boot \linux\ from the
`wrong' \kickstart\ version. The default range is 0--65535, so all \kickstart\
versions will be accepted.
\end{description}


\subsubsection{Boot records}

The boot records define one or more {\os}s you can select at
boot time. Make sure all your kernel images and the files \file{/boot/map},
\file{/boot/loader.patched} are located on the same physical device.

A boot record is defined by
\begin{quote}
\val{bootrec "}\var{label}\val{"} \\
\rule{1em}{0mm} \var{options} \\
\rule{1em}{0mm} \ldots \\
\val{endrec}
\end{quote}
with \var{label} the label of the boot record.

Valid boot record options are:
\begin{description}
\item[\val{alias "}\var{label}\val{"}] Specify an alias name for this boot
record.
\item[\val{type "}\var{name}\val{"}] Specify the \os\ type for this boot
record. Valid types are:
\begin{description}
\item[\val{linux}] \linux. This is the default.
\item[\val{amiga}] \amigaos. This only works if you install the \lilo\ boot
block on a valid \amigaos\ boot partition.
\item[\val{netbsd}] \name{NetBSD-Amiga}. This doesn't work yet~:-)
\end{description}

\item[\val{image "}\var{name}\val{"}] Specify the full qualified file
name of the kernel image for this boot record. This file needs not to
exist (except for the default boot record) --- this is useful for testing
purposes ---, but if it exists, it must be located on the \val{bootdev} device,
or on the \val{altdev} device, if the \val{altdev} option is specified. This
option must not be used if \val{type} is set to \val{amiga}.

\item[\val{args "}\var{name}\val{"}] Specify the kernel command line for this
boot record. This option must not be used if \val{type} is set to \val{amiga}.
Default is an empty string.

\item[\val{password "}\var{name}\val{"}] If this option is defined, \var{name}
is the password for this boot record.  It must be supplied if you want to boot
from this record.  Default is no password.

\item[\val{chipram} \var{size}] Override the detected \name{Chip RAM} size and
set it to \var{number} bytes.

\item[\val{fastram} \var{address} \var{size}] Override the detected adresses
and sizes of \name{Fast RAM} chunks. Each entry defines a \name{Fast RAM} chunk
at adress \var{address} containing \var{size} bytes, thus you can specify
multiple \name{Fast RAM} chunks.

\item[\val{model} \var{type}] Override the detected \amiga\ model.
\var{type} can be any of
\begin{center} \begin{tabular}{lllll}
\val{A500}   & \val{A500+}  & \val{A600}   & \val{A1000}  & \val{A1200}  \\
\val{A2000}  & \val{A2500}  & \val{A3000}  & \val{A3000T} & \val{A3000+} \\
\val{A4000}  & \val{A4000T} & \val{CDTV}   & \val{CD32}   & \val{Draco}  \\
\end{tabular} \end{center}
or a number corresponding to one of the model definitions in
\file{<asm/{\linebreak}amigatypes.h>}.

\item[\val{ramdisk "}\var{name}\val{"}] Specify the full qualified file name of
a file containing a file system to be used a a ramdisk. This file needs
not to exist but if it exists, it must be located on the \val{bootdev} device,
or on the \val{altdev} device, if the \val{altdev} option is specified. This
option must not be used if \val{type} is set to \val{amiga}. Default is an
empty string.
\end{description}


\subsubsection{File definitions}

The file definitions allow you to specify some addional files to be added to
the map file. These files can then be referenced from withing the boot monitor.
Make sure all these files are located on the same physical device as the kernel
images.

A file definition looks like
\begin{quote}
\val{file "}\var{name}\val{"}
\end{quote}
with \var{name} the full qualified file name of the file.


\subsubsection{Sample configuration file}

This example assumes:
\begin{itemize}
\item \file{/dev/hda1} is your main \amigaos\ partition,
\item \file{/dev/hdb1} is your main \linux\ partition,
\item \file{/boot/*}, \file{/vmlinux} and \file{/usr/src/linux/vmlinux} reside
on \file{/dev/{\linebreak}hdb?},
\item \file{/dev/hdb} under \linux\ is equivalent to \val{scsi.device} unit
\val{1} under \amigaos.
\end{itemize}

Note that in this case the \val{altdev} option is used because \file{/dev/hda}
and \file{/dev/hdb} are two different physical devices.


\begin{small} \begin{verbatim}
#
#   Amiga Linux/m68k Loader
#
#   Sample Configuration File
#

header
    bootdev "/dev/hda1"
    altdev "scsi.device" 1
    default "linux"
    auto false
    timeout 20
    aux false
    baud 9600
    password "amiga"
    debug false
endheader

bootrec "amiga"
    type amiga
endrec

bootrec "linux"
    type linux
    image "/vmlinux"
    args "ro root=/dev/hdb1"
endrec

bootrec "single"
    image "/vmlinux";
    args "ro single root=/dev/hdb1"
    password "single"
endrec

bootrec "test1"
    image "/usr/src/linux/vmlinux"
endrec

bootrec "test2"
    image "/usr/src/linux/vmlinux"
    args "ro root=/dev/hdb1"
endrec
\end{verbatim} \end{small}


% -----------------------------------------------------------------------------


\section{Command line options}

\file{/sbin/lilo} is used to install a \linux\ boot block loader on a
boot partition. It can also be used to save boot blocks to a file or restore
boot blocks from a file.

\begin{quote}
\val{lilo} \val{[}\var{options \ldots}\val{]}
\end{quote}

Valid options are:
\begin{description}
\item[\val{--help}] Display the usage information.
\item[\val{--verbose}] Enable verbose mode.
\item[\val{--force}] Force installation on a partition with an unknown boot
block.
\item[\val{--backup}] Force a boot block backup on installation, even if a
backup already exists.
\item[\val{--uninstall}] Uninstall \lilo\ by restoring the backed up boot
block.
\item[\val{--root} \var{prefix}] Specify the prefix to be used for all path
names. This is useful when creating boot floppies, or for debugging.
\item[\val{--restore-from} \var{file}] Restore the boot block from \var{file}.
\item[\val{--save-to} \var{file}] Save the boot block to \var{file} first.
\item[\val{--device} \var{device}] Override the block special device that's
specified in \linebreak \file{/etc/lilo.conf}.
\item[\val{--dostype} \var{id}] Specify the \name{DosType} for the boot
block. Valid \name{DosTypes} are:
\begin{center} \begin{tabular}{|l|l||l|c|}
\hline
ID & Usage & ID & Usage \\
\hline \hline
\val{BOOU} & Generic boot disk              &
\val{muFS} & \name{MultiUser FFS INTL} disk \\
\val{DOS0} & \name{OFS} disk                &
\val{muF0} & \name{MultiUser OFS} disk      \\
\val{DOS1} & \name{FFS} disk                &
\val{muF1} & \name{MultiUser FFS} disk      \\
\val{DOS2} & \name{OFS INTL} disk           &
\val{muF2} & \name{MultiUser OFS INTL} disk \\
\val{DOS3} & \name{FFS INTL} disk           &
\val{muF3} & \name{MultiUser FFS INTL} disk \\
\val{DOS4} & \name{OFS DC} disk             &
\val{muF4} & \name{MultiUser OFS DC} disk   \\
\val{DOS5} & \name{FFS DC} disk             &
\val{muF5} & \name{MultiUser FFS DC} disk   \\
\hline
\end{tabular} \end{center}
Default is the original \name{DosType} of the partition, or \val{BOOU} for
partitions with an unknown boot block (if \val{--force} is specified too).
\item[\val{--checksum}] Fix the boot block checksum.
\item[\val{--version}] Display version information.
\end{description}

All options also have a short form:
\begin{center} \begin{tabular}{|l|l||l|l|}
\hline
Short & Long & Short & Long \\
\hline \hline
\val{-h} & \val{--help} &
\val{-r} & \val{--restore-from} \\
\val{-v} & \val{--verbose} &
\val{-s} & \val{--save-to} \\
\val{-f} & \val{--force} &
\val{-d} & \val{--device} \\
\val{-b} & \val{--backup} &
\val{-t} & \val{--dostype} \\
\val{-u} & \val{--uninstall} &
\val{-c} & \val{--checksum} \\
\val{-w\footnotemark} & \val{--root} &
\val{-V} & \val{--version} \\
\hline
\end{tabular} \end{center}
\footnotetext{People who understand Dutch or German will probably easily
remember that \val{-w} is short for \val{--root}.}


% -----------------------------------------------------------------------------


\section{The \lilo\ boot prompt}

If \lilo\ is configured not to boot automatically, or if you do one of the
following things during boot time:
\begin{itemize}
\item hold \key{ALT}, \key{AMIGA}, \key{CTRL}, \key{SHIFT} or \key{CAPS LOCK},
\item hold one of the mouse-buttons,
\item press a key on the terminal connected to the builtin serial
port if the auxiliary console is enabled,
\end{itemize}
a boot prompt will appear on the \amiga\ console and, if enabled, on the
terminal too.


\subsection{Normal user prompt}

You can perform the following actions:
\begin{itemize}
\item Hit \key{ENTER} to boot the default \os.

\item Enter \val{?} or \val{help}, or press \key{TAB} to get a list of valid
commands and boot record labels.

\item Enter the label of a boot record to boot the corresponding \os. If
this record has a password attached to it, the loader will prompt
for it first and will boot from this record only if you enter the correct
password.

\item Enter \val{su} to enter the boot monitor.  The loader will prompt for the
master password first and will enter the boot monitor only if you enter the
correct password.

\item Sit and wait: after the specified timeout the loader will boot the
default \os\ automatically.
\end{itemize}


\subsection{The boot monitor}

Once you're in the boot monitor, the timeout is disabled and you have advanced
control over the booting process.

You can enter one of the following commands:
\begin{description}
\item[\val{help} or \val{?}] Display usage information.
\item[\val{version}] Display the version information.
\item[\val{list records} or \val{list files}] List all available boot records
and/or files.
\item[\val{boot} \var{label}] Boot from boot record \var{label}. If \var{label}
is omitted, the current boot settings are used.
\item[\val{use} \var{label}] Copy the boot record \var{label} to the current
boot settings. If \var{label} is omitted, the default boot record is assumed.
\item[\val{info} \var{label}] Get information about the boot record
\var{label}.  If \var{label} is omitted, information about the current boot
settings is dumped.
\item[\val{set} \var{var} \var{values} \ldots] Change a variable for the
current boot settings. If \var{var} is omitted, this command is equivalent to
\val{list}. If no values are specified, the behavior depends on the variable
but tries to be intuitive. The following variables can be changed:
\begin{description}
\item[\val{type}] The \os\ type.
\item[\val{kernel}] The full qualified file name of the kernel image. This file
\emph{must} be available. Use the \val{file} option in the configuration file
to add your own files.
\item[\val{ramdisk}] The full qualified file name of the ramdisk image.  This
file \emph{must} be available.  Use the \val{file} option in the configuration
file to add your own files.
\item[\val{args}] The kernel command line.
\item[\val{debug}] The debug flag: \val{true} or \val{false}.
\item[\val{model}] The \amiga\ model. Default is \val{auto}, i.e.\
autodetect.
\item[\val{chip}] The amount of \name{Chip RAM}. Default is \val{auto}, i.e.\
autodetect.
\item[\val{nummem}] The number of \name{Fast RAM} chunks. Default is
\val{auto}, i.e.\ autodetect.
\item[\val{mem}] The address and size of a \name{Fast RAM} chunk. The value
syntax is \var{number address size}, with \var{number} the number
(1--\val{nummem}) of the memory chunk.
\end{description}
\end{description}

Commands are case insensitive, and can be abbreviated.


% -----------------------------------------------------------------------------


\section{Miscellaneous}

\subsection{Implicit kernel command line options}

\lilo\ automatically adds the following options to the kernel command line:
\begin{description}
\item[\val{BOOT\_IMAGE=}\var{label}] \var{label} is the label of the boot
record that's used for booting.
\item[\val{auto}] This is added only in case of an automatic boot, i.e.\ in one
of the following cases:
\begin{itemize}
\item No boot prompt appeared.
\item You choose the default \os\ by just hitting \key{ENTER}.
\item The timeout was reached.
\end{itemize}
\end{description}

Of course you can override this when you're in the boot monitor.


\subsection{Keeping \lilo\ up-to-date}

\lilo\ now uses the same bootstrap code as \amiboot\ to ease code
maintenance.  This also means that all you have to do to keep pace with the
newest bootstrap code is to recompile \lilo\ on every \amiboot\
update.


\subsection{Creating boot floppies}

If you want to create a boot floppy with a \lilo\ boot block, use the
\val{--root} option to tell \lilo\ to use the file system on the floppy instead
of your normal root file system, e.g.\
\begin{quote}
\val{lilo --root /floppy}
\end{quote}
assuming you have mounted the floppy file system on \file{/floppy}.

After running \lilo, you may want to remove the following files from the floppy
file system to recover valuable space:
\begin{center} \begin{tabular}{l}
\val{/boot/loader} \\
\val{/boot/backup.*} \\
\val{/etc/lilo.conf} \\
\end{tabular} \end{center}
\lilo\ only needs \file{/boot/loader.patched} and \file{/boot/map} (and a
kernel image, of course) to boot.


% -----------------------------------------------------------------------------


\section{Theory of operation}

If you're not familiar with the internals of the \amiga\ boot process, you
may want to read Appendix~\ref{apx:booting} first.


\subsection{Program flow}

If you install a special \lilo\ boot block on a device, \lilo\
performs the following actions:

\begin{itemize}
\item First it reads and parses the configuration file \file{/etc/lilo.conf}.

\item Since \amigaos\ can't access files on an \exttwo\ or
\minix\ file system natively, it should know where the data blocks of the
files are stored. Thus for every kernel image you may want to boot from,
\lilo\ looks up the data blocks of the images, using the \val{FIBMAP}
\var{ioctl()} and stores them in the file \file{/boot/map}, together with the
configuration options.

\item Then \lilo\ reads the loader template executable
\file{/boot/loader}, looks up where \file{/boot/map} is stored on the disk,
patches the loader template executable so it knows where to find the data
blocks of \file{/boot/map}, adds a PC-relative header that decodes the
\amigaos\ executable file format and stores the result in
\file{/boot/loader.patched}.

\item During the last step \lilo\ looks up the data blocks for
\file{/boot/loader.{\linebreak}patched}, fills them in in the boot code and
writes the boot code to the boot block of the device specified in
\file{/etc/lilo.conf}.
\end{itemize}

If the \amiga\ tries to boot from a partition you installed \lilo\ on,
the system loads the special boot code and executes it. The boot code loads the
raw PC-relative executable \file{/boot/loader.patched} and executes it.
Afterwards \file{/boot/loader.patched} reads \file{/boot/map}, eventually asks
the user for a boot \os, and loads the desired \os.


\subsection{The boot block code}

The system calls the boot block code and passes it the \var{BootRequest} (of
type \val{struct IOStdReq}) for the boot device. At that moment the system has
not been initialized completely, e.g.\ \name{dos.library} is still missing.
This has the following consequences:
\begin{itemize}
\item We can't use files, so we need to use raw device I/O. Besides,
\amigaos\ doesn't know \exttwo\ or the \minix\ file system
either.

As an alternative a file is represented by an array of \val{u\_long}s (a
\var{vector}).  The first \val{u\_long} in this array contains the length of
the file (in bytes); the following \val{u\_long}s are disk offsets for the data
blocks, with holes\footnote{A hole is a place in a file where a whole block
contains nothing but zeroes.  \linux\ doesn't store such a block on disk
explicitly, but marks it specially, to save diskspace.} indicated by a disk
offset of 0.  The data block size is 1024 bytes\footnote{This is the default
block size for \linux.  \amigaos\ however uses a default block size of 512
bytes.}.  The data blocks can be read by using the \var{BootRequest}, or by
opening the alternate boot device if the \val{altev} option was used in
\file{/etc/lilo.conf}.

\item We can't use \name{DOS} devices like \name{CON:}. Thus the loader opens a
window and uses the \name{console.device} for communication with the user.

\item The \name{serial.device} resides on disk, so raw serial I/O (using the
private \name{exec.library} functions \var{RawMayGetChar()} and
\var{RawPutChar()}) is used instead to support the auxiliary console.
\end{itemize}

The boot block code loads and calls the loader. The loader should return
\val{FALSE} in case of an error, and \val{TRUE} if the user wants to boot
\amigaos; in all other cases it shouldn't return.


\subsection{The boot library}

The boot block code exports some functions for file access and execution by
passing a function table pointer to the loader.


\subsubsection{File access functions}

These functions provide basic file access.

\begin{itemize}
\item \src{void Open(u\_long *vector)}

Open a file. Only one file can be opened at the same time.

\item \src{void Close(void)}

Close the file opened with \var{Open()}.

\item \src{void Read(void *dest, u\_long length)}

Read \var{length} bytes of data from the file opened with \var{Open} and store
them in memory starting at \var{dest}. This routine does not check whether you
try to read beyond the end of the file.

\item \src{void Seek(u\_long offset)}

Seek to the absolute position \var{offset} in the file opened with \var{Open}.
This routine does not check whether you try to seek beyond the end of the file.

\end{itemize}


\subsubsection{File execution functions}

These functions provide for the loading and execution of files.

\begin{itemize}
\item \src{u\_long *Load(u\_long *vector)}

Load a file and return a pointer to the loaded data. This function uses
\var{Open()}, so it may not be called if there's already a file opened.

\item \src{void UnLoad(u\_long *data)}

Unload a file loaded with \var{Load()}.

\item \src{long Exec(u\_long *data, long arg)}

Execute a block of code pointed to by \var{data}. It pushes all caches first
and passes the supplied \var{arg} in register \var{D0} and returns the return
code after execution.
\end{itemize}


\subsection{The tagged map file format}
\label{sec:tags}

The map file \file{/boot/map} consists of a concatenation of \name{tag
records}.  A tag record contains a \name{Tag}, indicating its type, a
\name{Size} (must be a multiple of 4 bytes) and \var{Size} bytes of data. This
makes the file format very simple to understand and easy to parse and extend.

\subsubsection{General structure}

The general structure of the map file looks like:

\begin{center} \begin{tabular}{|l|r|l|l|}
\hline
Tag                    & Size & Data         & Info \\
\hline \hline
\multicolumn{4}{|c|}{\textbf{File identification}} \\
\hline
TAG\_LILO              &    0 & ---          & \\
\hline \hline
\multicolumn{4}{|c|}{\textbf{Boot options}} \\
\hline
TAG\_HEADER            &    0 & ---          & \\
\multicolumn{3}{|c|}{\vdots}  & \emph{Boot option tags} \\
TAG\_HEADER\_END       &    0 & ---          & \\
\hline \hline
\multicolumn{4}{|c|}{\textbf{One or more boot records}} \\
\hline
TAG\_BOOT\_RECORD      &    ? & char []      & Boot record label \\
\multicolumn{3}{|c|}{\vdots}  & \emph{Boot record tags} \\
TAG\_BOOT\_RECORD\_END &    0 & ---          & \\
\hline
\multicolumn{4}{c}{\vdots} \\
\hline
\multicolumn{4}{|c|}{\textbf{Zero or more file definitions}} \\
\hline
TAG\_FILE\_DEF         &    ? & char []      & File name \\
\multicolumn{3}{|c|}{\vdots}  & \emph{File definition tags} \\
TAG\_FILE\_DEF\_END    &    0 & ---          & \\
\hline
\multicolumn{4}{c}{\vdots} \\
\hline
\multicolumn{4}{|c|}{\textbf{End of file}} \\
\hline
TAG\_EOF               &    0 & ---          & \\
\hline
\end{tabular} \end{center}

\subsubsection{Boot option tags}

\begin{center} \begin{tabular}{|l|r|l|p{34mm}|}
\hline
Tag                    & Size & Data         & Info \\
\hline \hline
TAG\_DEFAULT           &    ? & char []      & Default boot image \\
TAG\_AUTO              &    4 & u\_long      & Automatic boot flag \\
TAG\_TIME\_OUT         &    4 & u\_long      & Time out value \\
TAG\_AUX               &    4 & u\_long      & Auxiliary console \\
TAG\_BAUD              &    4 & u\_long      & Baud for auxiliary console \\
TAG\_MASTER\_PASSWORD  &    ? & char []      & Master password \\
TAG\_DEBUG             &    4 & u\_long      & Debug flag \\
TAG\_PROMPT            &    ? & char []      & Boot prompt \\
TAG\_KICKRANGE         &    4 & u\_short [2] & Valid \kickstart\ version range \\
\hline
\end{tabular} \end{center}

\subsubsection{Boot record tags}

\begin{center} \begin{tabular}{|l|r|l|l|}
\hline
Tag                    & Size & Data         & Info \\
\hline \hline
TAG\_ALIAS             &    ? & char []      & Alias label name \\
TAG\_OS\_TYPE          &    4 & u\_long      & \os\ type \\
TAG\_KERNEL            &    ? & char []      & Kernel image \\
TAG\_ARGUMENTS         &    ? & char []      & Boot arguments \\
TAG\_PASSWORD          &    ? & char []      & Password \\
TAG\_CHIP\_RAM\_SIZE   &    4 & u\_long      & Chip RAM size \\
TAG\_FAST\_RAM\_CHUNK  &    8 & u\_long [2]  & Fast RAM chunk \\
TAG\_MODEL             &    4 & u\_long      & Amiga model \\
TAG\_RAMDISK           &    ? & char []      & Ramdisk image \\
\hline
\end{tabular} \end{center}

\subsubsection{File definition tags}

\begin{center} \begin{tabular}{|l|r|l|l|}
\hline
Tag                    & Size & Data         & Info \\
\hline \hline
TAG\_VECTOR            &    ? & u\_long []   & File vector \\
\hline
\end{tabular} \end{center}

\subsubsection{Debugging}

You can examine the contents of a map file with the \file{dumpmapfile} utility.


\subsection{Booting \linux}

If the user wants to boot \linux, the loader calls an adapted
version of the \amiboot\ utility. If this fails, it returns \val{FALSE}
to the boot code.


\subsection{Booting \amigaos}

If the user wants to boot \amigaos, the loader just returns \val{TRUE}
and the boot code uses the default boot method.


\subsection{\lilo\ alert codes}

The following alert codes are used by \lilo:

\begin{center} \begin{tabular}{|c|l|l|}
\hline
Value          & Meaning \\
\hline \hline
\val{30000001} & Boot error when automatic boot \\
\val{CC010000} & No memory \\
\val{CC010007} & No screen \\
\val{CC01000B} & No window \\
\val{CC038002} & No \name{graphics.library} \\
\val{CC038004} & No \name{intuition.library} \\
\val{CC03800A} & No \name{expansion.library} \\
\val{CC040000} & No alternate boot device \\
\val{CC048011} & No \name{console.device} \\
\val{CC048013} & No \name{keyboard.device} \\
\val{CC048015} & No \name{timer.device} \\
\val{CC048035} & No \name{input.device} \\
\val{CC060000} & Read error \\
\val{CC070000} & No signal \\
\val{CC4D4150} & Corrupt map file \\
\hline
\end{tabular} \end{center}

Other alert codes (especially those of the form \val{8000000x}, with \val{x}
equal to \val{3}, \val{4}, \val{A} or \val{B}) may indicate that something went
wrong with the \lilo\ installation, e.g.\ you forgot to rerun \file{lilo} after
you changed some important files.


% -----------------------------------------------------------------------------


\newpage
\appendix


\section{Credits}

\begin{itemize}
\item The \amililo\ was written by Geert Uytterhoeven
(\email{Geert.Uytterhoeven@cs.kuleuven.ac.be}).

\item The \linux\ bootstrap code was taken from:
\begin{quote}
\amiboot: This program loads the \linux\ kernel into an
\amiga\ and launches it. \copyright\ Copyright 1993, 1994 by Hamish
Macdonald (\email{hamish@border.ocunix.on.ca}), Greg Harp
(\email{harp@netcom.com}).
\end{quote}

\item Janos Farkas (\email{chexum@sparta.banki.hu}) added cache fixes for
\kickstart\ \name{V36} (\name{A3000 Beta ROM}) to and made some optimizations
in the boot block code.

\item The following people inspired me with their comments:
\begin{itemize}
\item J\"org Mayer (\email{jmayer@informatik.uni-kl.de})
\item J\"org Dorchain (\email{dorchain@cscip.uni-sb.de})
\item Christof Damian (\email{cdamian@mediaconsult.com})
\end{itemize}

\item The original idea for this program comes from the \linuxgen\
distribution:
\begin{quote}
\name{LILO}: Generic Boot Loader for \linuxgen\ (\name{LInux LOader}) by
Werner Almesberger (\email{werner.almesberger@lrc.di.epfl.{\linebreak}ch}).
\end{quote}

\item The \file{rlatex} script was taken from the \name{LILO} distribution and
is \copyright\ Copyright 1992-1996 Werner Almesberger.
\end{itemize}

And of course I want to thank the whole \linuxgen\ community, especially the
other \linux\ guys, for this great \name{Operating System}\footnote{Note the
uppercase `O' and `S'. IMHO \name{icrosoft} should refer to \name{indows 95}
with \name{perating ystem}~:-)}!!


% -----------------------------------------------------------------------------


\section{The \name{GNU General Public License}}

The \amililo\ and its documentation are \copyright\
Copyright 1995 by Geert Uytterhoeven. However, they are also subject to the
terms and conditions of the \name{GNU General Public License}. See the file
\file{COPYING} for more details.


% -----------------------------------------------------------------------------


\section{The \amiga\ boot process}
\label{apx:booting}

An \amiga\ can boot from different devices. After initialization of all
internal (motherboard) and external (\name{Zorro II/III} boards)
devices, a list of bootable devices is created, sorted by boot priority. This
list can be modified using the system boot menu\footnote{The system boot menu
is invoked by holding both the left and right mouse buttons at boot up.}. The
first floppy drive (\file{DF0:})\ always has boot priority 5, while the default
boot priority of a hard drive partition is 0.

Then the system tries to boot from the bootable devices in the list, the one
after the other starting with the device with the highest boot priority, until
success. If all failed, the system asks the user to insert a floppy by
displaying an image or animation. On succes, the system boots.

A device is a candidate for booting if it's marked as bootable and if one of
the following conditions is met:

\begin{itemize}
\item The device has a valid file system (i.e.\ its \name{DosType} is the same
as that of a \name{ROM} file system or a file system that's stored in the
\rdb\ of one of the hard drives) and the file system could be
initialized for this device. This should be the case for your default
\amigaos\ boot partition.

\item There is no valid file system for the device. This is the case if you
specify \val{0x45585432} (\val{EXT2} in \name{HEX ASCII}) for the
\name{DosType} and there is no file system in a \rdb\ with \name{DosType}
\val{0x45585432}.
\end{itemize}

There are two ways to boot from a boot device:  with or without execution of
the boot block\footnote{The boot block is the first block --- actually the
first $n$ blocks, with default $n = 2$.  Since the default block size under
\amigaos\ is 512 bytes, the default boot block size is 1024 bytes --- of the
device, which has a special purpose.}:

\begin{itemize}
\item Without execution of the boot block the system just ignores the boot
block contents and uses the default boot method. This is the default behavior
for hard drive partitions, which can be overridden by enabling \name{Custom
Boot Code} for the partition.

\item With execution of the boot block the system loads the boot block and
calculates a checksum value. If the checksum is correct, the boot code in the
boot block is executed, with the \var{BootRequest} (of type \val{struct
IOStdReq}) for the boot device passed to it as a parameter. If the checksum is
incorrect, the boot process fails for this device. This is the default behavior
for the floppy drive and the behavior for hard drive partitions if \name{Custom
Boot Code} is enabled. \lilo\ uses this method too.
\end{itemize}

The default boot method --- this method is also used in the default boot code
for floppies --- just checks whether \name{dos.library} is resident and
returns a pointer to the initialization routine of \name{dos.library}.


% -----------------------------------------------------------------------------


\section{History}

\subsection*{Version 0.1}

\begin{itemize}
\item Initial `alpha' release with support for only one kernel image at the
same time.
\end{itemize}

\subsection*{Version 0.2}

\begin{itemize}
\item Addition of the configuration file.
\item Support for multiple kernel images and command lines.
\end{itemize}

\subsection*{Version 0.3}

\begin{itemize}
\item Handles files with holes.
\item Fixes for \kickstart\ \name{V36} (\name{A3000 Beta ROM}).
\item Debug option.
\item Rounds memory chunks to a multiple of 256K instead of 1M (for e.g.\ users
of the \name{A3640 MapROM} feature).
\end{itemize}

\subsection*{Version 0.4}

\begin{itemize}
\item Support added for a terminal connected to the builtin serial port.
\item Documentation in \LaTeX\ 2\raisebox{-.5ex}{$\varepsilon$}.
\end{itemize}

\subsection*{Version 0.4a}

\begin{itemize}
\item Recompile to compensate for the changes in \file{<asm/bootinfo.h>}.
\end{itemize}

\subsection*{Version 0.5}

\begin{itemize}
\item \var{Seek()} function added to the boot library.
\item Bootstrap code updated to the \amiboot\ 2.1 level:
\begin{itemize}
\item Support added for \name{ELF} kernels,
\item Support added for \name{a.out ZMAGIC} kernels.
\end{itemize}
\item \var{LoadSeg()} and \var{UnLoadSeg()} functions of the boot library are
replaced by \var{Load()} and \var{UnLoad()}.
\item \file{/boot/loader} is no longer an \amigaos\ executable. Now it's a
raw PC-relative executable created with the normal \name{cc1} of
\name{m68k-linux-gcc} 2.7.x and the \file{fixpic} \name{perl} script. As a
consequence you no longer need \name{gcc} under \amigaos\ or a cross-compiler
to create it\footnote{Another step in the direction of an \amigaos-free
Amiga~:-)}.
\item New configuration file format with additional options:
\begin{description}
\item[\val{baud}:] Serial terminal speed,
\item[\val{altdev}:] Alternate boot device,
\item[\val{default}:] Default boot \os.
\end{description}
\end{itemize}

\subsection*{Version 0.6}

\begin{itemize}
\item New options for the configuration file:
\begin{description}
\item[\val{chipram}:] \name{Chip RAM} size,
\item[\val{fastram}:] \name{Fast RAM} address and size.
\item[\val{model}:] Amiga model.
\end{description}
\item Now \amiboot\ and \lilo\ use the same bootstrap code to ease
code maintenance.
\item Changed the data block size from 512 to 1024 bytes.
\item New command line option \val{--checksum}.
\end{itemize}

\subsection*{Version 0.7 (internal version)}

\begin{itemize}
\item New tagged file format for \file{/boot/map}; included
\file{dumptagfile.c} for debugging.
\item New command line option \val{--root}.
\item New options for the configuration file:
\begin{description}
\item[\val{prompt}:] Loader prompt,
\item[\val{alias}:] Alias label for a boot record,
\item[\val{ramdisk}:] File containing a file system to be used as a ramdisk.
\end{description}
\item \lilo\ now knows the version of \amiboot\ it's compatible with.
\item Implicit kernel command line options \val{BOOT\_IMAGE=}\val{label} and
\val{auto} added.
\end{itemize}

\subsection*{Version 0.8 (internal version)}

\begin{itemize}
\item Now \lilo\ also works under \linux\ \name{1.3.x} or higher.
\item Support added for gzipped kernel images and ramdisks.
\item Addition of a boot monitor.
\item Now all file vectors are stored only once in the map file.
\item New options for the configuration file:
\begin{description}
\item[\val{kickrange}:] Specify the valid \kickstart\ version range,
\item[\val{file}:] Add your own files to the map file.
\end{description}
\item Included \file{fakeboot.c} for debugging.
\end{itemize}

\subsection*{Version 1.0}

\begin{itemize}
\item \file{fixpic} is dead, long live \file{m68k-cbm-amigados-gcc}!
\file{/boot/loader} is again an \amigaos\ executable.
\item Support for gzipped kernel images and ramdisks removed because it doesn't
work with \file{m68k-cbm-amigados-gcc}.
\item Automatic creation of a boot block backup for easy uninstalling.
\item New command line options \val{--backup}, \val{--uninstall} and
\val{--version}.
\end{itemize}


% -----------------------------------------------------------------------------

\end{document}
