✎ soc:2008:mdeck:notes:gpxe_driver_api

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.
Trace: • 3c90x.c • week8 • project_plan • week1 • gpxe_driver_api • notes • usermode_overview • skge.c • notes • week5 • git-usage • notes • drivers