rpld.conf - rpld configuration file

NAME

     rpld.conf - rpld configuration file

DESCRIPTION

     The rpld.conf file is the configuration file for the rpld(1) program.  It
     consists of a number of HOST blocks of the form:

     HOST {
          ...
     };

     Within the HOST blocks there can be ethernet, execute, framesize,
     blocksize, nospew, and pacing  directives and FILE blocks.  FILE blocks
     are of the form:

             FILE {
                  ...
             };

     Within FILE blocks there can be path, offset, length, load and linux
     directives.  Directives are of the form

             foo = something;
     or

             bar;

     and are detailed below. Comments are allowed in the configuration file and
     can either be in C-form (i.e. starting with /* and ending with */) or C++ form
     (starting with // and ending at the line break).

DIRECTIVES

Directives are of the form

foo = something;
or

bar;

If something is a string it should be entered between quotes. Numbers are
assumed to be decimal unless preceded by 0x in which case they are interpreted
in hexadecimal. MAC addresses should be given as 6 octets in hexadecimal without
the leading 0x. The octets should be separated by colons.

number = 131;
hexnumber = 0x7382;
macaddr = 08:00:02:43:21:22;
string = "fish soup";

blocksize
This directive sets the maximum size in octets of data that is transmitted in
each
FILE.DATA.RESPONSE frame that the server sends. The block size should
be at least 48 octets smaller than the frame size. After the client negotiates
a frame size the block size is checked and if it is no longer 48 octets smaller
than frame size it is adjusted accordingly. Some buggy boot ROMs will fail
if block size is not a multiple of four, accordingly you should be aware of the
situation that could arise if the client was to negotiate the block size down
to something that wasn’t a multiple of four.

blocksize = 528;

ethernet
This directive sets the MAC address of the client referenced
in this HOST block. It should either be formatted as six octets separated by colons. e.g..

ethernet = 00:60:6e:33:4f:2c;

or it can be specified as a range of mac addresses as six octets separated by colons followed by a solidus and the number of bytes to match. So:

ethernet = 00:50:32:33:00:00/4;

Will match anything of the form 00:50:32:33:xx:xx. It is expected that this
support will be changed from bytes to bits in a future release.

execute
This directive sets the execute address that control is transferred to when
downloading has finished. It should be a number in either decimal or hexadecimal.

execute = 0x92000;

It is not clear whether or not the client’s Ethernet adapter is or should be shut down
prior to the transfer of control. This may cause problems on systems where the
Ethernet adapter in the client can do DMA directly into host memory. As the adapter may
continue writing to the buffers that the boot ROM set up, it may be necessary
to download a small program to reset the Ethernet adapter. See code under the
nics/
directory in the source distribution for examples.
framesize
This directive sets the maximum size of the frames that the server uses to
communicate with the client. The actual frame size used is negotiated between
the client and the server, the server will force the client to use this value
if it requests a larger one. The maximum frame size that Ethernet can support is
1500, and this is the default value.

framesize = 576;

length
This directive sets the number of octets transmitted to the client for this
FILE block. If this directive is not specified the server transmits data
until an end of file condition occurs.

length = 4096;

would send 4096 octets from the file.
linux
This directive takes no argument. It indicates to
rpld(1)
that the file specified in the path directive is a Linux kernel image.
rpld(1)
then analyses the kernel image and generates three FILE blocks corresponding
to the primary boot loader, secondary boot loader, and data portions of the image.
It then sets a default execute address which points to the secondary boot loader
which is loaded at 0x90200. The execute address may be over-ridden with an execute
directive which appears AFTER the FILE block.

linux;

rpld(1)
may have problems with bzImage kernels.
load
This directive sets the load address for this FILE block. Data is read from
offset
octets into the file at copied to the client starting at the address
specified by the load directive. The FILE block

FILE {
path = "/rplboot/fish";
offset = 512;
length = 4096;
load = 0x90200;
};

would load 4096 octets from the file
/rplboot/fish
starting 512 octets into the file into the
client’s memory starting
at address 0x90200. (so the 513th byte of the file will load to address 0x90200)
nospew
This directive causes rpld to emit only one FILE.DATA.RESPONSE frame for SEND.FILE.REQUEST frame received. The usual behaviour is the client sends one FILE.DATA.RESPONSE frame which causes the server to transmit all the FILE.DATA.RESPONSE frames
in order (see
pacing
) Some RPL boot proms have made this sensible modification to the protocol.
NB
if you
specify this directive when it is not required, most roms will send another
SEND.FILE.REQUEST frame after a timeout of about one second. Some roms will only
make twenty or so retransmits before aborting the boot.
offset
This directive sets the offset for this FILE block. Data is read from
offset
octets into the file at copied to the client starting at the address
specified by the load directive.

offset = 512;

pacing
This directive sets the minimum time gap in us between sequential frames when
the
nospew
option is NOT set. 1000 (or 1 ms) is a reasonable choice and the default.
Increase this if the client has to issue retransmits.
path
This directive sets the path to the file that is to be downloaded. The file
must exist, and is examined at startup and on reception of SEND.FILE.REQUEST
frames.

path = "/rplboot/fish";

NOTES

     The server downloads the FILE blocks in the inverse order to that in
     which they were specified. Boot ROMs typically prefer the blocks to
     arrive in decreasing load address, so you should specify them in
     increasing load address.  The server recalculates the length of all the
     files specified on reception of a SEND.FILE.REQUEST frame. If the file
     changes size during downloading the server will attempt to read to the
     original length of the file. If it encounters an end of file condition
     empty FILE DATA FRAMES will be sent. For Linux kernel images the first
     sector of the kernel image will only be read from disk when rpld is
     started. The first sector contains information such as the default root
     device and the length of secondary boot loader.  You should therefore
     restart rpld if you change the version of the kernel you are downloading.
     The order of directives is important: the execute directive, if present,
     should always come after the linux directive.

Example

     A complete example file using every directive:

     // Sample rpld.conf file
     /* (c) 1999 James McKenzie and
      *          Christopher Lightfoot
      *          All rights reserved.
      */

     HOST {
             ethernet=08:00:02:32:1e:fc;
             FILE {
                     path="/rplboot/vmlinuz";
                     linux;
             };
             FILE {
                     path="/rplboot/vesarom.img";
                     offset=0x200;
                     length=0x400;
                     load=0x92000;
             };
             execute=0x92000;
             pacing=2000;
     };

FILES

     /etc/rpld.conf  The rpld(1) configuration file.

AUTHORS AND COPYRIGHT

     (c) 1999,2000 James McKenzie, and Christopher Lightfoot. All rights
     reserved.