Adjust memory layout for 2.6.22+ kernels with 32KB setup code
[mknbi.git] / spec.txt
1   Draft Net Boot Image Proposal 0.3
2   Jamie Honan and Gero Kuhlmann, gero AT minix PERIOD han
3   PERIOD de
4   June 15, 1997
5
6   This is the specification of the "tagged image" format
7   ______________________________________________________________________
8
9   Table of Contents
10
11
12   1. Note
13
14   2. Preamble - the why
15
16   3. The target
17
18   4. Net Boot Process Description.
19
20   5. Image Format with Initial Magic Number.
21
22   6. Boot prom entry points.
23
24   7. Example of a boot image.
25
26   8. Terms
27
28   9. References
29
30
31
32   ______________________________________________________________________
33
34   1\b1.\b.  N\bNo\bot\bte\be
35
36
37   In order to provide more functionality to the boot rom code Jamie's
38   draft has been changed a little bit. All of Gero Kuhmnann's changes
39   are preceded and followed by (\b(g\bgk\bk)\b). All of Ken Yap's changes are
40   preceded and followed by (\b(k\bky\by)\b).
41
42
43
44   Gero Kuhlmann
45
46
47   2\b2.\b.  P\bPr\bre\bea\bam\bmb\bbl\ble\be -\b- t\bth\bhe\be w\bwh\bhy\by
48
49
50   Whilst researching what other boot proms do (at least those
51   implementing TCP/IP protocols) it is clear that each 'does their own
52   thing' in terms of what they expect in a boot image.
53
54
55
56   If we could all agree on working toward an open standard, O/S
57   suppliers and boot rom suppliers can build their products to this
58   norm, and be confident that they will work with each other.
59
60
61
62   This is a description of how I will implement the boot rom for Linux.
63   I  believe it to be flexible enough for any OS that will be loaded
64   when a PC boots from a network in the TCP/IP environment.
65
66
67   It would be good if this could be turned into some form of standard.
68
69
70
71   This is very much a first draft. I am inviting comment.
72
73
74
75   The ideas presented here should be independant of any implementation.
76   In the end, where there is a conflict between the final of this draft,
77   and an implementation, this description should prevail.
78
79
80
81   The terms I use are defined at the end.
82
83
84
85   (\b(g\bgk\bk)\b)IMPORTANT NOTE: The scope of this document starts at the point
86   where the net boot process gains control from the BIOS, to where the
87   booted image reaches a state from which there is no return to the net
88   boot program possible.(\b(g\bgk\bk)\b)
89
90
91   3\b3.\b.  T\bTh\bhe\be t\bta\bar\brg\bge\bet\bt
92
93
94   The target is to have a PC retrieve a boot image from a network in the
95   TCP/IP environment.
96
97
98
99   (\b(g\bgk\bk)\b)The boot may take place from a network adaptor rom, from a boot
100   floppy.(\b(g\bgk\bk)\b)
101
102
103   4\b4.\b.  N\bNe\bet\bt B\bBo\boo\bot\bt P\bPr\bro\boc\bce\bes\bss\bs D\bDe\bes\bsc\bcr\bri\bip\bpt\bti\bio\bon\bn.\b.
104
105
106   (\b(g\bgk\bk)\b)The net boot process is started as a result of the PC boot
107   process. The net boot program can reside on a rom, e.g. on an adaptor
108   card, or in ram as a result of reading off disk.(\b(g\bgk\bk)\b)
109
110
111
112   The boot process may execute in any mode (e.g. 8086, 80386) it
113   desires.  When it jumps to the start location in the boot image, it
114   must be in 8086 mode and be capable of going into any mode supported
115   by the underlying processor.
116
117
118
119   The image cannot be loaded into address spaces below 10000h(\b(k\bky\by:\b: T\bTh\bhi\bis\bs
120   r\bre\bes\bst\btr\bri\bic\bct\bti\bio\bon\bn r\bre\bem\bmo\bov\bve\bed\bd i\bin\bn E\bEt\bth\bhe\ber\brb\bbo\boo\bot\bt)\b), or between A0000h through FFFFFh,
121   or between 98000h(\b(k\bky\by:\b: C\bCh\bha\ban\bng\bge\bed\bd t\bto\bo 9\b94\b40\b00\b00\b0h\bh i\bin\bn E\bEt\bth\bhe\ber\brb\bbo\boo\bot\bt 5\b5.\b.x\bx o\bon\bnw\bwa\bar\brd\bds\bs)\b)
122   through 9FFFFh.  (\b(g\bgk\bk)\b)Only when the image is not going to return to the
123   boot process, all the memory is available to it once it has been
124   started, so it can relocate parts of itself to these areas.(\b(g\bgk\bk)\b)
125
126
127
128   The boot process must be capable of loading the image into all other
129   memory locations. Specifically, where the machine supports this, this
130   means memory over 100000h.
131
132
133   The net boot process must execute the bootp protocol, followed by the
134   tftp protocol, as defined in the relevant rfc's.
135
136
137
138   The file name used in the tftp protocol must be that given by the
139   bootp record.
140
141
142
143   If less than 512 bytes are loaded, the net boot process attempts to
144   display on the screen any ascii data at the start of the image. The
145   net boot process then exits in the normal manner. For a boot prom,
146   this will allow normal disk booting. (\b(g\bgk\bk)\b)Reference to DOS deleted.(\b(g\bgk\bk)\b)
147
148
149
150   When the first 512 bytes have been loaded, the boot process checks for
151   an initial magic number, which is defined later. If this number is
152   present, the net process continues loading under the control of the
153   image format. The image, which is described later, tells the net boot
154   process where to put this record and all subsequent data.
155
156
157
158   If no initial magic number is present the net boot process checks for
159   a second magic number at offset 510. If the magic number 510 = 55h,
160   511 = AAh, then the net process continues. If this second magic number
161   is not present, then the net boot process terminates the tftp
162   protocol, displays an error message and exits in the normal manner.
163
164
165
166   If no initial magic number is present and the second one is, the net
167   boot process relocates the 512 bytes to location 7c00h. The net boot
168   process continues to load any further image data to 10000h up. This
169   data can overwrite the first 512 boot bytes. If the image reaches
170   98000h, then any further data is continued to be loaded above 100000h.
171   When all the data has been loaded, the net boot process jumps to
172   location 0:7c00.(\b(k\bky\by)\b)N\bNo\bo l\blo\bon\bng\bge\ber\br s\bsu\bup\bpp\bpo\bor\brt\bte\bed\bd i\bin\bn E\bEt\bth\bhe\ber\brb\bbo\boo\bot\bt(\b(k\bky\by)\b)
173
174
175
176   (\b(g\bgk\bk)\b)When the net boot program calls the image, it places 2 far
177   pointers onto the stack, in standard intel order (e.g.  segment:offset
178   representation).  The first far pointer which immediately follows the
179   return address on the stack, points to the loaded boot image header.
180   The second far pointer which is placed above the first one, shows to
181   the memory area where the net boot process saved the bootp reply.
182
183
184
185   If the boot image is flagged as being returnable to the boot process,
186   the boot program has to provide the boot image with interrupt vector
187   78h. It's an interface to services provided by the net boot program
188   (see below for further description).
189
190
191
192   If the boot image is not flagged as being returnable to the boot
193   process, before the boot image is called, the boot program has to set
194   the system into a state in which it was before the net boot process
195   has started.(\b(g\bgk\bk)\b)
196
197
198
199   5\b5.\b.  I\bIm\bma\bag\bge\be F\bFo\bor\brm\bma\bat\bt w\bwi\bit\bth\bh I\bIn\bni\bit\bti\bia\bal\bl M\bMa\bag\bgi\bic\bc N\bNu\bum\bmb\bbe\ber\br.\b.
200
201
202   The first 512 bytes of the image file contain the image header, and
203   image loading information records. This contains all the information
204   needed by the net boot process as to where data is to be loaded.
205
206   The magic number (in time-honoured tradition (well why not?)) is:
207
208
209   ______________________________________________________________________
210           0 = 36h
211           1 = 13h
212           2 = 03h
213           3 = 1Bh
214   ______________________________________________________________________
215
216
217
218   Apart from the two magic numbers, all words and double words are in PC
219   native endian.
220
221
222
223   Including the initial magic number the header record is:
224
225
226   ______________________________________________________________________
227           +---------------------+
228           |                     |
229           | Initial Magic No.   |  4 bytes
230           +---------------------+
231           |                     |
232           | Flags and length    |  double word
233           +---------------------+
234           |                     |
235           | Location Address    |  double word in ds:bx format
236           +---------------------+
237           |                     |
238           | Execute Address     |  double word in cs:ip format
239           +---------------------+
240   ______________________________________________________________________
241
242
243
244   The Location address is where to place the 512 bytes. The net boot
245   process does this before loading the rest of the image. The location
246   address cannot be one of the reserved locations mentioned above, but
247   must be an address lower than 100000h.
248
249
250
251   The rest of the image must not overwrite these initial 512 bytes,
252   placed at the required location. The writing of data by the net boot
253   process into these 512 bytes is deprecated. These 512 bytes must be
254   available for the image to interogate once it is loaded and running.
255
256
257
258   The execute address is the location in cs:ip of the initial
259   instruction once the full image has been loaded. This must be lower
260   than 100000h, since the initial instructions will be executed in 8086
261   mode. When the jump (actually a far call) is made to the boot image,
262   the stack contains a far return address, with a far pointer parameter
263   above that, pointing to the location of this header.
264
265   (\b(k\bky\by)\b) If bit 31 in the flags is set, then the execute address is
266   interpreted as a linear 32-bit address, and a call is made to this
267   address. There is no restriction on the range of the execute address.
268   The arguments to the routine are: a pointer to an Etherboot specific
269   header, a pointer to the tagged image header, and a pointer to the
270   bootp reply.  The called routine may return to the boot loader.(\b(k\bky\by)\b)
271
272
273
274   The flags and length field is broken up in the following way:
275
276
277
278   Bits 0 to 3 (lowest 4 bits) define the length of the non-vendor header
279   in double words. Currently the value is 4.
280
281
282
283   Bits 4 to 7 define the length required by the vendor extra information
284   in double words. A value of zero indicates no extra vendor
285   information.
286
287
288
289   (\b(g\bgk\bk)\b)Bit 8 is set if the boot image can return to the net boot process
290   after execution. If this bit is not set the boot image does never
291   return to the net boot process, and the net boot program has to set
292   the system into a clean state before calling the boot image.(\b(g\bgk\bk)\b)
293
294   (\b(k\bky\by)\b)Bit 31 is set if the execute address of the boot image is a linear
295   32-bit address to be called. The boot image may return to the boot
296   loader.(\b(k\bky\by)\b)
297
298
299
300   (\b(g\bgk\bk+\b+k\bky\by)\b)Bits 9 to 30 are reserved for future use and must be set to
301   zero.(\b(g\bgk\bk+\b+k\bky\by)\b)
302
303
304
305   After this header, and any vendor header, come the image loading
306   information records. These specify where data is to be loaded, how
307   long it is, and communicates to the loaded image what sort of data it
308   is.
309
310
311
312   The format of each image loading information record is :
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331   ______________________________________________________________________
332             +---------------------+
333             | Flags, tags and     |  double word
334             | lengths             |
335             +---------------------+
336             |                     |
337             | Load Address        |  double word
338             +---------------------+
339             |                     |
340             | Image Length        |  double word
341             +---------------------+
342             |                     |
343             | Memory Length       |  double word
344             +---------------------+
345   ______________________________________________________________________
346
347
348
349   Each image loading information record follows the previous, or the
350   header.
351
352
353
354   The memory length, image length and load address fields are unsigned
355   32 numbers. They do not have the segment:offset format used by the
356   8086.
357
358
359
360   The flags, tags and lengths field is broken up as follows:
361
362
363
364   Bits 0 to 3 (lowest 4 bits) are the length of the non vendor part of
365   this header in double words. Currently this value is 4.
366
367
368
369   Bits 4 to 7 indicate the length of any vendor information, in double
370   words.
371
372
373
374   Bits 8 to 15 are for vendor's tags. The vendor tag is a private number
375   that the loaded image can use to determine what sort of image is at
376   this particular location.
377
378
379
380   Bits 16 to 23 are for future expansion and should be set to zero.
381
382
383
384   Bits 24 to 31 are for flags, which are defined later.
385
386
387
388   Vendors may place further information after this information record,
389   and before the next. Each information record may have a different
390   vendor length.
391
392
393
394   There are two restrictions on vendor information.
395
396
397   One is that the header and all information records that the net boot
398   process is to use fall within the first 512 bytes.
399
400
401
402   The second restriction is that the net boot process must ignore all
403   vendor additions. The net boot process may not overwrite vendor
404   supplied information, or other undefined data in the initial 512
405   bytes.
406
407
408
409   The flags are used to modify the load address field, and to indicate
410   that this is the last information record that the net boot process
411   should use.
412
413
414
415   Bit 24 works in conjunction with bit 25 to specify the meaning of the
416   load address.
417
418
419   ______________________________________________________________________
420             B24    B25
421
422              0     0    load address is an absolute 32 number
423
424              1     0    add the load address to the location one past the last byte
425                         of the memory area required by the last image loaded.
426                         If the first image, then add to 512 plus the location
427                         where the 512 bytes were placed
428
429              0     1    subtract the load address from the one past the
430                         last writeable location in memory. Thus 1 would
431                         be the last location one could write in memory.
432
433              1     1    load address is subtracted from the start of
434                         the last image loaded. If the first image, then
435                         subtract from the start of where the 512 bytes were
436                         placed
437   ______________________________________________________________________
438
439
440
441   (For convenience bit 24 is byte 0 of the flag field)
442
443
444
445   Bit 26 is the end marker for the net boot process. It is set when this
446   is the last information record the net boot process should look at.
447   More records may be present, but the net boot process will not look at
448   them. (Vendors can continue information records out past the 512
449   boundary for private use in this manner).
450
451
452
453   The image length tells the net boot process how many bytes are to be
454   loaded.  Zero is a valid value. This can be used to mark memory areas
455   such as shared memory for interprocessor communication, flash eproms,
456   data in eproms.
457
458
459
460   The image length can also be different from the memory length. This
461   allows decompression programs to fluff up the kernel image. It also
462   allows a file system to be larger then the loaded file system image.
463   Bits 27 through 31 are not defined as yet and must be set to zero
464   until they are.
465
466
467   6\b6.\b.  B\bBo\boo\bot\bt p\bpr\bro\bom\bm e\ben\bnt\btr\bry\by p\bpo\boi\bin\bnt\bts\bs.\b.
468
469
470   (\b(g\bgk\bk)\b)As mentioned above the net boot process has to provide interrupt
471   78h as an entry point in case, the returnable flag (bit 9 of the flags
472   field in the image header) of the boot image has been set.  When
473   calling this interface interrupt, the caller has to load the AH
474   register with a value indicating the type of operation requested:
475
476
477   ______________________________________________________________________
478          00h  -  Installation check
479                  Input:  none
480                  Output: AX  -  returns the value 474Bh
481                          BX  -  flags indicating what further services are
482                                 provided by the net boot program:
483                                  Bit 0 - packet driver interface (see below)
484                                  Bits 1 to 15 are unused and have to be zero
485
486          01h  -  Cleanup and terminate the boot process services. This will
487                  also remove the services provided by interrupt 87h.
488                  Input:  none
489                  Output: none
490   ______________________________________________________________________
491
492
493
494
495
496   Further functions are not yet defined. These functions are only
497   available to boot images which have the first magic number at the
498   beginning of the image header, and have the returnable flag set in the
499   flags field.
500
501
502
503   In order to provide compatibility with net boot programs written to
504   match an earlier version of this document, the loaded image should
505   check for the existence of interrupt 78h by looking at it's vector. If
506   that's 0:0, or if it does not return a proper magic ID after calling
507   the installation check function, the boot image has to assume that the
508   net boot program does not support this services interrupt.
509
510
511
512   If the bit 0 of register BX of function 00h is set, the boot program
513   has to provide a packet driver <http://www.crynwr.com> interface at
514   interrupt 79h as described in the packet driver interface standard,
515   version 1.09, published by FTP Software, Inc., which is not repeated
516   here. It serves as an interface to the system's network card. It is
517   important to note that the net boot process has to provide a clean
518   packet driver interface without any handles being defined when the
519   boot image gets started. It is expected that the boot image sets up
520   it's own TCP/IP or other network's stack on top of this packet driver
521   interface.  When the boot image returns to the net boot process, it
522   has to return a clean packet driver interface as well, without any
523   handles being defined.(\b(g\bgk\bk)\b)
524
525
526
527
528
529   7\b7.\b.  E\bEx\bxa\bam\bmp\bpl\ble\be o\bof\bf a\ba b\bbo\boo\bot\bt i\bim\bma\bag\bge\be.\b.
530
531
532   Here is an example of how the boot image would look for Linux:
533
534
535   ______________________________________________________________________
536             0x1B031336,  /* magic number */
537             0x4,         /* length of header is 16 bytes, no vendor info */
538             0x90000000,  /* location in ds:bx format */
539             0x90000200,  /* execute address in cs:ip format */
540
541                          /* 2048 setup.S bytes */
542             0x4,         /* flags, not end, absolute address, 16 bytes this
543                             record, no vendor info */
544             0x90200,     /* load address - note format */
545             0x800,       /* 4 8 512 byte blocks for linux */
546             0x800,
547
548                          /* kernel image */
549             0x4,         /* flags, not end, absolute address, 16 bytes this
550                             record, no vendor info */
551             0x10000,     /* load address - note format */
552             0x80000,     /* 512K (this could be shorter */
553             0x80000,
554
555                          /* ramdisk for root file system */
556             0x04000004,  /* flags = last, absolute address, 16 bytes this
557                             record, no vendor info *//
558             0x100000,    /* load address - in extended memory */
559             0x80000,     /* 512K for instance */
560             0x80000,
561
562                          /* Then follows linux specific information */
563   ______________________________________________________________________
564
565
566
567
568   8\b8.\b.  T\bTe\ber\brm\bms\bs
569
570
571   When I say 'the net boot process', I mean the act of loading the image
572   into memory, setting up any tables, up until the jump to the required
573   location in the image.
574
575
576
577   The net booting program executes the net boot process. The net boot
578   program may be a rom, but not neccassarily. It is a set of
579   instructions and data residing on the booting machine.
580
581
582
583   The image, or boot image,  consists of the data loaded by the net boot
584   process.
585
586
587
588   When I say 'the PC boot process', I mean the general PC rom bios boot
589   process, the setting up of hardware, the scanning for adaptor roms,
590   the execution of adaptor roms, the loading in of the initial boot
591   track. The PC boot process will include the net boot process, if one
592   is present.
593
594
595   When I say client, I mean the PC booting up.
596
597
598
599   When I say 'image host', I mean the host where the boot image is
600   comming from.  This may not have the same architecture as the client.
601
602
603
604   The bootp protocol is defined in RFC951 and RFC1084. The tftp protocol
605   is defined in RFC783. These are available on many sites.  See Comer
606   1991 for details on how to obtain them.
607
608
609
610   A bootp server is the machine that answers the bootp request. It is
611   not neccessarily the image host.
612
613
614
615   "Can" and "may" means doesn't have to, but is allowed to and might.
616   "Must" means just that. "Cannot" means must not.
617
618
619   9\b9.\b.  R\bRe\bef\bfe\ber\bre\ben\bnc\bce\bes\bs
620
621
622   Comer, D.E. 1991, Internetworking with TCP/IP Vol I: Principles,
623   Protocols, and Architecture Second Edition, Prentice Hall, Englewood
624   Cliffs, N.J., 1991
625
626
627
628   Stevens, W.R 1990, Unix Network Programming, Prentice Hall, Englewood
629   Cliffs, N.J., 1990
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660