This is an old revision of the document!


A PCRE internal error occured. This might be caused by a faulty plugin

====== gPXE Driver API Documentation ====== The current gPXE driver model differs from the previous Etherboot API. Drivers currently conforming to gPXE are: * e1000 * natsemi * rtl8139 The gPXE driver API is detailed in this document. Study of the [[:soc:2008:mdeck:notes:initialization|initialization of a network driver]] may also prove fruitful. ===== Driver Exported Functions ===== The following functions are defined in a gPXE network driver: * ''[[#probe|static int probe ( struct pci_device* , const struct pci_device_id* )]]'' * ''[[#remove|static void remove ( struct pci_device* )]]'' * ''[[#reset|static void reset ( struct net_device* )]]'' * ''[[#open|static int open ( struct net_device* )]]'' * ''[[#close|static void close ( struct net_device* )]]'' * ''[[#transmit|static int transmit ( struct net_device*, struct io_buffer* )]]'' * ''[[#poll|static void poll ( struct net_device* )]]'' * ''[[#irq|static void irq ( struct net_device*, int enable )]]'' In addition, a PCI network driver defines a ''struct pci_driver'': * ''.ids = '' an array of ''struct pci_device_id''s * ''.id_count = '' array count * ''.probe = '' the driver ''probe'' function * ''.remove = '' the driver ''remove'' function ==== probe ==== ''static int probe ( struct pci_device* , const struct pci_device_id* )''\\ This function is called [[:soc:2008:mdeck:notes:initialization|first]] to initialize the card. Here a typical driver will: - Allocate a ''struct net_device'' with associated private data using ''alloc_etherdev()''. - Associate the driver functions with the ''net_device'' via ''netdev_init()''. - Associate the ''net_device'' with the ''pci_device'' via ''pci_set_drvdata()''. - Initialize private data. - Ensure busmastering is enabled and check pci latency with ''adjust_pci_device()''. - Reset the device. - Initialize [[#EEPROM|EEPROM]]. - Read the MAC address from EEPROM. - Mark the ''net_device'' as having a link up with ''netdev_link_up()'', as we don't yet handle the link state. - Name the device and add it to the list of network devices via ''register_netdev()''. - Possibly setup a non-volatile stored options block with ''nvo_init()'' & ''register_nvo()''. ==== remove ==== ''static void remove ( struct pci_device* )''\\ This function is called last to remove the device. A typical driver will: - Call ''unregister_nvo()'' for any registered non-volatile stored options. - Call ''iounmap()'' for any addresses previously mapped with ''ioremap()''. - Call ''unregister_netdev()'' for the device previously registered with ''register_netdev()'' - Reset the device. - Dissociate driver functions from ''net_device'' via ''netdev_nullify()''. - Decrement reference count of ''net_device'' with ''netdev_put()''. ==== reset ==== ''static void reset ( struct net_device* )''\\ This function issues a hardware reset and waits for completion. A typical driver might: - Mask off interrupts. - Clear pending transmits. - Trigger hardware reset. - Wait for completion. ==== open ==== ''static int open ( struct net_device* )''\\ This function is called after ''probe()'' during [[:soc:2008:mdeck:notes:initialization|initialization]]. A driver would: - Program MAC address to device. - Setup TX & RX rings. - Perform other configuration (e.g. filters, bursts, interrupts). - Enable RX and TX. ==== close ==== ''static void close ( struct net_device* )''\\ In this function, a typical driver might: - Acknowledge interrupts. - Disable irq, receives. - Reset the device. - Free any used resources (e.g. rx/tx rings, dma buffers, etc). ==== transmit ==== ''static int transmit ( struct net_device*, struct io_buffer* )''\\ A data transmission is actuated with this routine. A typical driver might: - Check for tx overflow. - Save buffer pointer for later tx completion reference. - Pad & align packet if necessary. - Add packet to transmit ring. - Possibly ensure transmit is on. ==== poll ==== ''static void poll ( struct net_device* )''\\ This function is called periodically to process tx completions and rx packets. A typical driver would: - Acknowledge interrupts. - Feed tx completions to ''netdev_tx_complete()'' or ''netdev_tx_complete_err()''. - Add good received packets to receive queue with ''netdev_rx()'', or feed corrupted packets to ''netdev_rx_err()'' ==== irq ==== ''static void irq ( struct net_device*, int enable )''\\ In this function, a typical driver will: - Enable interrupts if the int parameter is non-zero ===== EEPROM ===== The EEPROM can be accessed via direct port access or using nvs functions. ==== Non-volatile storage (nvs) ==== The nvs functions may be used to access non-volatile storage that conforms to a number of supported SPI protocols. * To initialize nvs support: - The read_bit() and write_bit() function pointers are stored in a ''struct spi_bit_basher''. - The mode & endianness are also initialized. - ''init_spi_bit_basher()'' is called. - A ''struct spi_device'' is initialized (EEPROM-model dependent). - Bus is copied: ''spidev.bus = &spibb.bus'' - EITHER - Initialize a ''struct nvo_block'' with ''nvob.nvs = &spidev.nvs'' - Assign usable regions via ''nvob.fragments = nvof'' where ''nvof'' is an array of ''struct nvo_fragment''s that specify the usable regions. - OR - Call ''nvo_init(&nvob, &spidev.nvs, nvof, ..)'' where ''nvof'' is an array of ''struct nvo_fragment''s that specify the usable regions. * Use ''nvs_read()'' to perform a serial read @ a specific address. * Use ''nvs_write()'' to perform a serial write @ a specific address.


Navigation

* [[:start|Home]] * [[:about|About our Project]] * [[:download|Download]] * [[:screenshots|Screenshots]] * Documentation * [[:howtos|HowTo Guides]] * [[:appnotes|Application Notes]] * [[:faq:|FAQs]] * [[:doc|General Doc]] * [[:talks|Videos, Talks, and Papers]] * [[:hardwareissues|Hardware Issues]] * [[:mailinglists|Mailing lists]] * [[http://support.etherboot.org/|Bugtracker]] * [[:contributing|Contributing]] * [[:editing_permission|Wiki Edit Permission]] * [[:wiki:syntax|Wiki Syntax]] * [[:contact|Contact]] * [[:relatedlinks|Related Links]] * [[:commerciallinks|Commercial Links]] * [[:acknowledgements|Acknowledgements]] * [[:logos|Logo Art]]

QR Code
QR Code soc:2008:mdeck:notes:gpxe_driver_api (generated for current page)