home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / system / linux_bo / netboot.zoo / readme < prev    next >
Encoding:
Text File  |  1993-05-06  |  10.3 KB  |  318 lines
  1.  
  2. `I don't want to read this stuff, I just want to get it working! '
  3.  
  4. Go to the QUICKSTART section below. Then come back here when you
  5. get stuck.
  6.  
  7. This is:
  8. -------
  9.  
  10. This archive contains the source files for the network
  11. boot program.
  12.  
  13. The network boot program allows the booting of 386 PC's from
  14. a host running TCP/IP protocols.
  15.  
  16. Two protocols are used: bootp and tftp.
  17.  
  18. The network boot program can be used in one of three ways:
  19.  
  20.     - as a prom on a network adaptor card
  21.     - as the boot program on a floppy disk
  22.     - as an MSDOS program, run first thing after booting
  23.  
  24. Requirements:
  25. -------------
  26.  
  27. In order to use this program you will need to set up your host with
  28. the bootpd server and the tftpd server. Typically, this would be a
  29. Unix host.
  30.  
  31. You will need to have a suitable network adaptor. At the moment I have
  32. only ported the WD Ethernet card code from the original NCSA suite of
  33. programs. The original drivers are provided, you can use the WD
  34. code as a template for your changes.
  35.  
  36. This code has been written for Turbo C and Turbo assembler.
  37.  
  38. Features:
  39. ---------
  40.  
  41. This code implements my draft specification for network boot
  42. images. This specification is in the file 'spec.doc'. This defines
  43. a vendor independent format for boot images.
  44.  
  45. The code is written without any library calls, that is, all string,
  46. print etc. functions are included.
  47.  
  48. The network boot program is able to load data into memory locations
  49. above the 1 Meg barrier.
  50.  
  51. The code demonstrates how rom code can be generated from C.
  52.  
  53. Acknowledgements:
  54. -----------------
  55.  
  56. This code grew out of the NCSA Telnet suite of programs. Although
  57. it is now quite different, the roots can easily be seen. In particular, the
  58. use of their adaptor interface code is important.
  59.  
  60. Copyright:
  61. ---------
  62.  
  63. In so far as this work represents changes to the original NCSA Telnet
  64. code, these changes are Copyright Jamie Honan.
  65.  
  66. These changes may be freely distributed, sold, or modified. Acknowledgement
  67. of my work is appreciated.
  68.  
  69. The original work that is by NCSA, I believe to have been made
  70. available under similar arrangements, but you should check this out
  71. yourself. I make no warranty or representation about the original work.
  72.  
  73. This software is made available as is. That is, I make no warranty about
  74. its fitness of purpose, its correctness or suitability.
  75.  
  76. This is free software. I make no guarantee about support.
  77.  
  78. In particular I am not responsible for subsequent damages. You use this
  79. software entirely at your own risk.
  80.  
  81. QUICKSTART:
  82. ----------
  83.  
  84. If you have a WD or SMC Ethernet adaptor a floppy bootable test image
  85. is set up for you.
  86.  
  87. Simply use rawrite (in DOS) or dd (in Unix) to write fimage.bin onto a blank
  88. formatted floppy (careful - it erases any data on your floppy), then boot
  89. from your floppy.
  90.  
  91. Assuming you have a bootp and tftp server running, booting will start.
  92.  
  93. Files:
  94. ------
  95.  
  96. makefile    The controlling file
  97.  
  98. arp.c        handles arp requests
  99. bootp.c        handles bootp protocol
  100. decoder.c    handles decoding and placing the image
  101. general.c    general routines
  102. ip.c        ip layer, also handles icmp
  103. net.c        interface to the Ethernet driver software
  104. tftp.c        tftp (trivial file transfer protocol)
  105. udp.c        udp packet decoding / encoding
  106.  
  107. bootinc.h    function definitions
  108. config.h    various parameters you may tweak for local conditions
  109.  
  110. bootp.h        specific to bootp
  111. dos.mac        (historical)
  112. protocol.h    protocol headers
  113. whatami.h
  114.  
  115. asmstuff.asm    general routines in assembler
  116. string.c    string type routines
  117. utils.h        function definitions for two above
  118.  
  119. romstart.c    C start code for PROM and boot floppy
  120. booter.c    (obsolete) C start code for MSDOS
  121.  
  122. layout.asm    A dummy module for the MSDOS version
  123.  
  124. rom.asm        Start code for PROM and boot floppy and DOS
  125. layout.inc    Segment ordering
  126.  
  127. newdrive\    directory containing Ethernet interface code
  128.  
  129. origdriv\    directory containing originial interface code
  130.  
  131. dummy1.asm    dummy code for a boot image for testing
  132. dummy2.asm
  133.  
  134. floboot.asm    boot code for first sector of boot floppy
  135.  
  136. tools:
  137.  
  138. rawrite.exe    freely available program to write image onto floppy.
  139. hexbin.c
  140. hexbin.exe    program to write data for prom programmer (credit T.Bohning)
  141. dosum.exe    creates checksum for boot prom
  142. dosum.c
  143.  
  144. executable:
  145.  
  146. fimage.bin    floppy image for WD's /  SMC ethernet cards
  147.         use rawrite (in DOS) or dd (in Linux) to put onto a floppy
  148.  
  149. fimage0.bin    same image as above but for an ip broadcast address
  150.         of all zeroes
  151.  
  152. booter.com    replacement for command.com in a DOS system
  153.  
  154. How to make various targets:
  155. ----------------------------
  156.  
  157. 1. For all targets, as of this date, you will need to port your particular
  158. adaptor code. If you have a WD 8003E or 8013 or SMC Elite, then you are in
  159. luck, this has been done already. You simply type
  160.  
  161.     make net8003
  162.  
  163. For the others, you must get the original NCSA telnet sources and port. A
  164. start was made with net3com, but since I don't have one of these adaptors, 
  165. it is untested.
  166.  
  167. The modifications are
  168.     a. Public procedures use the START_PROC, END_PROC macros
  169.        provided in model.inc
  170.     b. Any interrupt routines are placed in the data segment, where
  171.        they can store variables using the CS register. There is usually
  172.        some minor modification to achieve this. Any other use of storing
  173.        data using the CS register must be changed.
  174.     c. Net.c must be updated with the new definitions
  175.     d. The makefile and config.h must also be modified
  176.  
  177. 2. To make a boot floppy.
  178.  
  179. After configuring for your Ethernet adaptor, you type 
  180.  
  181.     make fimage.bin
  182.  
  183. You then use rawrite or dd to write this onto a boot floppy disk.
  184.  
  185. Fimage.bin consists of two modules; floboot.bin and florom.bin.
  186.  
  187. The boot floppy requires code in the initial sector which is loaded at 0:7c00h.
  188. This is floboot.bin, made from floboot.asm. This code reads the next 32K out of
  189. the following sectors and executes. This second piece of code is florom.bin.
  190.  
  191. 3. To make an MSDOS program.
  192.  
  193. After configuring for your Ethernet adaptor, you type 
  194.  
  195.     make booter.com
  196.     
  197. The MSDOS program must load below 10000h. The intention here is not to
  198. let you run MS-Windows, do some work in DOS and then net boot. The aim
  199. here is to allow you to run some program which configures your hardware,
  200. for which there is no other way.
  201.  
  202. To run your program, you should place a line like:
  203.  
  204.     shell=a:\booter.com
  205.     
  206. in your config.sys file.
  207.  
  208. Once booter.com is run, DOS is generally scribbled over in memory.
  209.  
  210. 4. A Prom
  211.  
  212. After configuring for your ethernet adaptor, you type 
  213.  
  214.     make  rom.hex
  215.  
  216. This makes the rom image rom.bin. The dosum program creates a checksum.
  217. The hexbin program writes out data for a prom programmer.
  218.  
  219. What if it doesn't work?
  220. ------------------------
  221.  
  222. 1. First, work from a boot floppy version. 
  223. Does the floppy boot? It should produce a message when it does.
  224.  
  225. 2. Does the bootp protocol work? When the program starts, you can press
  226. 'd' to toggle the debug flag. This will produce lots of debugging information.
  227.  
  228. If bootp is not working, does anything go out the Ethernet wire? Do you
  229. have a tracer program. You can use ka9qnos on another PC to trace packets.
  230.  
  231. If packets go out, maybe the problem is on the Unix server. Does the host
  232. respond? Is the bootp daemon working? You can use the syslogd to see logged
  233. messages. If the bootpd program is running (use ps -ax on Linux to see all
  234. processes) then you can be reasonably sure that a bootp request has been seen.
  235. Bootpd stays active for about 15 minutes after initial activation.
  236. Are the entries in the bootptab correct? Are the entries in inetd.conf correct?
  237.  
  238. Do you have an early (pre 99.9, pre Net2) version of Linux, which has the ip
  239. broadcast address set to zeroes (if so, use fimage0.bin).
  240.  
  241. 3. If bootp is working, you're about 95% there. Does tftp (the file transfer)
  242. work? Is there a boot file. Does it have world read permissions, and the
  243. directory have world read permission. Again you can use syslogd. Again check
  244. inetd.conf.
  245.  
  246. 4. If you still can't get it to work, write down the major debugging
  247. messages when you toggle debug, and try to mail me below.
  248.  
  249. Please note the following:
  250.  
  251.     nobody is paying me to do this
  252.     service is entirely at my discretion
  253.     I am interested in genuine problems (where you have
  254.     sincerely tried yourself) and will try to help.
  255.     abuse will be silently ignored
  256.  
  257. Notes on the code:
  258. ------------------
  259.  
  260. This section is to help you should you desire to understand the code
  261. in a deeper way, and to present some design issues.
  262.  
  263. The code is written without any library calls, that is, all string,
  264. print etc. functions are included.
  265.  
  266. The reason for this is that I wanted to have a totally romable program.
  267. In order to produce one for a network adaptor, the prom should be
  268. able to be placed anywhere the adaptor allows, with the segment address
  269. configured by jumpers on the adaptor card.
  270.  
  271. Thus there must be no far calls, no segment addresses 'burnt into' the
  272. program.
  273.  
  274. This is also the reason there are no implicit long multiplies and divides.
  275.  
  276. You can tell if you've gone wrong here by running programs like locate
  277. or exe2hex on the exe file (before exe2bin). If segment fixup records are
  278. present then you've got segment information (actually, thinking about it
  279. exe2bin would probably barf too).
  280.  
  281. In addition, I tried to make the code such that the stack segment register
  282. did not have to be the same as the data segment register.
  283.  
  284. The main way this is achieved is not to make a pointer out of automatic
  285. variables. You may see this in the code, but I have only done it at
  286. points where I want the stack offset.
  287.  
  288. The map files produced during linking give a very good indication of
  289. segment layout. Be very careful with this layout. It interacts with
  290. code in rom.asm, which sets up the data segment and clears bss. The
  291. segment layout is different between the DOS version and the boot images.
  292. Layout is controlled by layout.inc.
  293.  
  294. Bugs:
  295. -----
  296.  
  297. Lots.
  298.  
  299. At the moment there is one bug I can't find. If Linux starts running, the
  300. PC requires a hard reset before my boot code will work. A software
  301. reset is not enough. (This is for the WD adaptor).
  302.  
  303. I haven't (ahem) actually burnt a prom.
  304.  
  305. Contact:
  306. --------
  307.  
  308. You can try
  309.  
  310.    jhonan@kralizec.zeta.org.au
  311.  
  312. I make my living doing consulting or contract programming work. If you
  313. have a special network adaptor you'd like to have a boot rom for, or
  314. for any code you'd like written, why don't you contact me?
  315.  
  316. Jamie Honan, May 1993
  317.  
  318.