
							2-28-1995 (gero)

I changed the WD initialization code and boot rom startup code, because
this boot program didn't work in an actual EPROM. Besides that, the WD
driver now determines the card address etc. by itself, so it's no longer
necessary to edit config.h. However, this only applies to the WD80*3 driver,
not to the 3com or any other driver in this archive. I also fixed a couple
of minor bugs. For example, the bootp code didn't set the prefered vendor
magic ID in the outgoing request.

Below is the original README.

Gero Kuhlmann

===============================================================================

`I don't want to read this stuff, I just want to get it working! '

Go to the QUICKSTART section below. Then come back here when you
get stuck.

This is:
-------

This archive contains the source files for the network
boot program.

The network boot program allows the booting of 386 PC's from
a host running TCP/IP protocols.

Two protocols are used: bootp and tftp.

The network boot program can be used in one of three ways:

	- as a prom on a network adaptor card
	- as the boot program on a floppy disk
	- as an MSDOS program, run first thing after booting

Requirements:
-------------

In order to use this program you will need to set up your host with
the bootpd server and the tftpd server. Typically, this would be a
Unix host.

You will need to have a suitable network adaptor. At the moment I have
only ported the WD Ethernet card code from the original NCSA suite of
programs. The original drivers are provided, you can use the WD
code as a template for your changes.

This code has been written for Turbo C and Turbo assembler.

Features:
---------

This code implements my draft specification for network boot
images. This specification is in the file 'spec.doc'. This defines
a vendor independent format for boot images.

The code is written without any library calls, that is, all string,
print etc. functions are included.

The network boot program is able to load data into memory locations
above the 1 Meg barrier.

The code demonstrates how rom code can be generated from C.

Acknowledgements:
-----------------

This code grew out of the NCSA Telnet suite of programs. Although
it is now quite different, the roots can easily be seen. In particular, the
use of their adaptor interface code is important.

Copyright:
---------

In so far as this work represents changes to the original NCSA Telnet
code, these changes are Copyright Jamie Honan.

These changes may be freely distributed, sold, or modified. Acknowledgement
of my work is appreciated.

The original work that is by NCSA, I believe to have been made
available under similar arrangements, but you should check this out
yourself. I make no warranty or representation about the original work.

This software is made available as is. That is, I make no warranty about
its fitness of purpose, its correctness or suitability.

This is free software. I make no guarantee about support.

In particular I am not responsible for subsequent damages. You use this
software entirely at your own risk.

QUICKSTART:
----------

If you have a WD or SMC Ethernet adaptor a floppy bootable test image
is set up for you.

Simply use rawrite (in DOS) or dd (in Unix) to write fimage.bin onto a blank
formatted floppy (careful - it erases any data on your floppy), then boot
from your floppy.

Assuming you have a bootp and tftp server running, booting will start.

Files:
------

makefile	The controlling file

arp.c		handles arp requests
bootp.c		handles bootp protocol
decoder.c	handles decoding and placing the image
general.c	general routines
ip.c		ip layer, also handles icmp
net.c		interface to the Ethernet driver software
tftp.c		tftp (trivial file transfer protocol)
udp.c		udp packet decoding / encoding

bootinc.h	function definitions
config.h	various parameters you may tweak for local conditions

bootp.h		specific to bootp
protocol.h	protocol headers
whatami.h

asmstuff.asm	general routines in assembler
string.c	string type routines
utils.h		function definitions for two above

romstart.c	C start code for PROM and boot floppy
booter.c	(obsolete) C start code for MSDOS

layout.asm	A dummy module for the MSDOS version

rom.asm		Start code for PROM and boot floppy and DOS
layout.inc	Segment ordering

newdrive\	directory containing Ethernet interface code

origdriv\	directory containing originial interface code

dummy1.asm	dummy code for a boot image for testing
dummy2.asm

floboot.asm	boot code for first sector of boot floppy

tools:

rawrite.exe	freely available program to write image onto floppy.
hexbin.c
hexbin.exe	program to write data for prom programmer (credit T.Bohning)
dosum.exe	creates checksum for boot prom
dosum.c

executable:

fimage.bin	floppy image for WD's /  SMC ethernet cards
		use rawrite (in DOS) or dd (in Linux) to put onto a floppy

booter.com	replacement for command.com in a DOS system

How to make various targets:
----------------------------

1. For all targets, as of this date, you will need to port your particular
adaptor code. If you have a WD 8003E or 8013 or SMC Elite, then you are in
luck, this has been done already. You simply type

	make net8003

For the others, you must get the original NCSA telnet sources and port. A
start was made with net3com, but since I don't have one of these adaptors, 
it is untested.

The modifications are
	a. Public procedures use the START_PROC, END_PROC macros
	   provided in model.inc
	b. Any interrupt routines are placed in the data segment, where
	   they can store variables using the CS register. There is usually
	   some minor modification to achieve this. Any other use of storing
	   data using the CS register must be changed.
	c. Net.c must be updated with the new definitions
	d. The makefile and config.h must also be modified

2. To make a boot floppy.

After configuring for your Ethernet adaptor, you type 

	make fimage.bin

You then use rawrite or dd to write this onto a boot floppy disk.

Fimage.bin consists of two modules; floboot.bin and florom.bin.

The boot floppy requires code in the initial sector which is loaded at 0:7c00h.
This is floboot.bin, made from floboot.asm. This code reads the next 32K out of
the following sectors and executes. This second piece of code is florom.bin.

3. To make an MSDOS program.

After configuring for your Ethernet adaptor, you type 

	make booter.com
	
The MSDOS program must load below 10000h. The intention here is not to
let you run MS-Windows, do some work in DOS and then net boot. The aim
here is to allow you to run some program which configures your hardware,
for which there is no other way.

To run your program, you should place a line like:

	shell=a:\booter.com
	
in your config.sys file.

Once booter.com is run, DOS is generally scribbled over in memory.

4. A Prom

After configuring for your ethernet adaptor, you type 

	make  rom.hex

This makes the rom image rom.bin. The dosum program creates a checksum.
The hexbin program writes out data for a prom programmer.

What if it doesn't work?
------------------------

1. First, work from a boot floppy version. 
Does the floppy boot? It should produce a message when it does.

2. Does the bootp protocol work? When the program starts, you can press
'd' to toggle the debug flag. This will produce lots of debugging information.

If bootp is not working, does anything go out the Ethernet wire? Do you
have a tracer program. You can use ka9qnos on another PC to trace packets.

If packets go out, maybe the problem is on the Unix server. Does the host
respond? Is the bootp daemon working? You can use the syslogd to see logged
messages. If the bootpd program is running (use ps -ax on Linux to see all
processes) then you can be reasonably sure that a bootp request has been seen.
Bootpd stays active for about 15 minutes after initial activation.
Are the entries in the bootptab correct? Are the entries in inetd.conf correct?

Do you have an early (pre 99.9, pre Net2) version of Linux, which has the ip
broadcast address set to zeroes (if so, use fimage0.bin).

3. If bootp is working, you're about 95% there. Does tftp (the file transfer)
work? Is there a boot file. Does it have world read permissions, and the
directory have world read permission. Again you can use syslogd. Again check
inetd.conf.

4. If you still can't get it to work, write down the major debugging
messages when you toggle debug, and try to mail me below.

Please note the following:

	nobody is paying me to do this
	service is entirely at my discretion
	I am interested in genuine problems (where you have
	sincerely tried yourself) and will try to help.
	abuse will be silently ignored

Notes on the code:
------------------

This section is to help you should you desire to understand the code
in a deeper way, and to present some design issues.

The code is written without any library calls, that is, all string,
print etc. functions are included.

The reason for this is that I wanted to have a totally romable program.
In order to produce one for a network adaptor, the prom should be
able to be placed anywhere the adaptor allows, with the segment address
configured by jumpers on the adaptor card.

Thus there must be no far calls, no segment addresses 'burnt into' the
program.

This is also the reason there are no implicit long multiplies and divides.

You can tell if you've gone wrong here by running programs like locate
or exe2hex on the exe file (before exe2bin). If segment fixup records are
present then you've got segment information (actually, thinking about it
exe2bin would probably barf too).

In addition, I tried to make the code such that the stack segment register
did not have to be the same as the data segment register.

The main way this is achieved is not to make a pointer out of automatic
variables. You may see this in the code, but I have only done it at
points where I want the stack offset.

The map files produced during linking give a very good indication of
segment layout. Be very careful with this layout. It interacts with
code in rom.asm, which sets up the data segment and clears bss. The
segment layout is different between the DOS version and the boot images.
Layout is controlled by layout.inc.

Bugs:
-----

Lots.

At the moment there is one bug I can't find. If Linux starts running, the
PC requires a hard reset before my boot code will work. A software
reset is not enough. (This is for the WD adaptor).

I haven't (ahem) actually burnt a prom.

Contact:
--------

You can try

   jhonan@kralizec.zeta.org.au

I make my living doing consulting or contract programming work. If you
have a special network adaptor you'd like to have a boot rom for, or
for any code you'd like written, why don't you contact me?

Jamie Honan, May 1993

