  Etherboot README
  Markus Gutschke and Ken Yap, gutschk@math.uni-muenster.de,
  ken.yap@acm.org
  1 March 1998

  This is the README file for the Etherboot package. This document
  explains how to install, configure and use the Etherboot package.  The
  instructions here apply to version 4.0 of Etherboot.
  ______________________________________________________________________

  Table of Contents


  1. Introduction

     1.1 What hardware is supported?
     1.2 Availability of this document
     1.3 Getting help

  2. Unpacking, compiling and testing the package

     2.1 Unpacking the distribution
     2.2 Compiling the ROM images
     2.3 Testing the ROM images

  3. Setting up a diskless boot

     3.1 Making a tagged image
     3.2 Compiling a custom kernel
     3.3 Setting up a bootp daemon
     3.4 Setting up a DHCP daemon
     3.5 Setting up a tftp daemon

  4. Testing the network booting

     4.1 Setting up a NFS root filesystem
     4.2 Swap over NFS

  5. Booting DOS

  6. Making an Etherboot EPROM or EEPROM

     6.1 Choosing the EPROM
     6.2 Enabling the EPROM
     6.3 Size and speed of the EPROM

  7. Troubleshooting tips

  8. Acknowledgements

  9. Copyright



  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn


  Etherboot is a package for creating ROM images that can download code
  over the network to be executed on an x86 computer. Typically the
  computer is diskless and the code is Linux, but these are not the only
  possibilities. The code uses the bootp, tftp and NFS Internet
  Protocols.


  11..11..  WWhhaatt hhaarrddwwaarree iiss ssuuppppoorrtteedd??


  Etherboot supports the following network hardware (in no particular
  order): 3c503, 3c507, 3c509, 3c905b, NE1000, NE2000 (also the PCI
  cards, with the nepci driver), WD8003, WD8013, SMC8216/8416, Lance
  based cards such as the NE2100 and NI6510 (also the PCI Lance cards),
  Crystal CS89x0, Intel EtherExpress Pro, SMC 83c170 EPIC/100, SMC9000,
  Realtek 8139, NI5210, Schneider and Koch G16, and Tiara (Fujitsu
  Lancard). All Etherboot drivers are autoprobing, which means they
  attempt to detect the hardware addresses at which the card is
  installed. It's fairly easy to write a driver if you are familiar with
  Ethernet hardware interfacing. Please contact me
  <mailto:ken.yap@acm.org> for more information if you are interested in
  doing so or are interested in having a driver written.


  11..22..  AAvvaaiillaabbiilliittyy ooff tthhiiss ddooccuummeenntt


  This document and related documents are also kept online at the
  Etherboot Home Page <http://www.slug.org.au/etherboot/>.  This will in
  general have the latest distributions and documentation.



  For a talk/tutorial type introduction to what Etherboot does and how
  to set it up, see my SLUG talk <diskless.html>. You may wish to review
  this before reading further.



  An older version of this README, which is now out of date, can be
  accessed via this link <old-README.html>.


  11..33..  GGeettttiinngg hheellpp


  There is a mailing list for all netbooting related issues. To
  subscribe follow the instructions on the Etherboot home page
  <http://www.slug.org.au/etherboot/>.



  With the exception of the following section, the information on
  diskless booting is not specific to Etherboot but can be used for the
  Netboot package also.


  22..  UUnnppaacckkiinngg,, ccoommppiilliinngg aanndd tteessttiinngg tthhee ppaacckkaaggee


  _T_h_i_s _s_e_c_t_i_o_n _i_s _E_t_h_e_r_b_o_o_t _s_p_e_c_i_f_i_c_.


  22..11..  UUnnppaacckkiinngg tthhee ddiissttrriibbuuttiioonn


  Unpack the distribution using gunzip and tar, using either of the
  following commands:





  ______________________________________________________________________
          tar zxvf etherboot-4.0.tar.gz
          gunzip < etherboot-4.0.tar.gz | tar xvf -
  ______________________________________________________________________




  22..22..  CCoommppiilliinngg tthhee RROOMM iimmaaggeess


  Precompiled ROM images are provided in the bin/ directory but you may
  wish to review the options compiled in and make your own versions. For
  the 32 bit version you need a recent release of gcc and the binutils
  tools. This package was compiled with the tools from a RedHat 5.2
  distribution but it should work with any recent Linux distribution.
  For the 16 bit version you need the bcc tools from the Embedded Linux
  Kernel Subset (ELKS) project, for more details see the notes on 16 bit
  Etherboot <16.html>. You need the 16 bit version only if you intend to
  run Etherboot on a 286 or 086/088 PC.



  Assuming you have decided to make the 32 bit version, you only have to
  go to src-32/, edit the options in Config and say make. This will
  create all the ROM images available. The .lzrom images are the same as
  the .rom images. Since the .lzrom images are smaller and work exactly
  the same, there is no real reason to use .rom images any more, unless
  you are nervous about compression algorithm patents. We believe the
  algorithm used does not infringe patents, having been in public use
  for some time, but we do not know all the legal ramifications. See
  here <COPYING_compressor.html> for more details.



  Here is a brief description of the options available:






























  ______________________________________________________________________
  Basic options:

  -DDHCP_SUPPORT  - Use DHCP instead of BOOTP (default on)
  -DIMAGE_MENU    - Allow to interactively chose between different
                    bootimages; read vendortags.html for further
                    information.
  -DMOTD          - Display message of the day; read vendortags.html
                    for further information.
  -DANSIESC       - evaluate a subset of common ANSI escape sequences
                    when displaying the message of the day; this
                    probably does not make sense unless you also
                    define -DMOTD or at least -DIMAGE_MENU.
                    Combining this option with -DSERIAL_CONSOLE
                    is a waste of EPROM space.
  -DGFX           - support extensions to the ANSI escape sequences for
                    displaying graphics (icons or logos); this
                    requires -DANSIESC
  -DASK_BOOT=n    - Ask "Boot from Network or from Local? " at startup,
                    timeout after n seconds (0 = no timeout); this
                    can be done in a more generic way by using the
                    IMAGE_MENU, but it requires that the "bootp"
                    server is accessible, even when booting locally.
  -DANS_DEFAULT=ANS_NETWORK
                  - Assume Network to previous question
                    (alternative: ANS_LOCAL) on timeout or Return key
                    See etherboot.h for prompt and answer strings.
  -DEMERGENCYDISKBOOT
                  - if no BOOTP server can be found, then boot from
                    local disk. The accessibility of the TFTP server
                    has no effect, though! So configure your BOOTP
                    server properly.

  Basic options only on Etherboot/32:

  -DPASSWD        - enable password protection for boot images; this
                    requires -DIMAGE_MENU
  -DUSRPARMS      - allow the user to interactively edit parameters
                    that are passed to the booted kernel; you should
                    probably enable -DPASSWD as well; this feature
                    requires -DIMAGE_MENU
  -DFLOPPY        - boot from floppy/hd if bootimage matches the
                    pattern "/dev/[fh]d*"; if you do not have
                    enough space in the EPROM, then disable this
                    feature and use "mknbi-blkdev" for booting
                    from a local blockdevice.
  -DCONFIG_PCI_DIRECT
                  - define this for PCI BIOSes that do not implement
                    BIOS32 or not correctly

  These options should normally not need to be touched:

  -DNOINT19H      - Take control as soon as BIOS detects the ROM
                    Normally hooks onto INT19H
  -DMOVEROM       - if your motherboard does not cache adapter memory
                    space, then this option can speed up loading of
                    compressed BOOT-Prom images. It has no effect on
                    uncompressed images. Unless you are very tight on
                    free space, you will usually want to define this
                    option.
  -DDELIMITERLINES - print a line of = characters at the start
                    and also just before starting an image.
  -DSIZEINDICATOR - update a running total of the amount of code
                    loaded so far, in kilobytes
  -DT509HACK      - send two bootp packets before waiting for a
                    reply to the first. Makes a 3c509 do bootp
                    quicker
  -DT503_AUI      - Use AUI by default on 3c503 cards.

  These options are only for a serial console for Etherboot/32:

  -DSERIAL_CONSOLE- use a serial line for input and output
  -DCOMPORT       - 0x0 for COM1, 0x1 for COM2 etc
  -DCOMPARM       - configuration for COMPORT, save values:
                     0xe3 == 9600/8n1, 0xa3 == 2400/8n1
  ______________________________________________________________________




  22..33..  TTeessttiinngg tthhee RROOMM iimmaaggeess


  You can test the image with a floppy before burning an EPROM. On Linux
  just put a blank floppy in fd0 and say make card.fd0 where card is the
  name of your network card and it will copy a bootable image onto the
  floppy. If you wish to do this by hand, it's easy, just prepend
  floppyload.bin to card.rom (or card.lzrom) and write this combined
  binary to the floppy raw, i.e. starting at the boot block. Like this:




  ______________________________________________________________________
          cat floppyload.bin 3c509.lzrom > /dev/fd0
  ______________________________________________________________________



  When you boot with this floppy it will load the Etherboot ROM image
  from floppy and execute it. It should be able to detect your card. To
  get the bootrom to acquire an IP address and load the intended code,
  you need to set up bootp, tftp and NFS services, which we will discuss
  next.



  We suggest you continue to use floppy booting until you have completed
  the setup of the server and are satisfied that diskless booting works.


  33..  SSeettttiinngg uupp aa ddiisskklleessss bboooott


  In this section I assume you want to boot a Linux kernel. Booting a
  DOS kernel is similar, the main differences being in the way you set
  up the tagged image.


  33..11..  MMaakkiinngg aa ttaaggggeedd iimmaaggee


  Etherboot expects to download a tagged image <spec.html> containing
  the code to be executed. Briefly explained, a tagged image is a
  wrapper around the pieces of code or data that need to be put in
  various places in the computer's memory. It contains a directory
  telling how large the pieces are and where they go in memory. It also
  says where to start execution.




  A tagged image is created using a utility program. The utility program
  is specific to the kernel you want to load. The version for Linux is
  called mknbi-linux and that for DOS is mknbi-dos. These utilities are
  found in the netboot-<version> directory of the distribution.


  33..22..  CCoommppiilliinngg aa ccuussttoomm kkeerrnneell


  You will probably have to compile a custom kernel because the kernel
  needs to have the "Root file system on NFS" option compiled in.  You
  should also select "BOOTP support". "RARP support" is not needed.  In
  2.2 kernels you have to enable the "Kernel Autoconfig" option to
  access the BOOTP support question.  And unless you are using an initrd
  (initial ramdisk) you will probably have to compile in the driver for
  your network card too. For details, see the file
  /usr/src/linux/Documentation/nfsroot.txt in a Linux kernel source
  distribution.



  After you have compiled the custom kernel, make the tagged image,
  typically like this:


  ______________________________________________________________________
          mknbi -x -k zImage -o /tftpboot/vmlinuz.xterm
  ______________________________________________________________________



  Then put the tagged image in where the tftp daemon expects to find it,
  typically /tftpboot. Make sure it is world-readable because typically
  the tftp daemon runs as an unprivileged user.


  33..33..  SSeettttiinngg uupp aa bboooottpp ddaaeemmoonn


  Now set up a bootp daemon. In RedHat 5.2 this means installing the
  bootp RPM package, making sure that the bootps service is active in
  /etc/inetd.conf,  and editing /etc/bootptab. The essential pieces of
  information you need to put in bootptab are:


  1. The domain name of the machine.

  2. The Ethernet (MAC) address of the network card, which you generally
     obtain from a sticker on the card, a configuration program for the
     card, or in the last resort, from watching the output of Etherboot
     or from the packets sent from the card when trying to boot, using
     the debug option of bootpd.

  3. The name of the tagged image file, relative to the tftpboot
     directory.

  4. The IP address you intend to give it.

  5. The IP addresses of various servers. You will need at least the
     tftp server's address.



  Here is an example of a /etc/bootptab for the bootpd supplied with
  RedHat Linux 5.2 and probably many versions of Unix:

  ______________________________________________________________________
  .default:\
          :ht=ethernet:\
          :hd=/tftpboot:bf=null:\
          :ds=nameserver:\
          :hn:to=36000:
  xterm.ken.net.au:tc=.default:ha=08002BB7F380:ip=192.168.26.100:bf=vmlinuz.xterm
  ______________________________________________________________________



  The first entry sets up some common defaults which applies to all
  succeeding entries which can be "included" using the tc=.default
  attribute. The first field is the domain name of the machine. The ha
  attribute is the Ethernet address.  The ip attribute is self-
  explanatory. The bf field specifies the tagged image filename. For
  more details, consult the bootptab man page.



  Please note that if you use the ef (extension file) attribute to be
  able to send more configuration data to the diskless machine, you must
  run bootpef everytime bootptab is modified.



  If you are on a local network that is not directly connected to the
  Internet, you can use the "private" IP addresses 192.168.x.y (or in
  the other ranges mentioned in RFC1918
  <http://ds.internic.net/rfc/rfc1918.txt>). Otherwise please ask either
  your network administrator or your Internet service provider for your
  own IP address(es).


  33..44..  SSeettttiinngg uupp aa DDHHCCPP ddaaeemmoonn


  As an alternative to bootp, you could set up a DHCP server which has
  the advantage of automating the handing out of IP addresses. However
  the kernel may still do a bootp request to find the IP address for
  mounting the NFS filesystem. You may then wish to investigate the
  option in mknbi-linux which tells the kernel to take the address from
  the initial DHCP reply.



  More information about DHCP can be found at the DHCP FAQ Web Page
  <http://web.syr.edu/~jmwobus/comfaqs/dhcp.faq.html>.


  33..55..  SSeettttiinngg uupp aa ttffttpp ddaaeemmoonn


  Now set up a tftp daemon. In RedHat 5.2 this means installing the tftp
  RPM package and making sure that the tftp service is active in
  /etc/inetd.conf. You probably want to use the secure (-s) option so
  that files can only be fetched from /tftpboot or people may be able to
  fetch arbitrary files from your server.


  44..  TTeessttiinngg tthhee nneettwwoorrkk bboooottiinngg


  Now when you start up Etherboot, it should obtain an IP address and
  print out what it received. If you do not get this to work, turn on
  debugging in bootpd and see if any query was received. If not, check
  your network hardware (cables, etc). If a query was received, check if
  bootpd was able to give an answer. If not, then the Ethernet address
  was not found in /etc/bootptab. If a reply was sent, then only faulty
  hardware or a bug in Etherboot would prevent it being received by
  Etherboot.



  Assuming an IP address was received, the next thing Etherboot tries to
  do is load a file using tftp. Check your system logs to see if a tftp
  daemon was started up and a file requested. Generally if you run tftpd
  under tcpwrapper security, a log entry will be generated. If not, it
  could be a path problem or file permission problem (the file needs to
  be readable by tftpd). Fix the problem.



  After the tagged image is loaded, Etherboot will jump to it. If it
  crashes here, check that the image is a tagged image. If it executes
  and stops at the point where it's trying to mount the NFS root, then
  you need to check that you have the "root on NFS" option compiled in
  and that you have compiled in the network card driver.


  44..11..  SSeettttiinngg uupp aa NNFFSS rroooott ffiilleessyysstteemm


  Now you need to set up a NFS root filesystem for the diskless
  computer.  Typically this is under /tftpboot/<ip address of computer>.
  (In 2.1 and presumably future kernels, this should be /tftpboot/<name
  of computer in bootptab>). This needs to contain a complete root
  filesystem that will make the kernel boot happily.  This means, for
  most kernels, it should contain /dev, /proc, /etc, /sbin, /bin, /tmp
  and /var. The details vary from distribution to distribution.  Being
  lazy I just make a copy of the necessary files from an existing RedHat
  5.2 filesystem and modify some key files appropriately. You can find a
  description in my tutorial <diskless.html> and some shell scripts to
  copy the files. Since the amount of disk space needed is relatively
  small in these days of large disks, I don't bother to throw out things
  that may not be needed.



  Warning: Do not attempt to reuse the root filesystem of your server,
  whether by exporting it directly or by making hard links (symbolic
  links will not work). First of all, the configuration files will
  contain information pertaining to the server, not the client, so your
  client will get the wrong information. Secondly, this is a security
  risk. NFS is already not totally safe, but this way you are directly
  exposing your server root to clients. Even if you make hard links, the
  clients could (maliciously or accidentally) overwrite key binaries,
  making the server unusable. Don't try to save a few megabytes of disk
  space this way. You can however share some directories between
  clients, typically /sbin, /bin and /lib.  The sample scripts in the
  tutorial show you how.



  The root filesystem should be exported rw and no_root_squash because
  the various processes need to be root and need to write to log files
  in the root partition. You may wish to export /usr and /home
  filesystems to the diskless computer also. These do not need
  no_root_squash permission. Be aware that the RedHat 5.2 distribution
  has a few "bugs" relating to symlinks and so forth for diskless
  booting.  These are mentioned in the tutorial. Other distributions may
  have similar problems.
  44..22..  SSwwaapp oovveerr NNFFSS


  Swap over NFS can be arranged but you have to patch the kernel source.
  There is a patch for kernels in the contrib/ directory for 2.0.x
  kernels. Hopefully this will make it into future kernels. Be aware
  that opinions are divided on NFS swap.  Some people think it's a bad
  thing because it just kills the network if you have lots of diskless
  computers and that you shouldn't be running into a swap regime on a
  diskless computer anyway. Some other people like having a bit of
  insurance.



  There are patches in the contrib directory for NFS swap but for up to
  date patches, try here < http://www.math1.rwth-aachen.de/~heine/nfs-
  swap/>.



  Also have a look at the NBD
  <http://atrey.karlin.mff.cuni.cz/~pavel/nbd/nbd.html> Network Block
  Device web page for swapping over that. This requires a 2.1 or 2.2
  kernel.


  55..  BBoooottiinngg DDOOSS


  What about DOS? The deal with DOS is that one is loading a virtual
  floppy called A: into extended memory and then booting from this
  floppy.  So you have to capture an image of a bootable DOS floppy
  first.  Some more details can be found in the mknbi-dos directory.



  I have booted DOS (both M$ and DR versions) diskless this way. Note
  that extended memory is used so that rules out 086/088 computers but
  286s are ok. See this document <atnetboot.html> for more details.



  If you were thinking of booting a Windows machine via the network, it
  seems (I'm not masochistic enough to do this) the problem is not the
  network booting but the mounting of a file system over NetBIOS
  (Windows does not do remote mounts of root filesystems over NetBIOS on
  TCP). So that rules out a Samba server. It appears to be possible over
  a Netware server, for which Linux has workalikes. But then what do you
  do about the networking stack? This situation may change with with
  future Samba developments. But you will still have problems with
  pathnames and the usual Windows hassles. Do you really want to do
  this?  In the Web page for Etherboot
  <http://www.slug.org.au/etherboot/>, there is a link to someone's Web
  page explaining how this was done with a commercial TCP/IP boot ROM.


  66..  MMaakkiinngg aann EEtthheerrbboooott EEPPRROOMM oorr EEEEPPRROOMM


  Assuming you have satisfactorily set up your server environment, you
  may now wish to put the Etherboot onto an EPROM or EEPROM. Naturally
  this assumes access to hardware to burn (and possibly erase) EPROMs.
  An alternative is to use an EEPROM card. There is a schematic and PCB
  artwork for such a card in the distribution. This EEPROM card plugs
  onto the ISA bus and can be reprogrammed with software.

  66..11..  CChhoooossiinngg tthhee EEPPRROOMM


  Most network cards come with a blank (E)EPROM socket even though it is
  seldom used. When it is used, it is typically filled with a
  proprietary EPROM from the network card manufacturer. You can put an
  Etherboot EPROM there instead.


  66..22..  EEnnaabblliinngg tthhee EEPPRROOMM


  First you must discover how to enable the EPROM socket on your card.
  Typically the EPROM is not enabled at the factory and a jumper or a
  soft configuration is used to turn it on.


  66..33..  SSiizzee aanndd ssppeeeedd ooff tthhee EEPPRROOMM


  Secondly, you must discover what size and speed of EPROM is needed.
  This can be difficult as network card manufacturers often neglect to
  provide this information.



  The smallest EPROM that is accepted by network cards is an 8K EPROM
  (2764). Some cards will even go up to 64KB EPROMs (27512). You want to
  use the smallest EPROM you can so that you don't take up more of the
  upper memory area than needed as other extensions BIOSes may need the
  space.  However you also want to get a good price for the EPROM.
  Currently the 32KB and 64KB EPROMs (27256 and 27512) seem to be the
  cheapest per unit. Smaller EPROMs appear to be more expensive because
  they are out of mainstream production.



  If you cannot find out from the documentation what capacity of EPROM
  your card takes, you could do it by trial and error. Take an ROM with
  some data on it (say a character generator ROM) and plug it into the
  socket. Be careful not to use an extension BIOS for this test because
  it may be detected and activated and prevent you from booting your
  computer.  Using the debug program under DOS, dump various regions of
  the memory space. Say you discover that you can see the data in a
  memory window from CC00:0 to CC00:3FFF (= 4000 hex = 16384 decimal
  locations). This indicates that a 16 KB EPROM is needed. However if
  you see an alias in parts of the memory space, say the region from
  CC00:0 to CC00:1FFF is duplicated in CC00:2000 to CC00:3FFF, then you
  have put an 8 KB EPROM into a 16 KB slot and you need to try a larger
  EPROM.



  Note that because pinouts for 28 pin EPROMs are upward compatible
  after a fashion, you can probably use a larger capacity EPROM in a
  slot intended for a smaller one. The higher address lines will
  probably be held high so you will need to burn the image in the upper
  half or upper quarter of the larger EPROM, as the case may be. However
  you should double check the voltages on the pins armed with data sheet
  and a meter because CMOS EPROMs don't like floating pins.



  The speed of the EPROM needed depends on how it is connected to the
  computer bus.  If the EPROM is directly connected to the computer bus,
  as in the case of many cheap NE2000 clones, then you will probably
  have to get an EPROM that is at least as fast as the ROMs used for the
  main BIOS. This is typically 150 ns. Some network cards mediate access
  to the EPROM via an ASIC and this ASIC may insert wait states so that
  slower EPROMs can be used. Incidentally the slowness of the EPROM
  doesn't affect Etherboot execution speed much because Etherboot copies
  itself to RAM before executing. I'm told Netboot does the same thing.


  77..  TTrroouubblleesshhoooottiinngg ttiippss



  +o  Floppy boot doesn't work. Have you copied the ROM image (with the
     floppyloader prepended) to the floppy raw? Is that size of floppy
     bootable by your computer? Are you trying to run a 32 bit Etherboot
     on a 16 bit machine (286, 086/088)? Have you selected too many
     compile time options? The real limit on Etherboot is not the size
     of the EPROM but the fact that it executes in the 32 KB region
     between 0x98000 and 0xA0000. If the sum of code, stack and bss is
     greater than 32 KB, then Etherboot might crash at unexpected
     places. You could increase the memory to 48 KB by lowering the
     RELOCADDR in the Makefile but this is outside the specifications.
     Definitely do not lower RELOCADDR below 0x94000 because various
     pieces of booting information are stored from 0x90000 upwards.

  +o  Floppy version works but EPROM version doesn't work. There is a
     program called rom-scan (Linux and DOS versions) in the directory
     contrib/rom-scan which will help detect problems.


  +o  If the EPROM is not detected at all then the contents of the EPROM
     are not visible to the BIOS. Check that you have enabled the EPROM
     with any jumpers or soft configuration settings. Check that you do
     not have any conflicts in the memory address of the EPROM and any
     other hardware.  Perhaps you have to prevent it from being mapped
     out by your BIOS settings. Or perhaps you have to shadow it with
     RAM. Maybe you put the code in the wrong half or wrong quarter of
     the EPROM. Maybe the access time of the EPROM is not low enough.
     You can also use the debug program under BIOS to examine the memory
     area in question.

  +o  If rom-scan says the EPROM is present but not active, then
     something prevented the BIOS from seeing it as a valid extension
     BIOS. This could be truncation of the EPROM window, maybe you have
     a larger EPROM in a slot meant for a smaller one. Maybe there is a
     checksum error in the EPROM due to some bits not properly
     programmed or the EPROM not being fast enough. In one case that we
     know of, the 3c503 network card, the ASIC actually returns 2 bytes
     of 80 80 in the end locations of the EPROM space. This apparently
     is a kind of signature. The makerom program in Etherboot
     compensates for this, but if the pattern is not 80 80, then the
     code needs to be modified.

  +o  If rom-scan says the EPROM is present and active, but BIOS does not
     see it, then perhaps the EPROM is located in an area that the BIOS
     does not scan. The range scanned is supposed to be 0xC0000 to
     0xEF800 in increments of 2 KB but I have seen some BIOSes that
     continue the scan into the 0xF0000 page.


     Note that rom-scan will also detect other extension BIOSes mounted
     on your computer, for example VGA BIOSes and SCSI adapter BIOSes.
     This is normal.

  +o  Etherboot does not detect card. Are you using the right ROM image?
     Is the card properly seated in the computer? Can you see the card
     with other software? Are there any address conflicts with other
     hardware? Is the PCI id of the card one that is not known to
     Etherboot yet? In this case and where you think there is a bug in
     Etherboot, please contact the author with all details.

  +o  Etherboot detects card but hangs computer after detection. Some
     cards are booby traps while they are enabled. The typical offenders
     are NE2000s which will hang the bus if any access is made to the
     reset addresses while interrupts are active. You may need to do a
     hard reset of the computer, i.e. power down and up again before
     running Etherboot.

  +o  Etherboot detects card but does nothing after saying Searching for
     server. Check your network hardware. Did you select the right
     hardware interface (AUI, BNC, RJ45)? Is the cabling ok? If you have
     a Unix computer on the network and have root privileges, you could
     run tcpdump looking for broadcast packets on the bootps port. If
     the requests are getting sent out but no replies are getting back,
     check your bootpd setup. Also check if the server has a route to
     the client.

  +o  Etherboot obtains IP address but fails to load file. Check the tftp
     server. Is the tagged image file installed? Is the file world
     readable? Did you put the right home directory and boot filename in
     bootptab?

  +o  Etherboot loads file via tftp but Linux fails to boot. This is a
     large category. Here are some suggestions:


  +o  You do not have a private copy of the /, /etc, /var, ...
     directories

  +o  Your /dev directory is missing entries for /dev/zero and/or
     /dev/null or is sharing device entries from a server that uses
     different major and minor numbers (i.e. a server that is not
     running Linux).

  +o  Your /lib directory is missing libraries (most notably libc* and/or
     libm*) or does not have the loader files ld*.so*

  +o  You neglected to run ldconfig to update /etc/ldconfig.cache or you
     do not have a configuration file for ldconfig.

  +o  Your /etc/inittab and/or /etc/rc.d/* files have not been customized
     for the clients.

  +o  Your kernel is missing some crucial compile-time feature (such as
     NFS filesystem support, booting from the net, transname (optional),
     ELF file support, networking support, driver for your ethernet
     card).

  +o  Missing init executable (in one of the directories known by the
     kernel: /etc, /sbin, ?). Remember /sbin/init must be a real file,
     not a symlink.

  +o  Missing /etc/inittab

  +o  Missing /dev/tty?

  +o  Missing /bin/sh

  +o  System programs that insist on creating/writing to files outside of
     /var (mount and /etc/mtab* is the canonical example)


     The essence is that you must provide whatever is needed in the NFS
     root filesystem that your kernel needs to boot. This is somewhat
     distribution dependent. In the discussion above I solved the
     problem by making a copy of an existing root filesystem and
     modifying a few bits.  Be aware that some, if not all,
     distributions contain bugs in their layout that hinder diskless
     mounting so you will have to fix any problems that arise. An
     example was a directory in /usr/X11R6/lib that needed to be
     writable, preventing /usr from being mounted ro.

  +o  Etherboot works fine and kernel starts but network interface
     doesn't work. Check your network configuration in the OS.
     Etherboot uses polled I/O and not interrupt I/O to fetch the
     images. So the IRQ line doesn't get exercised. This manifested
     itself in one case with a NIC that could netboot but network
     programs run afterwards couldn't receive any packets. It seemed to
     be a combination of a weak NIC IRQ line and a fussy motherboard.
     But the same thing could happen if say the IRQ is not set to where
     the software is expecting it. The image will load fine with the
     wrong IRQ but the software will not run properly. This is more of
     an issue with say DOS packet drivers, where the user has to specify
     the IRQ line than with Linux, which autoprobes.




  88..  AAcckknnoowwlleeddggeemmeennttss


  The following people have contributed substantially to Etherboot. If
  you feel your name has been left out, just let me know and I will fix
  it up.



     MMaarrkkuuss GGuuttsscchhkkee
        Co-author of Etherboot. He was the person who ported the Netboot
        suite from FreeBSD. He has enhanced Etherboot with many
        features, one new driver and has contributed various utilities
        and addons.


     GGeerroo KKuuhhllmmaannnn
        The mknbi utilities used by Etherboot are from Netboot.  He has
        also clarified the original specification by Jamie Honan.


     JJaammiiee HHoonnaann
        Jamie started Netboot off by writing the first version that used
        code from a packet driver.


     MMaarrttiinn RReenntteerrss eett.. aall
        The original authors of Netboot on FreeBSD.


     BBrruuccee EEvvaannss
        Created bcc compiler used by Etherboot/16.


     RRoobb ddee BBaatthh
        Current maintainer of bcc and associated tools like as86.


     GGeerrdd KKnnoorrrr
        Contributed MASQ for making a boot floppy without DOS.
     AAddaamm RRiicchhtteerr
        Contributed comboot for making a boot floppy without DOS.


     CCllaauuss--JJuussttuuss HHeeiinnee
        Contributed patch for serial console and NFS swapping. See the
        contrib/nfs-swap directory for his Web page.


     DDiicckkoonn RReeeedd
        Contributed display of loading status and a hack for the 3c509
        card.


     DDaavviidd MMuunnrroo
        Contributed PCI detection code originally from Linux sources.


     CChhaarrlliiee BBrraaddyy
        Donated NE2100 card so that a driver could be written, and
        helped test the LancePCI driver. Spotted bug with 4.1 header
        code.


     RRooggiieerr WWoollffff
        Created Intel EtherExpressPro 100 driver and binary to hex
        converter.


     VVllaagg LLuunngguu
        Contributed patches to work with DHCP. Also contributed a fix to
        match the received XID against the transmitted one, important in
        a network with many requesters.


     WWiilllliiaamm AArrbbaauugghh
        Patches for eepro to work with 3.2.


     JJeeaann MMaarrcc LLaaccrrooiixx
        Contributed an improved bin2intelhex.


     JJiimm HHaagguuee
        Contributed fixes to 3c503 driver for PIO mode, fix to makerom
        for presetting EPROM bytes, and various endian fixes.


     AAnnddrreeww CCoouulltthhuurrsstt
        Contributed patch for making Intel eepro work in 4.0.


     DDoouugg AAmmbbrriisskkoo
        Contributed patches to start32.S from FreeBSD version to make it
        boot Windoze after answering N to Boot from Network question.


     AAlleexx HHaarriinn
        Contributed patches for prepended loaders and makerom to make
        bootrom PnP and PCI compatible.


     PPeetteerr DDoobbccssaannyyii
        Contributed vendor and device IDs for the Netvin NE2000/PCI
        clone.

     aaddaamm@@mmuuddlliisstt..eeoorrbbiitt..nneett
        Contributed RARP code as alternative to BOOTP/DHCP. Activated by
        RARP_NOT_BOOTP define.


     DDaanniieell EEnnggssttrroomm
        Contributed a SMC9000 driver.


     DDiiddiieerr PPooiirroott
        Contributed an Etherpower II (EPIC 100) driver.


     MMaarrttiinn AAttkkiinnss
        Contributed mntnbi for mounting DOS NBIs.


     AAttiillllaa BBooggaarr
        Contributed a bug fix to the bootmenu code and a patch to main.c
        to remove looping menus on failure. Also code for ARP replies
        and TFTP retransmit (#ifdefed). Cleanup of tftp and tftpd.


     NNaatthhaann RR.. NNeeuulliinnggeerr
        Found bug due to tu_block being declared signed short in
        arpa/tftp.h on many platforms when it should be unsigned short.


     DDaavviidd SShhaarrpp
        Contributed a FreeBSD driver for Tulip based cards. Ken Yap
        ported it to Etherboot. Not tested because code needs to be
        written for all the variants of the Tulip and also because no
        hardware available to me.


     GGrreegg BBeeeelleeyy
        Contributed a 3c905b driver. Be sure to read the release notes
        in 3c905b.txt before using.


     AAlleexx NNeemmiirroovvsskkyy
        Contributed patches to use BIOS call to size memory otherwise
        Etherboot was trampling on top of 640kB area, which is used by
        some extended BIOSes. Also contributed patches to pci.c to
        implement PCI bus support on BIOSes that do not implement
        BIOS32, or incorrectly.


     GGuueenntteerr KKnnaauuff
        Suggested making the ASK_BOOT prompts more generic and clearer.
        (Why doesn't SGML-Tools accept &uumlaut;?) Also contributed a
        DOS utility for extracting the identifier string and PCI IDs, if
        any, out of the boot ROM.


     KKllaauuss EEssppeennllaauubb
        Contributed various cleanup patches to the code especially in
        the bootmenu area, as well as a completely revamped start32.S.
        Also introduced Rainer Bawidamann's code, see next paragraph.


     RRaaiinneerr BBaawwiiddaammaannnn
        Contributed a Realtek 8139 driver.



     GGeeoorrgg BBaauumm
        contributed a Schneider & Koch G16 driver.


     jjlluukkee@@ddeeaakkiinn..eedduu..aauu
        sent in a fix for the WD/SMC8013 which I finally verified.



  99..  CCooppyyrriigghhtt


  The boot code from FreeBSD is under the BSD license.  The netboot code
  is under the GPL. This is not a problem really: the GPL states that
  mere aggregation of another work with a GPL'ed work on a storage
  medium, e.g. an archive file, does not put the other work under the
  GPL.



  Send changes to this document to Ken Yap (ken.yap@acm.org).













































