====== Adding gPXE to an AMI BIOS ======

In systems with a motherboard-integrated NIC, the NIC's ROM generally does not exist as a separate entity. Instead, it is read as a sort of "option ROM module" out of the overall BIOS flash. This page contains instructions for replacing the vendor PXE image with gPXE in the flash image of an AMIBIOS-based machine.

My only experience messing with AMIBIOS in this way comes on an Asus eeepc, but the technique should generalize fine to other reasonably recent AMI systems.

Note that while I believe this procedure to be reasonably safe, and have recovered from various failure modes of it without permanently damaging any equipment, you are messing with your motherboard BIOS here, and it's possible for the ROM to be corrupted or the flash to fail in ways that are extremely difficult to recover from without a trip to the manufacturer. Consider yourself warned.

===== Prerequisites =====

**You will need:**
  * a Windows environment;
  * a means of flashing the BIOS on your target machine: a bootable DOS environment with **''AFUDOS.EXE''**, or Windows on your target system and **''AFUWIN.EXE''**, or a BIOS on your target system with an "EZ-Flash" boot-time option;
  * the program **MMtool 3.19**;
  * the latest flash update for your exact machine, as distributed by the manufacturer;
  * a Linux machine, if you want to customize your ROM image.

**''AFUDOS.EXE''**, sometimes ''AFU236U.EXE'', is the AMI Flash Utility for DOS. You can find it in many places, including officially from AMI's website in a [[http://ami.com/support/downloadagreement.cfm?DLFile=support/downloads/amiflash.zip&InpDrvID=90|zip file]] that also includes ''AFUWIN.EXE'' (the Windows version).

**MMtool** is the AMI utility that allows you to add, remove, and replace the sub-images within a flashable ROM file. One of these sub-images is the vendor PXE code, and it can be easily replaced with gPXE. MMtool is not available to the public from AMI's website, nor can we legally redistribute it here, but you should be able to [[http://www.google.com/search?q=MMtool+3.19|find it anyway]].

===== Getting the gPXE ROM =====

You need to determine the PCI Vendor and Device IDs for your onboard NIC, and build a gPXE ROM for that target specifically. [[http://www.rom-o-matic.net/|rom-o-matic]] can help with the second part of that if you don't have a gPXE development environment set up.

**Your ROM image must be below 64kB in size.** This is mostly an issue for Intel e1000 cards, whose stock gPXE ROM is 68kb, and for those crazy folk who try to burn a wireless gPXE image into their BIOS (like the author of this page). Depending on your specific BIOS, you may be able to fit much more than a 64kB image in the flash; I was able to squeeze a 95kb gPXE ROM into my eeepc's flash. But the BIOS will only load option ROMs up to about 75kB, even on a PCI3 system; worse, it appears that before calling gPXE as a boot device it clobbers an area around 64kB after the start of the image in option ROM space.

If your BIOS supports PMM well enough for gPXE to use it (''PMM0020@0010'' [maybe with other numbers] in the ROM banner, not just ''PMM''), you can try using a larger ROM. However, both AMI BIOSes I've worked with are not flexible enough with PMM allocations to let gPXE stay mostly out of option ROM space.

If the preceding explanation went over your head, that's fine; I included it so the curious can find it. Just remember the size limit of 64kB.

===== Creating a modified flash image =====

Extract the vendor flash image from whatever packaging (Zip file, etc) it came in; you want a ''.ROM'' file with a size exactly on a power of 2 (most likely 512kB or 1MB). Get this file onto a Windows machine with MMtool installed; this doesn't need to be the target machine you'll actually be doing the flashing on.

Open MMtool. Click "Load ROM", and navigate to the vendor ROM image. You should see the formerly-empty list box populated with an array of BIOS modules: there's the main BIOS, the CPU microcode, the localized string set, the OEM logo, the video ROM if your motherboard has built-in video... and the NIC ROM. You can spot it by looking for the PCI IDs of your NIC in the "Run Loc" column. The module ID should be 20 and the name should be "PCI Option ROM". (The video ROM will most likely also be a "PCI Option ROM"; make sure you pick the right one!)

Click the "Replace" tab at the top, then click on the entry for your NIC in the list of modules. The Module ID, VendorID, and DeviceID text boxes in the replace pane will be helpfully populated with appropriate values. Click "Browse..." next to the "Module file:" line, find your gPXE ROM, double-check that the VendorID and DeviceID boxes display the correct vendor:device IDs for your NIC, and click Replace. You should see the change reflected in the list of modules; the compression for the gPXE option ROM module will be something like 1%, because gPXE ROM images are already compressed.

It's OK if the order of the PCI Option ROM items changes during this process, e.g. if your video card is now after gPXE when it was before the vendor PXE ROM.

Click "Save ROM as..." and save the flash image as something like "bios-with-gpxe.rom". Get that new ROM file to your target machine. Make sure it's the same size as the original flash image you downloaded from the manufacturer's website.

===== Flashing the BIOS =====

Make sure "Onboard LAN Boot ROM" is enabled in BIOS Setup.

If your target system has Windows installed, you can probably look on your manufacturer's website for a GUI tool that will flash the BIOS. It may or may not accept a raw ROM image, but it's worth a try.

AMI distributes ''AFUWIN.EXE'', a Windows-based flash tool that does accept raw ROM images like the one you just made, freely from its website, as part of the ''amiflash.zip'' distribution. Use that.

Alternatively, if you have a DOS boot floppy, you can copy ''AFUDOS.EXE'' or ''AFU236U.EXE'' onto the floppy, along with your ROM image, and boot your target system with it. Assuming your ROM image is named ''BIOSGPXE.ROM'', you can do
  A:\>AFUDOS /IBIOSGPXE.ROM
to reflash. If it complains, you might have a different version of the flash utility than I; running ''AFUDOS'' will arguments should give you usage information.

Alternatively alternatively, on most AMIBIOS systems, you can press Alt+F2 during the POST screen to get into "EZ-Flash". It will look for the ROM image on a FAT-formatted floppy, a CD-ROM, or a FAT16-formatted USB key, under a system-dependent filename. Details are probably in your computer's manual.

Once you get the BIOS flashed, reboot. You should see something along the lines of
  gPXE (http://etherboot.org) - 03:00.0 6440 PCI3.00 PnP BBS PMM CF00
  Press Ctrl-B to configure gPXE (PCI 03:00.0)...
(the numbers will vary). After POST is done, gPXE will be executed according to its place in the BIOS-configurable boot order. Congratulations on successfully flashing gPXE into your BIOS!

===== Troubleshooting =====

If you see no sign of gPXE at all, but the system boots normally, you may have missed a BIOS setting about the "onboard LAN boot ROM". Double-check.

If you see no sign of gPXE except a message to the effect of "Unable to copy PCI Option ROM  00:03.0" (numbers will vary), you've flashed a gPXE ROM that's too large. You can recover by booting locally and reflashing with something more sane. If you're unlucky and have a less recent BIOS, you might just get a freeze in this case - a good reason to make sure that your gPXE ROM is smaller than 64k!

If you see the gPXE ROM banner shown above, and can boot the system locally, but attempting to boot from gPXE causes a crash/reboot/gibberish filling the screen - especially if you see "gPXE (PCI 03:00.0) starting execution..." before the failure - you have almost certainly used a gPXE ROM image that's over 64kB. Double-check. You can boot locally to recover from this; perhaps reflash with a vendor-provided BIOS upgrade.

If you see the normal BIOS startup screen with CPU/memory/drive information, but you get a freeze, a reboot, or something stranger (I once got output of "''3.000024@04 F000''") before you see any message from gPXE, you probably flashed a corrupted or broken gPXE ROM image. You can recover from this by pressing Alt+F2 while the BIOS startup screen is shown, and following the directions for EZ-Flash above.

If you don't even get to the normal BIOS startup screen, something went very wrong with your flash. This is not a gPXE-specific issue; bugs in the gPXE ROM code could at most reach the previous paragraph in severity. Your system is probably still recoverable, but it might take some doing to recover it. Look to your manual, your manufacturer's website, or the Internet at large for guidance.

===== The possibilities... =====

Using this set of instructions, and disabling every single option in ''config/general.h'' except TFTP and bzImage support, I was able to flash my eeepc with a gPXE ROM image for the built-in ath5k wireless card. It's a lot of fun to be able to boot over the air without a hard drive, any cables, or a USB key! :-)