This is an old revision of the document!
====== gPXE Driver API Documentation ====== :!: Under Construction ===== Driver Exported Functions ===== The following functions should be defined in any 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, your driver should define a ''struct pci_driver'' where >''.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 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* )''\\ In this function, a driver might: - 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* )''\\ In this function, 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* )''\\ In this function, a typical driver might: - 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.
