Marty Connor has set up a web form for creating a ROM image on the fly and returning it as the output of the form. If all you want is a ROM image, this could save you time building the distribution.
Unpack the distribution using gunzip and tar, using one of the following commands, where you replace x by the patchlevel number:
tar zxvf etherboot-5.0.x.tar.gz tar jxvf etherboot-5.0.x.tar.bz2 gunzip < etherboot-5.0.x.tar.gz | tar xvf - bunzip2 < etherboot-5.0.x.tar.bz2 | tar xvf -
If the documentation tarball was provided separately, then in addition do this:
cd etherboot-5.0.x
followed by one of the following:
tar zxvf ../etherboot-doc-5.0.x.tar.gz tar jxvf ../etherboot-doc-5.0.x.tar.bz2 gunzip < ../etherboot-doc-5.0.x.tar.gz | tar xvf - bunzip2 < ../etherboot-doc-5.0.x.tar.bz2 | tar xvf -
which will extract the documentation in a subdirectory of the Etherboot top directory.
To build the ROM images you need a recent release of gcc and the binutils tools. This package has been compiled with the tools from a SuSE 7.1 distribution but it should work with any recent Linux or FreeBSD distribution. gas 2.9.1 is too old to handle the 16-bit code in loader.S. Use gas 2.9.5 at least. Also the "gcc 2.96" used in RedHat 7.0 (and later versions maybe) generates faulty machine code compiling Etherboot. Use kgcc from those distributions instead.
You only have to go to src/, edit the options in Config and say make. We suggest you accept the default options if you are not sure what to select. This will create all the ROM images available in bin32. 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 for more details.
Here is a description of the options available:
User interaction options: -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. If unset, boot immediately using the default. -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. -DBAR_PROGRESS Use rotating bar instead of sequential dots to indicate an IP packet transmitted. -DMOTD Display message of the day; read vendortags.html for further information. (Deprecated) -DIMAGE_MENU Allow to interactively chose between different bootimages; read vendortags.html for further information. (Deprecated) -DPASSWD Enable password protection for boot images; this requires -DIMAGE_MENU. (Deprecated) -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. (Deprecated) -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. It is possible to combine this option with -DCONSOLE_DUAL, but you have to be aware that the boot menu will no longer use ANSI escapes to be compatible with the serial console. Also be careful with your banners, as they may confuse your serial console. Generally you lose most of the ANSIESC functionality. (Deprecated) -DGFX Support extensions to the ANSI escape sequences for displaying graphics (icons or logos); this requires -DANSIESC. It probably does not make sense to use -DGFX if you have -DCONSOLE_DUAL, as the serial console normally cannot handle the GFX stuff. (Deprecated) -DSHOW_NUMERIC Display menu item labels as numbers. -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. Boot autoconfiguration protocol options: -DNO_DHCP_SUPPORT Use BOOTP instead of DHCP. -DRARP_NOT_BOOTP Use RARP instead of BOOTP/DHCP. -DREQUIRE_VCI_ETHERBOOT Require an encapsulated Vendor Class Identifier of "Etherboot" in the DHCP reply Requires DHCP support. -DALLOW_ONLY_ENCAPSULATED Ignore Etherboot-specific options that are not within the Etherboot encapsulated options field. This option should be enabled unless you have a legacy DHCP server configuration from the bad old days before the use of encapsulated Etherboot options. Boot tuning parameters: -DCONGESTED Turns on packet retransmission. Use it on a congested network, where the normal operation can't boot the image. -DBACKOFF_LIMIT Sets the maximum RFC951 backoff exponent to n. Do not set this unreasonably low, because on networks with many machines they can saturate the link (the delay corresponding to the exponent is a random time in the range 0..3.5*2^n seconds). Use 5 for a VERY small network (max. 2 minutes delay), 7 for a medium sized network (max. 7.5 minutes delay) or 10 for a really huge network with many clients, frequent congestions (max. 1 hour delay). On average the delay time will be half the maximum value. If in doubt about the consequences, use a larger value. Also keep in mind that the number of retransmissions is not changed by this setting, so the default of 20 may no longer be appropriate. You might need to set MAX_ARP_RETRIES, MAX_BOOTP_RETRIES, MAX_TFTP_RETRIES and MAX_RPC_RETRIES to a larger value. Boot device options: -DCAN_BOOT_DISK Can boot from floppy/hd if bootimage matches the pattern "/dev/[fhs]d*". -DTRY_FLOPPY_FIRST If > 0, tries that many times to read the boot sector from a floppy drive before booting from ROM. If successful, does a local boot. It assumes the floppy is bootable. Requires -DCAN_BOOT_DISK. -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. You should probably reduce MAX_BOOTP_RETRIES to a small number like 3. Boot image options: -DTAGGED_IMAGE Add tagged image kernel boot support (Recommended). -DAOUT_IMAGE Add a.out kernel boot support (generic). -DELF_IMAGE Add generic ELF kernel boot support (Recommended). -DIMAGE_MULTIBOOT Add Multiboot image support (currently only for ELF images). Without this, generic ELF support is selected. -DIMAGE_FREEBSD Add FreeBSD image loading support (requires at least -DAOUT_IMAGE and/or -DELF_IMAGE). -DFREEBSD_KERNEL_ENV Pass in FreeBSD kernel environment -DAOUT_LYNX_KDI Add Lynx a.out KDI support -DDOWNLOAD_PROTO_TFTP If defined, boots by TFTP (Recommended). -DDOWNLOAD_PROTO_NFS If defined, boots from a NFS mount and disables TFTP loading. Default is DOWNLOAD_PROTO_TFTP if neither is defined. Console options: -DCONSOLE_CRT Set for CRT console (default if nothing else is set). -DCONSOLE_SERIAL Set for serial console. -DCONSOLE_DUAL Set for CRT and serial console, see comment at -DANSIESC and -DGFX. -DCOMCONSOLE Set port, e.g. 0x3F8. -DCONSPEED Set speed, e.g. 57600. -DCOMPARM Set Line Control Register value for data bits, stop bits and parity. See a National Semiconditor 8250/ 16450/16550 data sheet for bit meanings. If undefined, defaults to 0x03 = 8N1. -DCOMPRESERVE Ignore COMSPEED and COMPARAM and instead preserve the com port parameters from the previous user of the com port. Examples of previous user are a BIOS that implements console redirection, lilo and LinuxBIOS. This makes it trivial to keep the serial port speed setting in sync between multiple users. You set the speed in the first user and the rest follow along. BIOS interface options: -DPCBIOS Compile in support for the normal pcbios -DLINUXBIOS Compile in support for LinuxBIOS -DBBS_BUT_NOT_PNP_COMPLIANT Some BIOSes claim to be PNP but they don't conform to the BBS spec which specifies that ES:DI must point to the string $PnP on entry. This option works around those. This option must be added to LCONFIG. -DNO_DELAYED_INT Take control as soon as BIOS detects the ROM. Normally hooks onto INT18H or INT19H. Use only if you have a very non-conformant BIOS as it bypasses BIOS initialisation of devices. This only works for legacy ROMs, i.e. PCI_PNP_HEADER not defined. This option was formerly called NOINT19H. -DBOOT_INT18H Etherboot normally hooks onto INT19H for legacy ROMs. You can choose to hook onto INT18H (BASIC interpreter entry point) instead. This entry point is used when all boot devices have been exhausted. This option must be added to LCONFIG. -DCONFIG_PCI_DIRECT Define this for PCI BIOSes that do not implement BIOS32 or not correctly. Normally not needed. Only works for BIOSes of a certain era. -DCONFIG_TSC_CURRTICKS Uses the processor time stamp counter instead of reading the BIOS time counter. This allows Etherboot to work even without a BIOS. This only works on late model 486s and above. -DPXELOADER_KEEP_UNDI For implementation later with UNDI. -DIBM_L40 This option uses the 0x92 method of controlling A20 instead of the traditional method of using the keyboard controller. An explanation of A20 is here: http://www.win.tue.nl/~aeb/linux/kbd/A20.html This occurs on MCA, EISA and some embedded boards, and sometimes with the Fast Gate A20 option on some BIOSes. Enable this only if you are sure of what you are doing. Obscure options you probably don't need to touch: -DPOWERSAVE Halt the processor when waiting for keyboard input which saves power while waiting for user interaction. Good for compute clusters and VMware emulation. But may not work for all CPUs. -DT503_AUI Use AUI by default on 3c503 cards. -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. This option must be added to LCONFIG! (Recommended). -DUSE_LOWMEM_BUFFER Define to put some buffers below 0x10000 which may interfere with other programs (Deprecated).
You may have to set the PCI vendor and device IDs correctly for PCI NICs. Look at the file NIC. Locate the line that has the correct PCI IDs for your NIC. This will give you the name of the ROM image you should use. The PCI IDs are usually displayed by the BIOS on booting up. They can also be read out from a running Linux system using the Linux PCI Utilities. If you do not use the ROM with the correct IDs, the floppy version will work, but the ROM will not since the BIOS will check for a match.
You can test the image with a floppy before programming an EPROM. On Linux just put a blank floppy in fd0 and say make bin32/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 make bin/boot1a.bin and prepend this to card.rom (or card.lzrom) and write this combined binary to the floppy raw, i.e. starting at the boot block. Like this, after you have done a make to create all the images:
cat bin/boot1a.bin bin32/3c509.lzrom > /dev/fd0
Make sure the floppy has no bad blocks. It is best if it has been formatted just before use. You do not need to put any kind of filesystem on it. If you wish, you could substitute /dev/fd0 with the actual device suitable for the floppy size you are using, for example /dev/fd0H1440 for 1.44 MB floppies. This may be more reliable than using the autodetecting device /dev/fd0.
This will also work on a hard disk partition, but as this is a riskier operation, you should read the instructions in boot1a.s. If you don't understand how to do it, please ask the mailing list for help, don't just try it and destroy your disk data.
When you boot with this floppy it will load the Etherboot ROM image from floppy and execute it. If you chose the correct ROM image, 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 or DHCP, 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.
In addition, you can generate images with the suffixes .com, .lilo, .lzlilo and .pxe. Where you would normally say:
make bin32/3c509.rom
you would say
make bin32/3c509.com
and similarly for .lilo, .lzlilo and .pxe. These are alternate boot image formats.
The ones ending in .com are DOS format executables, suitable for starting from DOS. It requires a real DOS environment, not a virtual DOS environment such as that provided by the DOS prompt window under Windows. Also it requires that there be no XMS drivers or other memory handlers loaded. It is not guaranteed to work if the environment is not clean, and sometimes not even if it is. The best chance of this format working is when DOS is booted with no device drivers whatsoever. If you can, use raw floppy or SYSLINUX booting instead.
The ones ending in .lilo and .lzlilo look sufficiently like Linux kernel images to be accepted by LILO and SYSLINUX for installation. Unfortunately loadlin uses a slightly different method of booting for Linux kernels from LILO and SYSLINUX and will not work with these images. The difference between .lilo and .lzlilo is compression, analogous to the difference between .rom and .lzrom.
The fact that .(lz)lilo images look like a Linux kernel to LILO and SYSLINUX allows some interesting booting possibilities. For example, you could use LILO to select between DOS/Windows and Etherboot images from a disk that contains no Linux partitions, only FAT based partitions. This HOWTO shows you how this can be arranged.
The ones ending in .pxe can be booted by a PXE booter. This is useful to chain to Etherboot from PXE. Here are some notes on how to combine PXE and Etherboot.
In addition you can generate .dsk and .lzdsk images. These are just the .rom or .lzrom with the disk loader already prepended, and the size padded out to 18 kB, for reasons of filling out a floppy track. The make command is similar to those above.