Special Features of Network Devices

Do not look/act like files Do not correspond to inodes in /dev Read and write do not make sense Multiple sockets and protocols can be multiplexed on a single NIC Packets received asynchronously "Pushed" from outside, rather than "pulled" from inside

Image from http://www.checkcomputersetup.com/hardware/computer_network_adapter.html

Linux Network Subsystem

Protocol-independent Driver and kernel interact one packet at a time Separated into: Protocol-independent networking infrastructure (e.g., for all packets) Protocol-specific infrastructure (e.g., for TCP, or for UDP) Generic device-class infrastructure (e.g., for all ethernet devices, or for all PCI devices) Device-specific implementations (e.g., for just the e1000)

Image adapted from http://www.linuxjournal.com/article/4896

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Network Device Descriptor

The datatype struct net_device has many fields, including:

• init -- a pointer to an initialization routine
• name -- string indentifying the interface
  can use a form like "eth%d" to allow the system to plug in a unique number.
• several pointers to interface service routines (methods)

Registering A Network Device: e1000e Ethernet Driver

This driver handles a variety of ethernet controllers based on the Intel 82571, 82572, 82573, 82574, and 82583 chips. The main file is e1000/netdev.c.

The module initialization function e1000_init_module calls

pci_register_driver(&e1000_driver);

That structure contains several fields, including a pointer to a probe function.

static struct pci_driver e1000_driver = {
        .name     = e1000e_driver_name,
        .id_table = e1000_pci_tbl,
        .probe    =  e1000_probe,
        .remove   = __devexit_p(e1000_remove),
        .suspend  = e1000_suspend,
        .resume   = e1000_resume,
        .shutdown = e1000_shutdown,
        .err_handler = &e1000_err_handler};

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

PCI Driver Registration

The pci registration process proceeds through a series of calls

• In e1000_init_module

  pci_register_driver(&e1000_driver);

• Which passes the work directly into the PCI core

  __pci_register_driver(driver, THIS_MODULE, KBUILD_MODNAME);

• Which passes most of the work into the driver core

  driver_register(&drv->driver);

• Which passes most of the work on to the bus core

  bus_add_driver(drv);

Driver Registration: bus_add_driver

• Create a kernel object for the driver

  kobject_init_and_add(&priv->kobj, &driver_ktype, NULL; "%s", drv->name);

  and then link it into various kernel object structures.
• Probe for devices that the driver matches

  driver_attach(drv);

• Notify the userspace device manager of the new driver as a "uevent"

  kobject_uevent(&priv->kobj, KOBJ_ADD);

Driver Registration: driver_attach

Applies __driver_attach to each device on the driver's bus, which

• Calls driver_match_device(drv, dev), to see if the device matches one of those that this driver has claimed to able to manage in the table e1000_pci_tbl.
  • The work is done by the match method drv->bus->match (dev, drv)
  • In this case, the call is to pci_bus_match, which in turn calls pci_match_device, which runs down the device's table looking for matches between device and driver
• If there is a match, it calls driver_probe_device(drv, dev), which passes the job off to really_probe(dev, drv);.

Driver Registration: really_probe

• Create a sysfs entry for the driver

  driver_sysfs_add(dev);

• Call the probe method of the bus dev->bus->probe or driver drv->probe, which in our case is the function e1000_probe
• The probe function FINALLY gets around to looking at the device!

Driver & Device Descriptors

Image from http://book.chinaunix.net/special/ebook/oreilly/Understanding_Linux_Network_Internals/

Driver Registration: e1000_probe

This function does a lot of things, most of which are specific to the device. We focus on the parts that relate to its role as a generic network device.

• Allocate and initialize an object of type struct net_device to represent the device that is being probed

  netdev = alloc_etherdev(sizeof(struct e1000_adapter));

• The object created above contains a nested object of type e1000_adapter, which is accessed later via the macro

  netdev_priv(netdev)

Driver Registration: alloc_etherdev

• The function alloc_etherdev calls

  alloc_etherdev_mq(sizeof(struct e1000_adapter), 1);

  which calls

  alloc_netdev_mq(sizeof(struct e1000_adapter), "eth%d", ether_setup, 1);

• Much of the work of alloc_netdev_mq() is done by a call setup(dev); to function parameter that is passed in, which in this case is ether_setup.

Driver Registration: e1000_probe

• The function e1000_probe() initializes the structure returned by alloc_etherdev().
• One of the interesting features is the setting up of two timers, including a watchdog timer with handler e1000_watchdog.
• It also does a lot of work to set up the device for DMA.
• An interesting feature is initialization of the netdev_ops member to point to a struct net_device_ops that defines the operations on the network device, including ndo_open() and ndo_stop() (see next slide).

Opening/Closing A Network Device

ndo_open

• called in response to ioctl(SIOCSIFFLAGS) call from ifconfig
• requests system resources (e.g., irq, buffer space)
• activates the hardware interface

ndo_stop

• called in response to another ioctl(SIOCSIFFLAGS) call (with IFF_UP cleared) from ifconfig
• undoes effects of open()

See e1000_open for example. Notice the up-call to the network layer function netif_start_queue.

Network Driver Interrupts (typical)

• From NIC
  • Reception of a frame
  • Transmission failure
  • DMA transfer has completed successfully
  • Device has has enough memory to handle a new transmission
• Other
  • Watchdog timeout

Socket Buffers

The datatype struct sk_buff, is used to hold packets that go to or from sockets. It has quite a few fields, including some tagged as "important" by the LDD3 text. Unfortunately, the names of these fields appear to have changed since the book was written. The names of the "important" fields are:

• dev = the sending or receiving device
• pointers (or offsets) to headers within packet, of type sk_buff_data_t
  • transport_header
  • network_header
  • mac_header = link layer header
  • tail = end of valid data
  • end = maximum value tail can reach
• len = length of actual data in packet (= tail - data)
• data_len = nonzero only for scatter-gather
  length of portion stored in separate fragments
• ip_summed = the checksum policy (set by driver on incoming packets)
• pkt_type = delivery classification (set by eth_type_trans())
  • PACKET_HOST -- for the local host
  • PACKET_BROADCAST
  • PACKET_MULTICAST
  • PACKET_OTHERHOST
  • PACKET_OUTGOING
  • PACKET_LOOPBACK
  • PACKET_FASTROUTE
• pointers to components of the packet
  • head = beginning of space
  • data = beginning of valid data
  • truesize = buffer size
  • users = user count

sk_buff without Scatter-Gather

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Scatter-Gather I/O

• normally used for outgoing network packets
• allows layers of packet headers to be added, for each layer of protocol
  without recopying the packet
• accomodated by the sk_buff datatype
• macro skb_shinfo returns pointer to the "shareable data" of a sk_buff object, of type struct skb_shared_info
  • nr_frags = number of fragments (beyond the the first sk_buff) in the packet
  • frag_list
  • frags = pointer to array of skb_frag_struct, each with the following fields:
    • struct page *page
    • __u16 page_offset
    • __u16 size

sk_buff with Scatter-Gather

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

struct msghdr {
      void         * msg_name;     /* optional address */
      socklen_t    msg_namelen;    /* size of address */
      struct iovec * msg_iov;      /* scatter/gather array */
      size_t       msg_iovlen;     /* # elements in msg_iov */
      void         * msg_control;  /* ancillary data, see below */
      socklen_t    msg_controllen; /* ancillary data buffer len */
      int          msg_flags;      /* flags on received message */
  };
  struct iovec {
      void *iov_base;   /* Starting address */
      size_t iov_len;   /* Number of bytes */
  };

Receiving a Packet

The end goal of the driver is to pass off each packet that it receives, to the higher-level protocol handling routines of the system.

There are two models of packet reception that a driver may implement

• interrupt-driven --
  • each packet arrival generates an interrupt
  • can paralyze the system if there is a "packet storm"
  • implemented by the toy driver, snull.c in the LDD3 text, but not by the e1000 driver
  • a packet is passed off via a call to netif_rx()
• polling -- (better)
  • packet arrivals only generate an interrupt if the system is not actively polling
  • reduced overhead due to interrupts when the system is already busy
  • implemented by the snull, e100, and e1000 drivers
  • a packet is passed off via a call to netif_receive_skb

All the input processing builds up to this.

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

NAPI

Linux "Newer API" for network drivers Combines benefits of polling and interrupts We will not discuss the API presented in the LDD3 text, since it is no longer supported.

Image from http://www.goodexperience.com/tib/archives/signs/

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Pre-NAPI (interrupt-driven) Linux Networking

Data Flow of Pre-NAPI Linux Network Driver API

The diagrams above are reproduced from piters.home.cern.ch/piters/ TCP/seminar/TDAQ-April02/TDAQ-April02.ps.

NAPI Model

Interrupt from NIC is normally disabled Driver has thread that polls to see if there is work for the driver to do: Handling received (RX) packets: undo DMA mapping, parse link-level packet header, pass packet up to next level of protocol stack Cleaning up transmitted (TX) packets: undo DMA mapping, recycle buffer, possibly notify sender If thread finds no work to do, it enables the interrupt Interrupt handler disables interrupt and signals polling thread

NAPI Advantages

• Less time wasted in overhead of interrupt handling
• Poller can handle several packets in one cycle
• If packets must be dropped (due to overload) they are dropped before wasting CPU time on them

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

struct napi_struct

• Used to implement NAPI for a specific device
• Similar to a tasklet, specialized for handling NAPI polling
• Member state:
  • NAPI_STATE_SCHED - poll is scheduled
  • NAPI_STATE_DISABLE - disable pending
  • NAPI_STATE_NPSVC - netpoll, don't dequeue from poll_list

Value NAPI_STATE_NPSVS provides support for the "Netpoll" option, i.e., pure polling.

Packet Reception in the e1000 Driver

• A polling function is registered with the network_device layer, responsible for passing packets up to the network layer

  
  netif_napi_add(netdev, &adapter->napi, e1000_clean, 64);

• DMA receive-buffers are allocated for the device, and an interrupt handler is installed, responsible for activating polling

  
  adapter->clean_rx = e1000_clean_rx_irq;
  adapter->alloc_rx_buf = e1000_alloc_rx_buffers;

The e1000 driver provides optional support for Netpoll (the pure polling), but we will not discuss that further here.

Receive-Buffer Allocation

The data structure passed to netif_rx() is a struct sk_buff, which is allocated here:

skb
= netdev_alloc_skb(netdev, bufsz);

The function netdev_alloc_skb() is called from e1000_alloc_rx_buffers which allocates a socket buffer of size ETH_FRAME_LEN + VLAN_HLEN + ETH_FCS_LEN.

Receive Descriptor Ring

Driver Allocates buffer Maps it for DMA access Places buffer address into the Receive Descriptor Queue Structure (a circular/ring buffer) Advances the Tail pointer Device Fills the Head buffer Puts some data into the corresponding Receive Descriptor Advances the Head pointer

Receive Descriptor (RDESC)

• Status - bit vector, including
  • EOP - Is this the last descriptor of a packet?
  • DD - Is hardware is done with the descriptor? (should be initialized to zero by driver)
• Length -
• Packet Checksum -
• Errors - bit vector, one bit per error type
• VLAN Tag - (only nonzero for 8023.1q packets)

This is the "legacy" format. There is also an extended version, which allows the device to provide additional information.

Receive Buffers (Split Mode)

Optionally, the device can split the packet header into a separate buffer This requires an extended RDESC format, with room for multiple buffer addresses

The e1000e driver does support this option, but we will not discuss any of these extended formats further here.

Transmit Descriptor Ring

Driver Allocates buffer Maps it for DMA access Places buffer address and other fields into the Receive Descriptor Queue Structure (a circular/ring buffer) Advances the Tail pointer Device Transmits data from the Head buffer Writes some status into the corresponding Transmit Descriptor Advances the Head pointer

Transmit Descriptor

• STA - status bit vector, including
  • DD - has the hardware finished with this buffer?
  • EC - has the transmission been abortd, to excess collisions?
• Length -
• CMD - command (see next slide)
• CSS - where to start computing TCP checksum
• CSO - offset to place TCP checksum

Again, this is the "legacy" format. There are also several extended versions, which allows the device to perform additional functions, offloading some of the work that otherwise would need to be done by the operating system.

e1000 Interrupts

• The cause(s) of an interrupt are discoverable via the Interrupt Cause Register of the device (ICR)
• Examples of causes include:

  TXDW - Transmit Descriptor Written Back TXQE - Transmit Queue Empty LSC - Link Status Change RXSEQ - Receive Sequence Error ("framing error")

  RXDMTO - Receive Descriptor Minimum Threshold Reached (low buffer count) RXO - Receiver Overrrun RXTO - Receiver Timer Interrupt ...

• Reading the ICR register automatically acknowledges every interrupt specified in the Interrupt Acknowledge Auto Mask Register (IAM)
• All interrupts can be masked by writing to the Interrupt Mask Clear (IMC) register

For more details on the e1000 chips, see the Intel documentation.

Network Device Polling

In net_dev_init, which is called during system initialization to initialize the network device subsystem, the function net_rx_action is attached to the softirq NET_RX_SOFTIRQ.

When the function net_rx_action is called, in response to this softirq, it runs though a per-CPU softnet_data queue, executing the poll method of each device on the queue.

e1000 Polling

In the case of the e100, the polling function is e1000_clean. The most interesting parts of this function are the actual polling call

adapter->clean_rx(adapter, &adapter->rx_ring[0], &work_done, budget);

and the NAPI logic

if (work_done < budget) {
   if (likely(adapter->itr_setting & 3)) e1000_set_itr(adapter);
   napi_complete(napi);
   if (!test_bit(__E1000_DOWN, &adapter->flags))
   e1000_irq_enable(adapter);
}

See also the corresponding code, which calls the polling function, in net_rx_action.

e1000 Polling

The function called by adapter->cleanrx(...) is one of the three different functions that may be assigned in e1000_configure_rx, depending on the MTU size.

The most typical one is e1000_clean_rx_irq.

After many steps, it gets to netif_receive_skb(skb), and from there to deliver_skb, which calls the delivery method appropriate to the protocol

return pt_prev->func(skb, skb->dev, pt_prev, orig_dev);

Sending a Packet

Sending of a packet starts with one application-level calls, like send() or sendto(). After the system determines the route and assembles the packet with the appropriate headers, it eventually makes an internal call to the ndo_start_xmit method of the actual device.

For the e1000 driver, the actual function bound to this link is e1000_xmit_frame, which calls e1000_tx_queue to actuallyl enqueue the frame on the transmit-buffer ring of the devices.

Timeouts

• can detect failures
  • hardware bugs
  • driver bugs
  • failures/bugs of communication partners (other hosts)

Review of Uses of Memory Mapping in the e1000 Driver

• Device memory is mapped into the kernel space in e1000_probe

  adapter->hw.hw_addr = ioremap(mmio_start, mmio_len);

• Each receive socket buffer is mapped for DMA acccess in e1000_alloc_rx_buffers

  
  buffer_info->dma = pci_map_single(pdev, skb->data,
                                    adapter->rx_buffer_len,
                                    PCI_DMA_FROMDEVICE);

• ... List needs completing.

Review of Uses of Interrupts in the e1000 Driver

• e1000_open() calls e1000_request_irq, to install an interrupt handler

  err = request_irq(adapter->pdev->irq, &e1000_intr, IRQF_SHARED,
                    netdev->name, netdev);

• e1000_intr
  • reads the status of the device
  • acknowledges the interrupt to the device
  • in all cases, calls napi_schedule_prep to make certain an effort is under way to process the packets already received

References

• http://book.chinaunix.net/special/ebook/oreilly/Understanding_Linux_Network_Internals/: Understanding Linux Network Internals, by Christian Benvenuti (O'Reilly on-line) - a 2006 book, with lots of details, but becoming outdated, like LDD3