http://gimel.esc.cam.ac.uk/james/rpld/src/rpld-1.4.tar.gz
[rpld.git] / doc / rpld.conf.5
1
2 RPLD.CONF(5)              System Programmer's Manual              RPLD.CONF(5)
3
4 NAME
5      rpld.conf - rpld configuration file
6
7 DESCRIPTION
8      The rpld.conf file is the configuration file for the rpld(1) program.  It
9      consists of a number of HOST blocks of the form:
10
11      HOST {
12           ...
13      };
14
15      Within the HOST blocks there can be ethernet, execute, framesize, block-
16      size, nospew, and pacing  directives and FILE blocks.  FILE blocks are of
17      the form:
18
19              FILE {
20                   ...
21              };
22
23      Within FILE blocks there can be path, offset, length, load and linux di-
24      rectives.  Directives are of the form
25
26              foo = something;
27      or
28
29              bar;
30
31      and are detailed below. Comments are allowed in the configuration file
32      and can either be in C-form (i.e. starting with /* and ending with */) or
33      C++ form (starting with // and ending at the line break).
34
35 DIRECTIVES
36      Directives are of the form
37
38              foo = something;
39      or
40
41              bar;
42
43      If something is a string it should be entered between quotes. Numbers are
44      assumed to be decimal unless preceded by 0x in which case they are inter-
45      preted in hexadecimal. MAC addresses should be given as 6 octets in hex-
46      adecimal without the leading 0x. The octets should be separated by
47      colons.
48
49              number = 131;
50              hexnumber = 0x7382;
51              macaddr = 08:00:02:43:21:22;
52              string = "fish soup";
53
54      blocksize
55        This directive sets the maximum size in octets of data that is trans-
56        mitted in each FILE.DATA.RESPONSE frame that the server sends. The
57        block size should be at least 48 octets smaller than the frame size.
58        After the client negotiates a frame size the block size is checked and
59        if it is no longer 48 octets smaller than frame size it is adjusted ac-
60        cordingly. Some buggy boot ROMs will fail if block size is not a multi-
61        ple of four, accordingly you should be aware of the situation that
62        could arise if the client was to negotiate the block size down to some-
63        thing that wasn't a multiple of four.
64
65                blocksize = 528;
66
67      ethernet
68        This directive sets the MAC address of the client referenced in this
69        HOST block. It should either be formatted as six octets separated by
70        colons. e.g..
71
72                ethernet = 00:60:6e:33:4f:2c;
73
74        or it can be specified as a range of mac addresses as six octets sepa-
75        rated by colons followed by a solidus and the number of bytes to match.
76        So:
77
78                ethernet = 00:50:32:33:00:00/4;
79
80        Will match anything of the form 00:50:32:33:xx:xx. It is expected that
81        this support will be changed from bytes to bits in a future release.
82
83      execute
84        This directive sets the execute address that control is transferred to
85        when downloading has finished. It should be a number in either decimal
86        or hexadecimal.
87
88                execute = 0x92000;
89
90        It is not clear whether or not the client's Ethernet adapter is or
91        should be shut down prior to the transfer of control. This may cause
92        problems on systems where the Ethernet adapter in the client can do DMA
93        directly into host memory. As the adapter may continue writing to the
94        buffers that the boot ROM set up, it may be necessary to download a
95        small program to reset the Ethernet adapter. See code under the nics/
96        directory in the source distribution for examples.
97      framesize
98        This directive sets the maximum size of the frames that the server uses
99        to communicate with the client. The actual frame size used is negotiat-
100        ed between the client and the server, the server will force the client
101        to use this value if it requests a larger one. The maximum frame size
102        that Ethernet can support is 1500, and this is the default value.
103
104                framesize = 576;
105
106      length
107        This directive sets the number of octets transmitted to the client for
108        this FILE block. If this directive is not specified the server trans-
109        mits data until an end of file condition occurs.
110
111                length = 4096;
112
113        would send 4096 octets from the file.
114      linux
115        This directive takes no argument. It indicates to rpld(1) that the file
116        specified in the path directive is a Linux kernel image.  rpld(1) then
117        analyses the kernel image and generates three FILE blocks corresponding
118        to the primary boot loader, secondary boot loader, and data portions of
119        the image.  It then sets a default execute address which points to the
120        secondary boot loader which is loaded at 0x90200. The execute address
121        may be over-ridden with an execute directive which appears AFTER the
122        FILE block.
123
124                linux;
125
126        rpld(1) may have problems with bzImage kernels.
127      load
128        This directive sets the load address for this FILE block. Data is read
129        from offset octets into the file at copied to the client starting at
130        the address specified by the load directive. The FILE block
131
132        FILE {
133                path = "/rplboot/fish";
134                offset = 512;
135                length = 4096;
136                load = 0x90200;
137        };
138
139        would load 4096 octets from the file /rplboot/fish starting 512 octets
140        into the file into the client's memory starting at address 0x90200. (so
141        the 513th byte of the file will load to address 0x90200)
142      nospew
143        This directive causes rpld to emit only one FILE.DATA.RESPONSE frame
144        for SEND.FILE.REQUEST frame received. The usual behaviour is the client
145        sends one FILE.DATA.RESPONSE frame which causes the server to transmit
146        all the FILE.DATA.RESPONSE frames in order (see pacing ) Some RPL boot
147        proms have made this sensible modification to the protocol.  NB if you
148        specify this directive when it is not required, most roms will send an-
149        other SEND.FILE.REQUEST frame after a timeout of about one second. Some
150        roms will only make twenty or so retransmits before aborting the boot.
151      offset
152        This directive sets the offset for this FILE block. Data is read from
153        offset octets into the file at copied to the client starting at the ad-
154        dress specified by the load directive.
155
156                offset = 512;
157
158      pacing
159        This directive sets the minimum time gap in us between sequential
160        frames when the nospew option is NOT set. 1000 (or 1 ms) is a reason-
161        able choice and the default.  Increase this if the client has to issue
162        retransmits.
163      path
164        This directive sets the path to the file that is to be downloaded. The
165        file must exist, and is examined at startup and on reception of
166        SEND.FILE.REQUEST frames.
167
168                path = "/rplboot/fish";
169
170
171 NOTES
172      The server downloads the FILE blocks in the inverse order to that in
173      which they were specified. Boot ROMs typically prefer the blocks to ar-
174      rive in decreasing load address, so you should specify them in increasing
175      load address.  The server recalculates the length of all the files speci-
176      fied on reception of a SEND.FILE.REQUEST frame. If the file changes size
177      during downloading the server will attempt to read to the original length
178      of the file. If it encounters an end of file condition empty FILE DATA
179      FRAMES will be sent. For Linux kernel images the first sector of the ker-
180      nel image will only be read from disk when rpld is started. The first
181      sector contains information such as the default root device and the
182      length of secondary boot loader.  You should therefore restart rpld if
183      you change the version of the kernel you are downloading. The order of
184      directives is important: the execute directive, if present, should always
185      come after the linux directive.
186
187
188 Example
189      A complete example file using every directive:
190
191      // Sample rpld.conf file
192      /* (c) 1999 James McKenzie and
193       *          Christopher Lightfoot
194       *          All rights reserved.
195       */
196
197      HOST {
198              ethernet=08:00:02:32:1e:fc;
199              FILE {
200                      path="/rplboot/vmlinuz";
201                      linux;
202              };
203              FILE {
204                      path="/rplboot/vesarom.img";
205                      offset=0x200;
206                      length=0x400;
207                      load=0x92000;
208              };
209              execute=0x92000;
210              pacing=2000;
211      };
212
213
214 FILES
215      /etc/rpld.conf  The rpld(1) configuration file.
216
217 SEE ALSO
218      rpld(1),  bootpd(1),  dhcpd(1),  http://gimel.esc.cam.ac.uk/james/rpld;
219
220 AUTHORS AND COPYRIGHT
221      (c) 1999,2000 James McKenzie, and Christopher Lightfoot. All rights re-
222      served.
223
224  Linux                           Jun 16, 2000                                4