TFTPLILO V1.1.2
===============

TFTPLILO is a Linux kernel loader for booting diskless m68k/Linux
machines over a network. Currently TFTPLILO supports the BVM
BVME4000/6000 and Motorola MVME SBCs. TFTPLILO relies on the network
services of the target computer's boot ROMs in order to transfer the
required kernel and configuration data.


Theory of operation
-------------------

The target computer's boot ROMs must first be configured to transfer and
execute the TFTPLILO (tftplilo.bvme or tftplilo.mvme) executable at boot
time. TFTPLILO will then transfer its configuration text file using the
services for the boot ROMs. The configuration file contains details such
as which kernel to load, the kernel startup command line etc. A single
configuration file can specify any number of boot configurations for any
number of machines. TFTPLILO examines the configuration file and
extracts the configurations relating to the target machine. If
configured to do so TFTPLILO will then present the user with a list of
available configurations and allow them to select one along with any
extra kernel command line parameters that may be required. Once the
configuration is selected TFTPLILO will proceed to load and execute the
corresponding Linux kernel and optional initrd ramdisk, again using the
services of the targets boot ROMs.


Configuration file
------------------

The configuration file is an ASCII text file, which defines the boot
configuration for each machine. The default configuration file name,
"tftplilo.conf", is compiled into TFTPLILO but may be overridden by
configuring the boot ROMs (see machine specific details below). Each
line of the configuration file may be terminated with either a CR or LF
or both in either order, what ever suits the environment in which it is
edited, (DOS, Linux, Macintosh etc.).

The file itself is divided into 3 types of section:

1. One or more machine specific sections each of which defines the
   configuration for a single or group of machines selected by the IP
   address of the target machine. Each of these sections begins with a line
   containing the word 'crate' in square brackets, i.e. [crate],
   extending to the start of the next section or to the end of the file.

2. Zero or more boot specific sections each defining a kernel image and
   configuration that can be selected at boot time. Boot sections begin
   with a line containing the word 'boot' in square brackets, i.e. [boot],
   extending to the start of the next section or the end of the file.

3. A single global section which defines the default values for the
   other sections. The global section extends from the first line of the
   configuration file until the first [boot] or [crate] section.

Blank lines and lines beginning with a '#' are ignored and may be used
to improve readability and add comments. A line may be continued onto
the next line by placing a backslash at the end.

The parameters in each section are specified using the syntax:

  option = value

Where 'option' is the name of the configuration parameter and 'value' is
what it is set to. Each configuration parameter must begin on a new
line. The value of each option can be one of 4 possible types:

<number>     Numeric values are used to specify timeouts, delays and
             memory sizes. By default they are interpreted as decimal
             but they can be specified in binary, octal and hexadecimal
             by prefixing them with 0b, 0 and 0x respectively.
             Additionally by suffixing the number with a 'K' or an 'M'
             they are multiplied by 1024 or 1024*1024 respectively.

<bool>       Boolean values are used to turn an option on or off and
             are specified as either "Yes", "No", "True", "False" or a
             number that is either zero (false) or non-zero (true). For
             boolean configuration parameters the equals symbol and value
             are optional, if omitted the value is taken to be true.

<filename>	 A pathlist string that is used to transfer the file from
             the remote TFTP server.

<string>	 An arbitrary sequence of characters that are used to
             specify labels and command line parameters.


The following is a list of the possible global options. All of these
options provide default values for similarly named options in each of
the [crate] sections. Any option not specified in the global section
takes on a default compiled in value.

Valid global options are:

  Option name                Compiled in default Value
  -----------                -------------------------
  debug                      No
  timeout                    No timeout (infinite)
  delay                      3 seconds
  prompt                     No
  display                    Use [display] section if defined
  restricted                 No
  calldbg or callmonitor     No
  memsize                    Auto detect
  kernel or image            No default (must be specified)
  ramdisk                    None
  console                    "ttyS0"
  root                       None
  read-only                  None
  read-write                 None
  cmdline                    None
  append                     None

The following is a list of possible [crate] options where appropriate
default option values are taken from either the compiled in defaults or
similarly named options in the global section.

  debug
  ip
  timeout
  delay
  prompt
  display
  restricted
  calldbg or callmonitor
  memsize
  kernel or image
  ramdisk
  console
  root
  read-only
  read-write
  cmdline
  append
  boot
  default


Valid [boot] section options are as follows, default values are taken
from either the applicable [crate] section or the global or compiled in
defaults.

  label
  alias
  description
  debug
  restricted
  calldbg or callmonitor
  memsize
  kernel or image
  ramdisk
  console
  root
  read-only
  read-write
  cmdline
  append


Option descriptions
-------------------

Below is a full description of each of the available options.

------------------------------------------------------------------------
debug = bool                   Sections: global, crate, boot

Enable TFTPLILO debug mode.

------------------------------------------------------------------------
timeout = secs                 Sections: global, crate

Sets a timeout in seconds for keyboard input. If no key is pressed for
the specified time, the default image is automatically booted. A timeout
of zero disables the timeout feature. The default timeout is disabled.

------------------------------------------------------------------------
delay = secs                   Sections: global, crate

Specifies the number of seconds the TFTPLILO should wait before booting
the default configuration. Pressing a key on the keyboard will interrupt
the delay and cause TFTPLILO to prompt for a configuration to boot.
TFTPLILO doesn't wait or check for keyboard input if 'delay' is set to
zero. The default delay is 3 seconds.

------------------------------------------------------------------------
prompt = bool                  Sections: global, crate

Forces entering the boot prompt without delaying or expecting any prior
key presses. Unattended reboots are impossible if 'prompt' is set and
'timeout' isn't.

------------------------------------------------------------------------
display = string               Sections: global, crate

This option specifies a suffix string that is appended to the string
"display-" the resulting string is the name of a configuration file
section that contains a message that is displayed by TFTPLILO when it
starts. If the 'display' option is not used or is used but does not define
a suffix string, the default display section '[display]' is used. If the
resulting section name can not be found in the configuration file it is
silently ignored. The section containing the actual message extends to
the start of the next section or to the end of the configuration file.
Lines in the message section containing nothing but white space are
ignored. Newlines must be given explicitly with the "\n" escape
sequence. See the 'Display and description strings' section later in
this document.

For example:

[crate]
display = crate1

[display-crate1]
"\n"
"\n"
"       Insert your favorite greeting here\n"
"       ----------------------------------\n"
"\n"


------------------------------------------------------------------------
console = string               Sections: global, crate, boot

Specifies the console device name and options, to be used for 2.1 and
later kernels. It is ignored when booting a 2.0 kernel. The resulting
kernel command line option is inserted before those specified by the
'cmdline' option.

------------------------------------------------------------------------
root = string                  Sections: global, crate, boot

Specifies the device that should be mounted as root. The root device
name string can be prefixed with /dev/ to indicate a device name or can
be specified as a hexadecimal number indicating the devices major/minor
numbers. The resulting kernel command line option is inserted before
those specified by the 'cmdline' option.

------------------------------------------------------------------------
read-only = bool               Sections: global, crate, boot

If true specifies that the root device should be mounted read only.
Equivalent to specifying 'read-write = false'. The resulting kernel
command line option is inserted before those specified by the 'cmdline'
option.

------------------------------------------------------------------------
read-write = bool              Sections: global, crate, boot

If true specifies that the root device should be mounted read write.
Equivalent to specifying 'read-only = false'. The resulting kernel
command line option is inserted before those specified by the 'cmdline'
option.

------------------------------------------------------------------------
cmdline = string               Sections: global, crate, boot

Specifies the kernel command line. Command line parameters specified at
the Boot: prompt are placed on the kernels command line after the values
specified here.

------------------------------------------------------------------------
append = string                Sections: global, crate, boot

Specifies extra kernel command line parameters that are appended after
the values specified by 'cmdline' and at the Boot: prompt.

------------------------------------------------------------------------
restricted = bool              Sections: global, crate, boot

If true specifies that any kernel command line parameters entered at the
boot prompt should be ignored. This provides a safe way for an operator
to select between multiple boot configurations.

------------------------------------------------------------------------
kernel = filename              Sections: global, crate, boot

Specifies the path to a version 2.0 or later Linux kernel image on the
remote TFTP server. The image should be ELF format and may be compressed
with 'gzip' if required.

------------------------------------------------------------------------
image = filename               Sections: global, crate, boot

Another name for the 'kernel' option.

------------------------------------------------------------------------
ramdisk = filename             Sections: global, crate, boot

Specifies the path to an initrd ramdisk image that is to be loaded at
boot time from the remote TFTP server. If the filename is specified as
"none", without the quotes, then any previously specified default value
is ignored and no ramdisk load will be attempted.

------------------------------------------------------------------------
memsize = number               Sections: global, crate, boot

Specifies the amount of system RAM in bytes that the Kernel can use. If
not specified the boot loader will auto detect the amount of available
memory. 

------------------------------------------------------------------------
callmonitor = bool             Sections: global, crate, boot

If specified as true causes the TFTPLILO to call the resident ROM debug
monitor immediately prior to executing the loaded kernel.

Warning: Do NOT use this option if your boot ROMs are configured to use
the bottom 64K of memory for local storage. The Linux kernel is loaded
over this memory region and will probably cause the boot ROM code to
crash when it is called.

------------------------------------------------------------------------
calldbg = bool                 Sections: global, crate, boot

Another name for the 'callmonitor' option.

------------------------------------------------------------------------
label = name                   Sections: boot

Specifies the name by which TFTPLILO identifies the boot configuration.
A label option must be specified for each boot section.

------------------------------------------------------------------------
alias = name                   Sections: boot

An alternative name by which TFTPLILO can identify the boot section.

------------------------------------------------------------------------
description = text             Sections: boot

Specifies text that will be placed next to the boot records label when
listing the available boot records. See the 'Display and description
strings' section later in this document.

------------------------------------------------------------------------
boot = boot-section-label      Sections: crate

Specifies the label or alias of a boot configuration to use for this
machine. This option can be specified any number of times to select all
the required boot configurations. The order in which multiple 'boot'
options are specified dictates the order in which they are presented at
the Boot: prompt. If no valid boot options are specified TFTPLILO will
first try to build a single default boot configuration from the default
values specified in the [crate] and global sections. If no configuration
can be made this way TFTPLILO will scan the whole of the configuration
file and use ALL the boot configurations that are available.

------------------------------------------------------------------------
default = boot-section-label   Sections: crate

This option specifies an additional boot configuration that will be the
default boot configuration to use for this machine. If not specified the
first 'boot' option will become the default.

------------------------------------------------------------------------
ip = IP address                Sections: crate

This option specifies an IP address or range of IP addresses that
TFTPLILO uses to select a crate section for the booting target machine.
If TFTPLILO cannot find a [crate] section that matches the target
machines IP address it will first try to find a [crate] section that has
an 'ip' option with the string value of "any". If that fails it will
scan for a [crate] section without an 'ip' option. The 'ip' option can
be used any number of times to specify a number of matching addresses.
IP addresses should be specified using the conventional decimal dotted
quad notation. Giving a hyphenated range for any of the decimal
components of the IP address specifies ranges of IP addresses.

For example:

 192.168.1.2-5   = 192.168.1.2, 192.168.1.3, 192.168.1.4 and 192.168.1.5
 192.168.1-2.1   = 192.168.1.1 and 192.168.2.1
 192.168.1-2.1-2 = 192.168.1.1, 192.168.1.2, 192.168.2.1 and 192.168.2.2

------------------------------------------------------------------------

IP address substitution
-----------------------

To aid configuration, the kernel command line ('cmdline' and 'append'
options and Boot: prompt input) and the configuration file name
(configured in the boot ROMs) are subject to IP address substitution.
This allows you to place 'printf' style sequences into to these strings
which TFTPLILO substitutes for various IP addresses obtained from the
boot ROMs.

    %%  = %
    %C  = machines IP address.
    %S  = TFTP servers IP address.
    %M  = subnet mask.
    %G  = gateway address.
    %B  = broadcast address (MVME only)

Lower case equivalents of these sequences substitute an empty string if
the address is "0.0.0.0" (unconfigured).


Display and description strings
-------------------------------

Display and description strings are normally subject to leading and trailing
white space removal, to prevent this enclose the description strings and
each line of the display section in double quotes. Also not that any
non-printable or control character will be replaced with a single space.
To embed control characters into the message the following escape
sequences may be used:

    \n    = newline
    \r    = carriage return
    \t    = tab
    \b    = backspace
    \e    = escape (ASCII 27)
    \\    = a single backslash
    \ooo  = any character specified by up to 3 octal digits.


Boot prompt
-----------

When TFTPLILO enters interactive mode it first displays a list of
available configurations. This list can be redisplayed by entering
"help" or by pressing the <TAB> key. At the Boot: prompt enter the
required configuration name or alias followed by any extra kernel
command line parameters required. The extra kernel command line
parameters are subject to IP address substitution as described above.
Entering nothing at the boot prompt or allowing it to timeout (see the
'timeout' configuration option) will cause the default boot
configuration to be selected.


Architecture conditional configuration
--------------------------------------

A space delimited list of machine architecture names can be placed after
the closing square bracket of a [crate], [boot], [display] or
[display-xxx] section marker. This causes the section to be ignored
unless TFTPLILO is running on one of the named architectures.

The recognised architecture names are:
  BVME4000 BVME6000 MVME162 MVME166 MVME167 MVME172 and MVME177

If an architecture name is specified that is not in the above list no
error will be reported but a match will never be made.

Example:

 [crate]
 boot = linux 
  .
  .
  .

 [boot] BVME4000 BVME6000
 label  = linux
 kernel = linuxbvme
  .
  .
  .

 [boot] MVME166 MVME167
 label  = linux
 kernel = linuxmvme
  .
  .
  .

Note:
 Provided the [boot] sections are conditionalised, as in the above
 example, so that the sections label and alias are unique after the
 conditions are applied, it is acceptable to have more than one [boot]
 section with the same 'label' or 'alias' name.


Machine configuration
---------------------

BVME4000/6000
-------------

In order to use TFTPLILO the BVM SBC must be fitted with BVMBug Revision
G or later boot ROMs.

Front panel DIP switch usage:

Switch  Left position  Right position  Function
------  -------------  --------------  --------------------------------
 SW1    disable        enable          VMEbus system controller functions
 SW2    0x00000000     0xE900000000    BVMBug workspace address (64Kb)
 SW3    disable        enable          Map VMEbus into low 256Mb
 SW4    enable         disable         Autoboot

New to BVMBug revision G is the ability to choose which area of RAM to
use for it's local workspace. Previous revisions always used the onboard
SRAM at address E9000000. With revision G, the front panel DIP switch 2
is used to select between address E9000000 (SRAM) when switched to the
right and address 00000000 (DRAM) when switched to the left. If TFTPLILO
is configured to call BVMBug just before calling the Linux kernel
(calldbg = Yes) then the DIP switch should be set to use the SRAM at
address E9000000 because the linux kernel will have been moved to the
bottom area of memory overwriting what would have been BVMBug's
workspace.

Flip the lower front panel DIP switch 4 to the right to cause the BVMBug
prompt to be displayed at reset. Using the BVMBug 'rc' (reconfigure
command) the machines network boot parameters can be configured. When
done flip DIP switch 4 back to the left to cause BVMBug to auto boot.


BVME4000/6000 Generic Bootstrap - Revision G
Copyright (c) 1997-1998 BVM Ltd.

tcr:0000          dttn:F00FA040 00000000                ittn:00000000 00000000
vbr:E9000000 sfc:0 dfc:0   cacr:00000000       urp:00000000       srp:00000000
dn: 00000000 00000000  00000000 00000000  00000000 00000000  00000000 00000000
an: 00000000 00000000  00000000 00000000  00000000 00000000  E9000400 E900F800
pc: E800052C  sr:2700 (--S--7-----)t:OFF                 usp:E900F000   ^ssp^
0xE800052C          >2C7C00000000         movea.l #0,a6
BVMBug: rc

SYSTEM RECONFIGURATION

VMEbus snooping is enabled, LANC snooping is enabled
VME A16 slave address window is disabled
VME A24 slave address window is disabled
VME A32 slave address window is disabled
IP IRQ's: A0=1 A1=1 B0=1 B1=1 C0=1 C1=1 D0=1 D1=1 E0=1 E1=1 F0=1 F1=1
IPA is slow/async, IPB is slow/async, IP exp is slow/async
The boot ROM baud rate is 115200
The initiator SCSI ID is 7
The Ethernet Address is 00:80:FB:02:04:65
Internet address is determined using BOOTP
Server address is determined using BOOTP
Gateway address is determined using BOOTP
Subnet mask is 128.0.0.0
Default net boot file load address is 0x00000000
Net boot file name is "bootfile"
Boot argument string is ""
The current boot order is : Disk on ID 2

Set default values? (y/n/q/f) : n
Reconfigure the ethernet address? (y/n/q/f/b) : n
Reconfigure the snoop control? (y/n/q/f/b) : n
Reconfigure the slave addressing? (y/n/q/f/b) : n
Reconfigure the IP IRQ levels? (y/n/q/f/b) : n
Reconfigure the IP modes? (y/n/q/f/b) : n
Reconfigure the baud rate? (y/n/q/f/b) : n
Reconfigure the initiator SCSI ID? (y/n/q/f/b) : n
Reconfigure net boot parameters? (y/n/q/f/b) : y

Internet address is determined using BOOTP
Server address is determined using BOOTP
Gateway address is determined using BOOTP
Subnet mask is 0.0.0.0
Default net boot file load address is 0x00000000
Net boot file name is "bootfile"

Internet address    :  (n.n.n.n or 0 to use bootp) : 192.168.1.3
TFTP server address :  (n.n.n.n or 0 to use bootp) : 0
Gateway address     :  (n.n.n.n or 0 to use bootp) : 0
Number of subnet mask bits (0-31) : 24
Enter default net boot file load address (hex) : 10000
Net boot file name ("NULL" for none) : tftplilo.bvme

Reconfigure boot file arguments? (y/n/q/f/b) : y

Boot argument string is ""

Boot arguments ("NULL" for none) : tftplilo.conf

Reconfigure the boot devices? (y/n/q/f/b) : y
The current boot order is : Disk on ID 2

Available boot drivers:
 1. BOOTP/TFTP
 2. SCSI CD-ROM, Hard or Floppy Disk

The order you specify these boot drivers determines the order
in which they will be tried when the system is configured to boot
automatically. Each driver is selected with a 1 or 2 digit code,
the first digit represents the boot driver number as listed above,
and the second the SCSI device ID where applicable

Enter the numbers of the boot drivers in the order that you want
them prioritised: 1


VMEbus snooping is enabled, LANC snooping is enabled
VME A16 slave address window is disabled
VME A24 slave address window is disabled
VME A32 slave address window is disabled
IP IRQ's: A0=1 A1=1 B0=1 B1=1 C0=1 C1=1 D0=1 D1=1 E0=1 E1=1 F0=1 F1=1
IPA is slow/async, IPB is slow/async, IP exp is slow/async
The boot ROM baud rate is 115200
The initiator SCSI ID is 7
The Ethernet Address is 00:80:FB:02:04:65
Internet address is 192.168.1.3
Server address is determined using BOOTP
Gateway address is not used
Subnet mask is 255.255.255.0
Default net boot file load address is 0x00010000
Net boot file name is "tftplilo.bvme"
Boot argument string is "tftplilo.conf"
The current boot order is : BOOTP/TFTP

Is this the configuration you want? (y/n/b/q) : y

Notes:

1. TFTPLILO will always load at address 0x00010000 regardless of the
   "Default net boot file load address" configuration.

2. TFTPLILO uses the "Boot argument string" as its configuration file
   name. If not set it will use the compiled in default value. Boards
   earlier than revision F cannot configure this parameter (there is not
   enough non-volatile storage) and will always use the compiled in default.

3. Boards earlier than revision F cannot configure the net boot file
   name (not enough non-volatile storage) and have a hard coded name
   string of "bootfile". Space is reserved in the BVMBug prom image at
   address 0xE8000410 to patched an alternative name (up to 64 bytes
   including null terminator) if you have the facility to copy an
   reprogram the proms. If not the "tftplilo.bvme" file must be renamed
   to "bootfile" or BVMBug must be configured to use the BOOTP protocol
   in which case it will use the bootfile name returned from the BOOTP server.

4. BVMBug only use the BOOTP protocol if either the client or the
   server's IP address is set to zero, or on a revision F or later board
   the net bootfile name is not set. The gateway address is set from
   the BOOTP response only if both it and the server IP address are set to zero.
   The subnet mask is set from the BOOTP response only if it is non zero
   and the client IP address is zero. When transferring the data from the
   TFTP server the gateway address is used only if it is non-zero and
   the client and server addresses are on different subnets.


MVME16x
-------

To reconfigure the MVME network boot parameters use the 'niot' command.


167-Bug>niot
Controller LUN =00? 0
Device LUN     =00? 0
Node Control Memory Address =FFE10000?
Client IP Address      =0.0.0.0? 192.168.1.4
Server IP Address      =0.0.0.0? 192.168.1.1
Subnet IP Address Mask =0.0.0.0? 255.255.255.0
Broadcast IP Address   =0.0.0.0? 192.168.1.255
Gateway IP Address     =0.0.0.0?
Boot File Name ("NULL" for None)     =? tftplilo.mvme
Argument File Name ("NULL" for None) =? tftplilo.conf
Boot File Load Address         =00000000? 10000
Boot File Execution Address    =00000000? 10000
Boot File Execution Delay      =00000000?
Boot File Length               =00000000?
Boot File Byte Offset          =00000000?
BOOTP/RARP Request Retry       =00?
TFTP/ARP Request Retry         =00?
Trace Character Buffer Address =00000000?
BOOTP/RARP Request Control: Always/When-Needed (A/W)=W? w
BOOTP/RARP Reply Update Control: Yes/No (Y/N)       =Y?

Update Non-Volatile RAM (Y/N)? y
167-Bug>

Notes:

1. TFTPLILO will always load at the address specified by the "Boot File
   Load Address" configuration. This should always be set to 0x00010000
   and the "Boot File Execution Address" should always match.

2. TFTPLILO uses the "Argument File Name" string as its configuration file
   name. If not set it will use the compiled in default value.


----

Nick Holgate <nick@deadleg.freeserve.co.uk> <holgate@debian.org> [13/07/99]