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 cannot 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 note
that  any  non-printable  or  control characters 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     0xE9000000      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 and
   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> [04/07/01]
