✎ faq:drivers - Etherboot/gPXE Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Driver FAQ =====

==== How do I check if a network card is supported? ====

When a PCI network card is detected, its PCI ID is used to identify it and choose an appropriate driver.  Each network card driver has a list of PCI IDs it supports.

The format of a PCI ID is ''VVVV:DDDD'', where the ''VVVV'' field is called the Vendor ID and the ''DDDD'' field is called the Device ID.

  - Find out the PCI ID of the network card:
    * On Linux using ''lspci -nn''.  Look for ''Ethernet controller''.
    * In gPXE using ''show net0/busid''.  Ignore for first byte, e.g. busid ''01:10:ec:81:39'' -> PCI ID ''10ec:8139''.
  - Check if there is a gPXE driver for this PCI ID:
    * Ask ''gpxebot'' on #etherboot IRC like this: ''gpxebot: lspci 10ec:8139''.
    * Search the gPXE source code for the Device ID, looking for lines of code like this:

  PCI_ROM(0x10ec, 0x8139, "rtl8139", "Realtek 8139", 0),

==== What if there is no driver for my network card? ====

If there is no native gPXE driver for a network card, there are two choices:
  - Develop a driver or extend an existing driver to support the network card.
  - Use the generic UNDI driver, which works for many use cases but is not equivalent to a native driver.

Before falling back to the UNDI driver, speak with the developers about the effort required to add native driver support for the network card.  Sometimes there is already a native driver and it simply needs a line added with the PCI ID of the network card.

There are developers in the community who do paid driver development work and can help you add support for new network cards.  Ask on the mailing list.

==== Can open source Linux or BSD drivers be used with gPXE? ====

No.  Although the gPXE driver API is similar to the Linux API, drivers are not compatible at the source or binary level.  Open source drivers can be ported to gPXE or used as a starting point for developing gPXE drivers.  This is especially useful for network cards where no datasheet is available from the vendor.

==== Where do I start with developing a new driver? ====

You must be able to program in C.  Device driver development knowledge on other platforms is useful but not required.

[[http://etherboot.org/wiki/soc/2008/mdeck/notes/gpxe_driver_api|Michael Decker's gPXE driver API documentation]] shows the interface that a driver must implement.

Study the code in ''gpxe/src/drivers/net''.  The ''rtl8139'' and ''r8169'' drivers are good examples.  Note that some drivers are not written for the gPXE API but use a wrapper for the legacy Etherboot API instead.  New drivers should use the gPXE API.

[[http://lwn.net/Kernel/LDD3/|Linux Device Drivers]] is a good reference for understanding Linux drivers and learning general driver development concepts.

==== How can I use the UNDI driver if there is no native driver? ====

The UNDI driver is a generic driver that works on network cards that have a vendor UNDI ROM.  The ROM contains driver code that is supposed to conform to the PXE/UNDI specification.  gPXE can load the UNDI driver and use it instead of a native driver.

Depending on the gPXE image type, UNDI support works as follows:
  - ''undionly.kpxe'' is loaded from a vendor PXE stack and uses UNDI on the network card that it was booted from.
  - All-driver (''gpxe'') or ''undi'' images can load the UNDI for PCI network cards.  The network boot ROM must be enabled in the BIOS in order for the UNDI ROM to be visible to gPXE.  Note that only the first network card is supported with UNDI since multiple instances of UNDI is unreliable and cannot be supported.

==== Why write native drivers if UNDI works with every network card? ====

  - gPXE is an open source PXE stack and provides UNDI services.  gPXE cannot be used as an option ROM without a native driver.
  - UNDI is slow because gPXE must switch CPU modes when calling it.
  - UNDI ROMs can be buggy or violate the PXE specification.  Native drivers are known to work with gPXE and can be fixed if there is a bug since they are part of the gPXE codebase.
  - Enabling the network boot ROM in the BIOS is not always possible or desirable.
Trace: • week2 • welcome • journal • officialdebian • qemupxe • week1 • week12 • nikhilcrao • revised_timeline • wrapup • sanboot • appnotes • week3 • ubuntu_iscsi • week3 • start • httpboot • less1 • week2 • week7