The role of a network interface within the system is similar to that of a mounted block device. A block device registers its features in the blk_dev array and other kernel structures, and it then "transmits" and "receives" blocks on request, by means of its request function. Similarly, a network interface must register itself in specific data structures in order to be invoked when packets are exchanged with the outside world.

There are a few important differences between mounted disks and packet-delivery interfaces. To begin with, a disk exists as a special file in the /dev directory, whereas a network interface has no such entry point. The normal file operations (read, write, and so on) do not make sense when applied to network interfaces, so it is not possible to apply the Unix "everything is a file" approach to them. Thus, network interfaces exist in their own namespace and export a different set of operations.

Although you may object that applications use the read and write system calls when using sockets, those calls act on a software object that is distinct from the interface. Several hundred sockets can be multiplexed on the same physical interface.

But the most important difference between the two is that block drivers operate only in response to requests from the kernel, whereas network drivers receive packets asynchronously from the outside. Thus, while a block driver is asked to send a buffer toward the kernel, the network device asksto push incoming packets toward the kernel. The kernel interface for network drivers is designed for this different mode of operation.

Network drivers also have to be prepared to support a number of administrative tasks, such as setting addresses, modifying transmission parameters, and maintaining traffic and error statistics. The API for network drivers reflects this need, and thus looks somewhat different from the interfaces we have seen so far.

The network subsystem of the Linux kernel is designed to be completely protocol independent. This applies to both networking protocols (IP versus IPX or other protocols) and hardware protocols (Ethernet versus token ring, etc.). Interaction between a network driver and the kernel proper deals with one network packet at a time; this allows protocol issues to be hidden neatly from the driver and the physical transmission to be hidden from the protocol.

This chapter doesn't talk about IP numbering schemes, network protocols, or other general networking concepts. Such topics are not (usually) of concern to the driver writer, and it's impossible to offer a satisfactory overview of networking technology in less than a few hundred pages. The interested reader is urged to refer to other books describing networking issues.

The networking subsystem has seen many changes over the years as the kernel developers have striven to provide the best performance possible. The bulk of this chapter describes network drivers as they are implemented in the 2.4 kernel. Once again, the sample code works on the 2.0 and 2.2 kernels as well, and we cover the differences between those kernels and 2.4 at the end of the chapter.

Another feature of snull is that it supports only IP traffic. This is a consequence of the internal workings of the interface -- snull has to look inside and interpret the packets to properly emulate a pair of hardware interfaces. Real interfaces don't depend on the protocol being transmitted, and this limitation of snull doesn't affect the fragments of code that are shown in this chapter.

Assigning IP Numbers

Unfortunately, this effect can't be accomplished through IP-number assignment alone, because the kernel wouldn't send out a packet through interface A that was directed to its own interface B. Instead, it would use the loopback channel without passing through snull. To be able to establish a communication through the snull interfaces, the source and destination addresses need to be modified during data transmission. In other words, packets sent through one of the interfaces should be received by the other, but the receiver of the outgoing packet shouldn't be recognized as the local host. The same applies to the source address of received packets.

To achieve this kind of "hidden loopback," the snull interface toggles the least significant bit of the third octet of both the source and destination addresses; that is, it changes both the network number and the host number of class C IP numbers. The net effect is that packets sent to network A (connected to sn0, the first interface) appear on the sn1 interface as packets belonging to network B.

To avoid dealing with too many numbers, let's assign symbolic names to the IP numbers involved:

• snullnet0 is the class C network that is connected to the sn0 interface. Similarly, snullnet1 is the network connected to sn1. The addresses of these networks should differ only in the least significant bit of the third octet.

• local0 is the IP address assigned to the sn0 interface; it belongs to snullnet0. The address associated with sn1 is local1. local0 and local1 must differ in the least significant bit of their third octet and in the fourth octet.

• remote0 is a host in snullnet0, and its fourth octet is the same as that of local1. Any packet sent to remote0 will reach local1 after its class C address has been modified by the interface code. The host remote1 belongs to snullnet1, and its fourth octet is the same as that of local0.

The operation of the snull interfaces is depicted in Figure 14-1, in which the hostname associated with each interface is printed near the interface name.

 snullnet0       192.168.0.0 snullnet1       192.168.1.0 

 192.168.0.1   local0 192.168.0.2   remote0 192.168.1.2   local1 192.168.1.1   remote1 

The important feature of these numbers is that the host portion of local0 is the same as that of remote1, and the host portion of local1 is the same as that of remote0. You can use completely different numbers as long as this relationship applies.

Be careful, however, if your computer is already connected to a network. The numbers you choose might be real Internet or intranet numbers, and assigning them to your interfaces will prevent communication with the real hosts. For example, although the numbers just shown are not routable Internet numbers, they could already be used by your private network if it lives behind a firewall.

Whatever numbers you choose, you can correctly set up the interfaces for operation by issuing the following commands:

 ifconfig sn0 local0 ifconfig sn1 local1 case "`uname -r`" in 2.0.*)     route add -net snullnet0 dev sn0     route add -net snullnet1 dev sn1 esac 

At this point, the "remote" end of the interface can be reached. The following screendump shows how a host reaches remote0 and remote1 through the snull interface.

morgana% ping -c 2 remote0 64 bytes from 192.168.0.99: icmp_seq=0 ttl=64 time=1.6 ms 64 bytes from 192.168.0.99: icmp_seq=1 ttl=64 time=0.9 ms 2 packets transmitted, 2 packets received, 0% packet loss  morgana% ping -c 2 remote1 64 bytes from 192.168.1.88: icmp_seq=0 ttl=64 time=1.8 ms 64 bytes from 192.168.1.88: icmp_seq=1 ttl=64 time=0.9 ms 2 packets transmitted, 2 packets received, 0% packet loss 

The Physical Transport of Packets

As was mentioned previously, snull only works with IP packets. This limitation is a result of the fact that snull snoops in the packets and even modifies them, in order for the code to work. The code modifies the source, destination, and checksum in the IP header of each packet without checking whether it actually conveys IP information. This quick-and-dirty data modification destroys non-IP packets. If you want to deliver other protocols through snull, you must modify the module's source code.

Module Loading

  struct net_device snull_devs[2] = {     { init: snull_init, },  /* init, nothing more */     { init: snull_init, } }; 

The first struct net_device field we will look at is name, which holds the interface name (the string identifying the interface). The driver can hardwire a name for the interface or it can allow dynamic assignment, which works like this: if the name contains a %d format string, the first available name found by replacing that string with a small integer is used. Thus, eth%d is turned into the first available eth n name; the first Ethernet interface is called eth0, and the others follow in numeric order. The snullinterfaces are called sn0 and sn1 by default. However, if eth=1 is specified at load time (causing the integer variable snull_eth to be set to 1), snull_init uses dynamic assignment, as follows:

  if (!snull_eth) { /* call them "sn0" and "sn1" */     strcpy(snull_devs[0].name, "sn0");     strcpy(snull_devs[1].name, "sn1"); } else { /* use automatic assignment */     strcpy(snull_devs[0].name, "eth%d");     strcpy(snull_devs[1].name, "eth%d"); } 

The other field we initialized is init, a function pointer. Whenever you register a device, the kernel asks the driver to initialize itself. Initialization means probing for the physical interface and filling the net_device structure with the proper values, as described in the following section. If initialization fails, the structure is not linked to the global list of network devices. This peculiar way of setting things up is most useful during system boot; every driver tries to register its own devices, but only devices that exist are linked to the list.

Because the real initialization is performed elsewhere, the initialization function has little to do, and a single statement does it:

  for (i=0; i<2;  i++)     if ( (result = register_netdev(snull_devs + i)) )         printk("snull: error %i registering device \"%s\"\n",                result, snull_devs[i].name);     else device_present++; 

Initializing Each Device

No real probing is performed for the snullinterface, because it is not bound to any hardware. When you write a real driver for a real interface, the usual rules for probing devices apply, depending on the peripheral bus you are using. Also, you should avoid registering I/O ports and interrupt lines at this point. Hardware registration should be delayed until device open time; this is particularly important if interrupt lines are shared with other devices. You don't want your interface to be called every time another device triggers an IRQ line just to reply "no, it's not mine."

The core of snull_init is as follows:

  ether_setup(dev); /* assign some of the fields */  dev->open            = snull_open; dev->stop            = snull_release; dev->set_config      = snull_config; dev->hard_start_xmit = snull_tx; dev->do_ioctl        = snull_ioctl; dev->get_stats       = snull_stats; dev->rebuild_header  = snull_rebuild_header; dev->hard_header     = snull_header; #ifdef HAVE_TX_TIMEOUT dev->tx_timeout     = snull_tx_timeout; dev->watchdog_timeo = timeout; #endif /* keep the default flags, just add NOARP */ dev->flags           |= IFF_NOARP; dev->hard_header_cache = NULL;      /* Disable caching */ SET_MODULE_OWNER(dev); 

  struct snull_priv {     struct net_device_stats stats;     int status;     int rx_packetlen;     u8 *rx_packetdata;     int tx_packetlen;     u8 *tx_packetdata;     struct sk_buff *skb;     spinlock_t lock; }; 

  dev->priv = kmalloc(sizeof(struct snull_priv), GFP_KERNEL); if (dev->priv == NULL)     return -ENOMEM; memset(dev->priv, 0, sizeof(struct snull_priv)); spin_lock_init(& ((struct snull_priv *) dev->priv)->lock); 

Module Unloading

  void snull_cleanup(void) {     int i;         for (i=0; i<2;  i++) {         kfree(snull_devs[i].priv);         unregister_netdev(snull_devs + i);     }     return; } 

Modularized and Nonmodularized Drivers

When a driver is linked directly into the Linux kernel, it doesn't declare its own net_device structures; the structures declared in drivers/net/Space.c are used instead. Space.c declares a linked list of all the network devices, both driver-specific structures like plip1 and general-purpose eth devices. Ethernet drivers don't care about their net_device structures at all, because they use the general-purpose structures. Such general eth device structures declare ethif_probe as their init function. A programmer inserting a new Ethernet interface in the mainstream kernel needs only to add a call to the driver's initialization function to ethif_probe. Authors of non-eth drivers, on the other hand, insert their net_device structures in Space.c. In both cases only the source file Space.c has to be modified if the driver must be linked to the kernel proper.

When a modularized driver is loaded, on the other hand, it declares its own net_device structures (as we have seen in this chapter), even if the interface it controls is an Ethernet interface.

struct net_device can be conceptually divided into two parts: visible and invisible. The visible part of the structure is made up of the fields that can be explicitly assigned in static net_device structures. All structures in drivers/net/Space.c are initialized in this way, without using the tagged syntax for structure initialization. The remaining fields are used internally by the network code and usually are not initialized at compilation time, not even by tagged initialization. Some of the fields are accessed by drivers (for example, the ones that are assigned at initialization time), while some shouldn't be touched.

The Visible Head

The Hidden Fields

We will list the three groups separately, independent of the actual order of the fields, which is not significant.

Interface information

The device methods

Device methods for a network interface can be divided into two groups: fundamental and optional. Fundamental methods include those that are needed to be able to use the interface; optional methods implement more advanced functionalities that are not strictly required. The following are the fundamental methods:

The remaining device operations may be considered optional.

Utility fields

When ifconfig is used to assign an address to the interface, it performs two tasks. First, it assigns the address by means of ioctl(SIOCSIFADDR) (Socket I/O Control Set Interface Address). Then it sets the IFF_UP bit in dev->flag by means of ioctl(SIOCSIFFLAGS) (Socket I/O Control Set Interface Flags) to turn the interface on.

Both device methods return 0 in case of success and the usual negative value in case of error.

As far as the actual code is concerned, the driver has to perform many of the same tasks as the char and block drivers do. open requests any system resources it needs and tells the interface to come up; stop shuts down the interface and releases system resources. There are a couple of additional steps to be performed, however.

 void netif_start_queue(struct net_device *dev); 

The open code for snull looks like the following:

  int snull_open(struct net_device *dev) {     MOD_INC_USE_COUNT;          /* request_region(), request_irq(), .... (like fops->open) */      /*       * Assign the hardware address of the board: use "\0SNULx", where      * x is 0 or 1. The first byte is '\0' to avoid being a multicast      * address (the first byte of multicast addrs is odd).      */     memcpy(dev->dev_addr, "\0SNUL0", ETH_ALEN);     dev->dev_addr[ETH_ALEN-1] += (dev - snull_devs); /* the number */      netif_start_queue(dev);     return 0; } 

As you can see, in the absence of real hardware, there is little to do in the open method. The same is true of the stop method; it just reverses the operations of open. For this reason the function implementing stop is often called closeor release.

  int snull_release(struct net_device *dev) {     /* release ports, irq and such -- like fops->close */      netif_stop_queue(dev); /* can't transmit any more */     MOD_DEC_USE_COUNT;     return 0; }  

 void netif_stop_queue(struct net_device *dev); 

A pointer to sk_buff is usually called skb, and we follow this practice both in the sample code and in the text.

The socket buffer is a complex structure, and the kernel offers a number of functions to act on it. The functions are described later in "The Socket Buffers"; for now a few basic facts about sk_buff are enough for us to write a working driver.

The snull packet transmission code is follows; the physical transmission machinery has been isolated in another function because every interface driver must implement it according to the specific hardware being driven.

  int snull_tx(struct sk_buff *skb, struct net_device *dev) {     int len;     char *data;     struct snull_priv *priv = (struct snull_priv *) dev->priv;     len = skb->len < ETH_ZLEN ? ETH_ZLEN : skb->len;     data = skb->data;     dev->trans_start = jiffies; /* save the timestamp */      /* Remember the skb, so we can free it at interrupt time */     priv->skb = skb;      /* actual delivery of data is device specific, and not shown here */     snull_hw_tx(data, len, dev);      return 0; /* Our simple device cannot fail */ } 

The transmission function thus performs only some sanity checks on the packet and transmits the data through the hardware-related function. That function (snull_hw_tx) is omitted here since it is entirely occupied with implementing the trickery of the snull device (including manipulating the source and destination addresses) and has little of interest to authors of real network drivers. It is present, of course, in the sample source for those who want to go in and see how it works.

Controlling Transmission Concurrency

Real hardware interfaces, on the other hand, transmit packets asynchronously and have a limited amount of memory available to store outgoing packets. When that memory is exhausted (which, for some hardware, will happen with a single outstanding packet to transmit), the driver will need to tell the networking system not to start any more transmissions until the hardware is ready to accept new data.

 void netif_wake_queue(struct net_device *dev); 

This function is just like netif_start_queue, except that it also pokes the networking system to make it start transmitting packets again.

Most modern network interfaces maintain an internal queue with multiple packets to transmit; in this way they can get the best performance from the network. Network drivers for these devices support having multiple transmisions outstanding at any given time, but device memory can fill up whether or not the hardware supports multiple outstanding transmission. Whenever device memory fills to the point that there is no room for the largest possible packet, the driver should stop the queue until space becomes available again.

Transmission Timeouts

Many drivers handle this problem by setting timers; if the operation has not completed by the time the timer expires, something is wrong. The network system, as it happens, is essentially a complicated assembly of state machines controlled by a mass of timers. As such, the networking code is in a good position to detect transmission timeouts automatically.

If the current system time exceeds the device's trans_start time by at least the timeout period, the networking layer will eventually call the driver's tx_timeout method. That method's job is to do whatever is needed to clear up the problem and to ensure the proper completion of any transmissions that were already in progress. It is important, in particular, that the driver not lose track of any socket buffers that have been entrusted to it by the networking code.

snull has the ability to simulate transmitter lockups, which is controlled by two load-time parameters:

  static int lockup = 0; MODULE_PARM(lockup, "i");  #ifdef HAVE_TX_TIMEOUT static int timeout = SNULL_TIMEOUT; MODULE_PARM(timeout, "i"); #endif 

If the driver is loaded with the parameter lockup=n, a lockup will be simulated once every n packets transmitted, and the watchdog_timeo field will be set to the given timeout value. When simulating lockups, snull also calls netif_stop_queue to prevent other transmission attempts from occurring.

The snull transmission timeout handler looks like this:

  void snull_tx_timeout (struct net_device *dev) {     struct snull_priv *priv = (struct snull_priv *) dev->priv;      PDEBUG("Transmit timeout at %ld, latency %ld\n", jiffies,                     jiffies - dev->trans_start);     priv->status = SNULL_TX_INTR;     snull_interrupt(0, dev, NULL);     priv->stats.tx_errors++;     netif_wake_queue(dev);     return; } 

The implementation of snull separates the "hardware" details from the device-independent housekeeping. The function snull_rx is thus called after the hardware has received the packet and it is already in the computer's memory. snull_rx receives a pointer to the data and the length of the packet; its sole responsibility is to send the packet and some additional information to the upper layers of networking code. This code is independent of the way the data pointer and length are obtained.

  void snull_rx(struct net_device *dev, int len, unsigned char *buf) {     struct sk_buff *skb;     struct snull_priv *priv = (struct snull_priv *) dev->priv;      /*      * The packet has been retrieved from the transmission      * medium. Build an skb around it, so upper layers can handle it      */     skb = dev_alloc_skb(len+2);     if (!skb) {         printk("snull rx: low on mem - packet dropped\n");         priv->stats.rx_dropped++;         return;     }     memcpy(skb_put(skb, len), buf, len);      /* Write metadata, and then pass to the receive level */     skb->dev = dev;     skb->protocol = eth_type_trans(skb, dev);     skb->ip_summed = CHECKSUM_UNNECESSARY; /* don't check it */     priv->stats.rx_packets++;     priv->stats.rx_bytes += len;     netif_rx(skb);     return; } 

The function is sufficiently general to act as a template for any network driver, but some explanation is necessary before you can reuse this code fragment with confidence.

Once there is a valid skb pointer, the packet data is copied into the buffer by calling memcpy; the skb_put function updates the end-of-data pointer in the buffer and returns a pointer to the newly created space.

Finally, the driver updates its statistics counter to record that a packet has been received. The statistics structure is made up of several fields; the most important are rx_packets, rx_bytes, tx_packets, and tx_bytes, which contain the number of packets received and transmitted and the total number of octets transferred. All the fields are thoroughly described in "Statistical Information" later in this chpater.

The usual interrupt routine can tell the difference between a new-packet-arrived interrupt and a done-transmitting notification by checking a status register found on the physical device. The snull interface works similarly, but its status word is implemented in software and lives in dev->priv. The interrupt handler for a network interface looks like this:

  void snull_interrupt(int irq, void *dev_id, struct pt_regs *regs) {     int statusword;     struct snull_priv *priv;     /*      * As usual, check the "device" pointer for shared handlers.      * Then assign "struct device *dev"      */     struct net_device *dev = (struct net_device *)dev_id;     /* ... and check with hw if it's really ours */      if (!dev /*paranoid*/ ) return;      /* Lock the device */     priv = (struct snull_priv *) dev->priv;     spin_lock(&priv->lock);      /* retrieve statusword: real netdevices use I/O instructions */     statusword = priv->status;     if (statusword & SNULL_RX_INTR) {         /* send it to snull_rx for handling */         snull_rx(dev, priv->rx_packetlen, priv->rx_packetdata);     }     if (statusword & SNULL_TX_INTR) {         /* a transmission is over: free the skb */         priv->stats.tx_packets++;         priv->stats.tx_bytes += priv->tx_packetlen;         dev_kfree_skb(priv->skb);     }      /* Unlock the device and we are done */     spin_unlock(&priv->lock);     return; } 

The handler's first task is to retrieve a pointer to the correct struct net_device. This pointer usually comes from the dev_id pointer received as an argument.

The interesting part of this handler deals with the "transmission done" situation. In this case, the statistics are updated, and dev_kfree_skb is called to return the (no longer needed) socket buffer to the system. If your driver has temporarily stopped the transmission queue, this is the place to restart it with netif_wake_queue.

Packet reception, on the other hand, doesn't need any special interrupt handling. Calling snull_rx (which we have already seen) is all that's required.

 void netif_carrier_off(struct net_device *dev); void netif_carrier_on(struct net_device *dev); 

If your driver detects a lack of carrier on one of its devices, it should call netif_carrier_off to inform the kernel of this change. When the carrier returns, netif_carrier_on should be called. Some drivers also call netif_carrier_off when making major configuration changes (such as media type); once the adapter has finished resetting itself, the new carrier will be detected and traffic can resume.

 int netif_carrier_ok(struct net_device *dev); 

This can be used to test the current carrier state (as reflected in the device structure).

Although there is no strict need to understand the internals of sk_buff, the ability to look at its contents can be helpful when you are tracking down problems and when you are trying to optimize the code. For example, if you look in loopback.c, you'll find an optimization based on knowledge of the sk_buff internals. The usual warning applies here: if you write code that takes advantage of knowledge of the sk_buff structure, you should be prepared to see it break with future kernel releases. Still, sometimes the performance advantages justify the additional maintenance cost.

The Important Fields

The remaining fields in the structure are not particularly interesting. They are used to maintain lists of buffers, to account for memory belonging to the socket that owns the buffer, and so on.

Functions Acting on Socket Buffers

Using ARP with Ethernet

Overriding ARP

  int snull_header(struct sk_buff *skb, struct net_device *dev,                 unsigned short type, void *daddr, void *saddr,                 unsigned int len) {     struct ethhdr *eth = (struct ethhdr *)skb_push(skb,ETH_HLEN);      eth->h_proto = htons(type);     memcpy(eth->h_source, saddr ? saddr : dev->dev_addr, dev->addr_len);     memcpy(eth->h_dest,   daddr ? daddr : dev->dev_addr, dev->addr_len);     eth->h_dest[ETH_ALEN-1]   ^= 0x01;   /* dest is us xor 1 */     return (dev->hard_header_len); } 

The function simply takes the information provided by the kernel and formats it into a standard Ethernet header. It also toggles a bit in the destination Ethernet address, for reasons described later.

 skb->protocol = eth_type_trans(skb, dev); 

The function extracts the protocol identifier (ETH_P_IP in this case) from the Ethernet header; it also assigns skb->mac.raw, removes the hardware header from packet data (with skb_pull), and sets skb->pkt_type. This last item defaults to PACKET_HOST at skb allocation (which indicates that the packet is directed to this host), and eth_type_trans changes it according to the Ethernet destination address. If that address does not match the address of the interface that received it, the pkt_type field will be set to PACKET_OTHERHOST. Subsequently, unless the interface is in promiscuous mode, netif_rx will drop any packet of type PACKET_OTHERHOST. For this reason, snull_header is careful to make the destination hardware address match that of the "receiving" interface.

Non-Ethernet Headers

When the packet is picked up at the other end of the link, the receiving function in the driver should correctly set the fields skb->protocol, skb->pkt_type, and skb->mac.raw.

skb->mac.raw is a char pointer used by the address-resolution mechanism implemented in higher layers of the networking code (for instance, net/ipv4/arp.c). It must point to a machine address that matches dev->type. The possible values for the device type are defined in <linux/if_arp.h>; Ethernet interfaces use ARPHRD_ETHER. For example, here is how eth_type_trans deals with the Ethernet header for received packets:

 skb->mac.raw = skb->data; skb_pull(skb, dev->hard_header_len); 

In the simplest case (a point-to-point link with no headers), skb->mac.raw can point to a static buffer containing the hardware address of this interface, protocol can be set to ETH_P_IP, and packet_type can be left with its default value of PACKET_HOST.

 int (*do_ioctl)(struct net_device *dev, struct ifreq *ifr, int cmd); 

The ifr pointer points to a kernel-space address that holds a copy of the structure passed by the user. After do_ioctl returns, the structure is copied back to user space; the driver can thus use the private commands to both receive and return data.

The device-specific commands can choose to use the fields in struct ifreq, but they already convey a standardized meaning, and it's unlikely that the driver can adapt the structure to its needs. The field ifr_data is a caddr_t item (a pointer) that is meant to be used for device-specific needs. The driver and the program used to invoke its ioctl commands should agree about the use of ifr_data. For example, pppstats uses device-specific commands to retrieve information from the ppp interface driver.

It's not worth showing an implementation of do_ioctl here, but with the information in this chapter and the kernel examples, you should be able to write one when you need it. Note, however, that the plipimplementation uses ifr_data incorrectly and should not be used as an example for an ioctlimplementation.

  struct net_device_stats *snull_stats(struct net_device *dev) {     struct snull_priv *priv = (struct snull_priv *) dev->priv;     return &priv->stats; } 

unsigned long rx_packets;

unsigned long tx_packets;

These fields hold the total number of incoming and outgoing packets successfully transferred by the interface.

unsigned long rx_bytes;

unsigned long tx_bytes;

The number of bytes received and transmitted by the interface. These fields were added in the 2.2 kernel.

unsigned long rx_errors;

unsigned long tx_errors;

The number of erroneous receptions and transmissions. There's no end of things that can go wrong with packet transmission, and the net_device_stats structure includes six counters for specific receive errors and five for transmit errors. See <linux/netdevice.h> for the full list. If possible, your driver should maintain detailed error statistics, because they can be most helpful to system administrators trying to track down a problem.

unsigned long rx_dropped;

unsigned long tx_dropped;

The number of packets dropped during reception and transmission. Packets are dropped when there's no memory available for packet data. tx_dropped is rarely used.

unsigned long collisions;

The number of collisions due to congestion on the medium.

unsigned long multicast;

The number of multicast packets received.

It is worth repeating that the get_stats method can be called at any time -- even when the interface is down -- so the driver should not release statistic information when running the stop method.

The tricky part of dealing with host groups and hardware addresses is performed by applications and the kernel, and the interface driver doesn't need to deal with these problems.

Transmission of multicast packets is a simple problem because they look exactly like any other packets. The interface transmits them over the communication medium without looking at the destination address. It's the kernel that has to assign a correct hardware destination address; the hard_header device method, if defined, doesn't need to look in the data it arranges.

The kernel handles the job of tracking which multicast addresses are of interest at any given time. The list can change frequently, since it is a function of the applications that are running at any given time and the user's interest. It is the driver's job to accept the list of interesting multicast addresses and deliver to the kernel any packets sent to those addresses. How the driver implements the multicast list is somewhat dependent on how the underlying hardware works. Typically, hardware belongs to one of three classes, as far as multicast is concerned:

• Interfaces that cannot deal with multicast. These interfaces either receive packets directed specifically to their hardware address (plus broadcast packets), or they receive every packet. They can receive multicast packets only by receiving every packet, thus potentially overwhelming the operating system with a huge number of "uninteresting" packets. You don't usually count these interfaces as multicast capable, and the driver won't set IFF_MULTICAST in dev->flags.

  Point-to-point interfaces are a special case, because they always receive every packet without performing any hardware filtering.

• Interfaces that can tell multicast packets from other packets (host-to-host or broadcast). These interfaces can be instructed to receive every multicast packet and let the software determine if this host is a valid recipient. The overhead introduced in this case is acceptable, because the number of multicast packets on a typical network is low.

• Interfaces that can perform hardware detection of multicast addresses. These interfaces can be passed a list of multicast addresses for which packets are to be received, and they will ignore other multicast packets. This is the optimum case for the kernel, because it doesn't waste processor time dropping "uninteresting" packets received by the interface.

The kernel tries to exploit the capabilities of high-level interfaces by supporting at its best the third device class, which is the most versatile. Therefore, the kernel notifies the driver whenever the list of valid multicast addresses is changed, and it passes the new list to the driver so it can update the hardware filter according to the new information.

Kernel Support for Multicasting

The last bit of information needed by the driver developer is the definition of struct dev_mc_list, which lives in <linux/netdevice.h>.

 struct dev_mc_list {         struct dev_mc_list   *next;          /* Next address in list */     _ _u8                 dmi_addr[MAX_ADDR_LEN]; /* Hardware address */     unsigned char        dmi_addrlen;    /* Address length */     int                  dmi_users;      /* Number of users */     int                  dmi_gusers;     /* Number of groups */ }; 

Because multicasting and hardware addresses are independent of the actual transmission of packets, this structure is portable across network implementations, and each address is identified by a string of octets and a length, just like dev->dev_addr.

A Typical Implementation

The best way to describe the design of set_multicast_list is to show you some pseudocode.

The following function is a typical implementation of the function in a full-featured (ff) driver. The driver is full featured in that the interface it controls has a complex hardware packet filter, which can hold a table of multicast addresses to be received by this host. The maximum size of the table is FF_TABLE_SIZE.

All the functions prefixed with ff_ are placeholders for hardware-specific operations.

 void ff_set_multicast_list(struct net_device *dev) {     struct dev_mc_list *mcptr;      if (dev->flags & IFF_PROMISC) {         ff_get_all_packets();         return;     }     /* If there's more addresses than we handle, get all multicast     packets and sort them out in software. */     if (dev->flags & IFF_ALLMULTI || dev->mc_count > FF_TABLE_SIZE) {         ff_get_all_multicast_packets();         return;     }     /* No multicast?  Just get our own stuff */     if (dev->mc_count == 0) {         ff_get_only_own_packets();         return;     }     /* Store all of the multicast addresses in the hardware filter */     ff_clear_mc_list();     for (mc_ptr = dev->mc_list; mc_ptr; mc_ptr = mc_ptr->next)         ff_store_mc_address(mc_ptr->dmi_addr);     ff_get_packets_in_multicast_list(); } 

This implementation can be simplified if the interface cannot store a multicast table in the hardware filter for incoming packets. In that case, FF_TABLE_SIZE reduces to 0 and the last four lines of code are not needed.

As was mentioned earlier, even interfaces that can't deal with multicast packets need to implement the set_multicast_list method to be notified about changes in dev->flags. This approach could be called a "nonfeatured" (nf) implementation. The implementation is very simple, as shown by the following code:

 void nf_set_multicast_list(struct net_device *dev) {     if (dev->flags & IFF_PROMISC)         nf_get_all_packets();     else         nf_get_only_own_packets(); } 

Differences in Linux 2.2

First of all, Linux 2.3.14 renamed the network device structure, which had always been struct device, to struct net_device. The new name is certainly more appropriate, since the structure was never meant to describe devices in general.

unsigned char start;

This variable indicated that the interface was ready for operations; it was normally set to 1 in the driver's openmethod. The current implementation is to call netif_start_queue instead.

unsigned long interrupt;

interrupt was used to indicate that the device was servicing an interrupt -- accordingly, it was set to 1 at the beginning of the interrupt handler and to 0 before returning. It was never a substitute for proper locking, and its use has been replaced with internal spinlocks.

unsigned long tbusy;

When nonzero, this variable indicated that the device could handle no more outgoing packets. Where a 2.4 driver will call netif_stop_queue, older drivers would set tbusy to 1. Restarting the queue required setting tbusy back to 0 and calling mark_bh(NET_BH).

The type of the name field in struct device was different. The 2.2 version was simply

 char *name; 

Thus, the storage for the interface name had to be allocated separately, and name assigned to point to that storage. Usually the device name was stored in a static variable within the driver. The %d notation for dynamically assigned interface names was not present in 2.2; instead, if the name began with a null byte or a space character, the kernel would allocate the next eth name. The 2.4 kernel still implements this behavior, but its use is deprecated. Starting with 2.5, only the %d format is likely to be recognized.

Further Differences in Linux 2.0

The 2.1 development series also saw its share of changes to the network driver interface. Most took the form of small changes to function prototypes, rather than sweeping changes to the network code as a whole.

 void dev_tint(struct device *dev); 

This function would be called by the driver after a lockup had been cleared to restart the transmission of packets.

 int (*rebuild_header) (void *eth, struct device *dev,  unsigned long raddr, struct sk_buff *skb); 

  int snull_rebuild_header(void *buff, struct net_device *dev, unsigned long dst,                     struct sk_buff *skb) {     struct ethhdr *eth = (struct ethhdr *)buff;      memcpy(eth->h_source, dev->dev_addr, dev->addr_len);     memcpy(eth->h_dest, dev->dev_addr, dev->addr_len);     eth->h_dest[ETH_ALEN-1]   ^= 0x01;   /* dest is us xor 1 */     return 0; } 

The device methods for header caching were also significantly different in this kernel. If your driver needs to implement these functions directly (very few do), and it also needs to work with the 2.0 kernel, see the definitions in <linux/netdevice.h> to see how things were done in those days.

Probing and HAVE_DEVLIST

 #ifdef HAVE_DEVLIST /*  * Support for an alternate probe manager,  * which will eliminate the boilerplate below.  */ struct netdev_entry netcard_drv = {cardname, netcard_probe1, NETCARD_IO_EXTENT, netcard_portlist}; #else /* Regular probe routine defined here */