net_device

include/linux/netdevice.h

The net_device data structure stores all information specifically regarding a network device.There is one such structure for each device, both real ones (such as Ethernet NICs) and virtual ones (such as bonding* or VLAN†).

The net_device structures for all devices are put into a global list to which the global variable dev_base points.

int ifindex
A unique ID, assigned to each device when it is registered with a call to dev_new_index.

int iflink
This field is mainly used by (virtual) tunnel devices and identifies the real device that will be used to reach the other end of the tunnel.

unsigned short dev_id
Currently used by IPv6 with the zSeries OSA NICs. The field is used to differentiate between virtual instances of the same device that can be shared between different OSes concurrently.

char name[IFNAMSIZ]
Name of the device (e.g., eth0).

unsigned long mem_start
unsigned long mem_end
These fields describe the shared memory used by the device to communicate with the kernel. They are initialized and accessed only within the device driver; higher layers do not need to care about them.

unsigned long base_addr
The beginning of the I/O memory mapped to the device’s own memory.

unsigned int irq
The interrupt number used by the device to talk to the kernel. It can be shared among multiple devices. Drivers use the request_irq function to allocate this variable and free_irq to release it.

unsigned char if_port
The type of port being used for this interface.
Some devices come with more than one connector (the most common combination is BNC + RJ45) and allow the user to select one of them depending on her needs. This parameter is used to set the port type for the device.There are also cases where a single device driver can handle different interface models; in those situations, the interface can discover the port type to use by simply trying all of them in a specific order.

unsigned char dma
The DMA channel used by the device (if any).
To obtain and release a DMA channel from the kernel, the functions request_dma and free_dma. To enable or disable a DMA channel after obtaining it, the functions enable_dma and disable_dma are provided in various include/asmarchitecture files (e.g., include/asm-i386). The routines are used by ISA devices; Peripheral Component Interconnect (PCI) devices do not need them because they use others instead.
DMA is not available for all devices because some buses don’t use it.

unsigned short flags
unsigned short gflags
unsigned short priv_flags
Some bits in the flags field represent capabilities of the network device (such as IFF_MULTICAST) and others represent changing status (such as IFF_UP or IFF_RUNNING). You can find the complete list of these flags in include/linux/if.h. The device driver usually sets the capabilities at initialization time, and the status flags are managed by the kernel in response to external events. The settings of the flags can be viewed through the familiar ifconfig command:
bash# ifconfig lo
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
UP LOOPBACK RUNNING MTU:3924 Metric:1
RX packets:198 errors:0 dropped:0 overruns:0 frame:0
TX packets:198 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
In this example, the words UP LOOPBACK RUNNING correspond to the flags IFF_UP, IFF_LOOPBACK, and IFF_RUNNING. priv_flags stores flags that are not visible to the user space. Right now this field is used by the VLAN and Bridge virtual devices. gflags is almost never used and is there for compatibility reasons. Flags can be changed through the dev_change_flags function.

int features
Another bitmap of flags used to store some other device capabilities. It is not redundant for this data structure to contain multiple flag variables. The features field reports the card’s capabilities for communicating with the CPU, such as whether the card can do DMA to high memory, or checksum all the packets in hardware. The list of the possible features is defined inside the structure net_device itself. This parameter is initialized by the device driver. You can find the list of NETIF_F_XXX features, along with good comments, inside the net_device data structure definition.

unsigned mtu
MTU stands for Maximum Transmission Unit and it represents the maximum size of the frames that the device can handle.

unsigned short type
The category of devices to which it belongs (Ethernet, Frame Relay, etc. include/linux/if_arp.h ).

unsigned short hard_header_len
The size of the device header in octets. The Ethernet header, for instance, is 14 octets long.

unsigned char broadcast[MAX_ADDR_LEN]
The link layer broadcast address.

unsigned char dev_addr[MAX_ADDR_LEN]
unsigned char addr_len
dev_addr is the device link layer address; do not confuse it with the L3 or IP address. The address’s length in octets is given by addr_len. The value of addr_len depends on the type of device. Ethernet addresses are six octets long.

int promiscuity
Certain network administration tasks require a system to receive all the frames that travel across a shared cable, not just the ones directly addressed to it; a device that receives all packets is said to be in promiscuous mode.
The net_device structure contains a counter named promiscuity that indicates a device is in promiscuous mode. The reason it is a counter rather than a simple flag is that several clients may ask for promiscuous mode;
Whenever promiscuity is nonzero (such as through a call to dev_set_promiscuity), the IFF_PROMISC bit flag of flags is also set and is checked by the functions that configure the interface.

Statistics

Instead of providing a collection of fields to keep statistics, the net_device structure includes a pointer named priv that is set by the driver to point to a private data structure storing information about the interface. The private data consists of statistics such as the number of packets transmitted and received and the number of errors encountered.
The data structure to which priv points sometimes has a name reflecting the interface (e.g., vortex_private for the Vortex and Boomerang series, also called the 3c59x family), and other times is simply called net_local. Still, the fields in net_local are defined uniquely by each device driver.

Device Status

unsigned long state
A set of flags used by the network queuing subsystem. They are indexed by the constants in the enum netdev_state_t

enum {...} reg_state
The registration state of the device

unsigned long trans_start
The time (measured in jiffies) when the last frame transmission started. The device driver sets it just before starting transmission. The field is used to detect problems with the card if it does not finish transmission after a given amount of time. An overly long transmission means there is something wrong; in that case, the driver usually resets the card.

unsigned long last_rx
The time (measured in jiffies) when the last packet was received. At the moment, it is not used for any specific purpose, but is available in case of need.

struct net_device *master
Some protocols exist that allow a set of devices to be grouped together and be treated as a single device. These protocols include EQL (Equalizer Load-balancer for serial network interfaces), Bonding (also called EtherChannel and trunking), and the TEQL (true equalizer) queuing discipline of Traffic Control. One of the devices in the group is elected to be the so-called master, which plays a special role. This field is a pointer to the net_device data structure of the master device of the group. If the interface is not a member of such a group, the pointer is simply NULL.

spinlock_t xmit_lock
int xmit_lock_owner
The xmit_lock lock is used to serialize accesses to the driver function hard_start_xmit. This means that each CPU can carry out only one transmission at a time on any given device. xmit_lock_owner is the ID of the CPU that holds the lock. It is always 0 on single-processor systems and –1 when the lock is not taken on SMP systems. It is possible to have lockless transmissions, too, when the device driver supports it.

void *atalk_ptr
void *ip_ptr
void *dn_ptr
void *ip6_ptr
void *ec_ptr
void *ax25_ptr
These six fields are pointers to data structures specific to particular protocols, each data structure containing parameters that are used privately by that protocol.

List Management

net_device data structures are inserted into a global list and into two hash tables

struct net_device *next
Links each net_device data structure to the next in the global list.

struct hlist_node name_hlist
struct hlist_node index_hlist
Link the net_device structure to the bucket’s list of two hash tables.

Link Layer Multicast

Multicast is a mechanism used to deliver data to multiple recipients. Multicasting can be available both at the L3 network layer (i.e., IP) and at the L2 link layer (i.e., Ethernet).

Link layer multicast delivery can be achieved by using special addresses or control information in the link layer header.

Multicast addresses are distinguished from the range of other addresses by a specific bit. This means that 50% of the possible addresses are multicast, and 50% of 248 is a huge number! When an interface is asked to join a lot of multicast groups (each identified by a multicast address), it may be more efficient and faster for it to simply listen to all the multicast addresses instead of maintaining a long list and wasting time filtering ingress L2 multicast frames based on the list. One of the flags in the net_device data structure indicates whether the device should listen to all addresses.

Each device keeps an instance of the dev_mc_list structure for each link layer multicast address it listens to

struct dev_mc_list *mc_list
Pointer to the head of this device’s list of dev_mc_list structures.

int mc_count
The number of multicast addresses for this device, which is also the length of the list to which mc_list points.

int allmulti
When nonzero, causes the device to listen to all multicast addresses. allmulti is a reference count. When the variable goes from 0 to nonzero, the function dev_set_allmulti is called to instruct the interface to listen to all multicast addresses. The opposite happens when allmulti goes to 0.

Traffic Management

struct net_device *next_sched
Used by one of the software interrupts

struct Qdisc *qdisc
struct Qdisc *qdisc_sleeping
struct Qdisc *qdisc_ingress
struct list_head qdisc_list
These fields are used to manage the ingress and egress packet queues and access to the device from different CPUs.

spinlock_t queue_lock
spinlock_t ingress_lock
The Traffic Control subsystem defines a private egress queue for each network device. queue_lock is used to avoid simultaneous accesses to it . ingress_lock does the same for ingress traffic.

unsigned long tx_queue_len
The length of the device’s transmission queue. When Traffic Control support is present in the kernel, tx_queue_len may not be used (only a few queuing discipline use it).
Note that all devices with a queue length of 0 are virtual devices: they rely on the associated real devices to do any queuing (with the exception of the loopback device, which does not need it because it is internal to the kernel and delivers all traffic immediately).

Feature Specific

struct divert_blk *divert
Diverter is a feature that allows you to change the source and destination addresses of the incoming packet. This makes it possible to reroute traffic with specific characteristics specified by the configuration to a different interface or a different host. To work properly and to make sense, diverter needs other features such as bridging. The data structure pointed to by this field stores the parameters needed by the diverter feature.

struct net_bridge_port *br_port
Extra information needed when the device is configured as a bridged port

void (*vlan_rx_register)(...)
void (*vlan_rx_add_vid)(...)
void (*vlan_rx_kill_vid)(...)
These three function pointers are used by the VLAN code to register a device as VLAN tagging capable (see net/8021q/vlan.c), add a VLAN to the device, and delete the VLAN from the device, respectively.

int netpoll_rx
void (*poll_controller)(...)
Used by the optional Netpoll feature

Generic

atomic_t refcnt
Reference count. The device cannot be unregistered until this counter has gone to zero

int watchdog_timeo
struct timer_list watchdog_timer
implement the “Watchdog timer”

int (*poll)(...)
struct list_head poll_list

int quota
int weight
Used by the NAPI feature

const struct iw_handler_def *wireless_handlers
struct iw_public_data *wireless_data
Additional parameters and function pointers used by wireless devices

struct list_head todo_list
The registration and unregistration of a network device is done in two steps. todo_list is used to handle the second one

struct class_device class_dev
Used by the new generic kernel driver infrastructure

Function Pointers

struct ethtool_ops *ethtool_ops
Pointer to a set of function pointers used to set or get the configuration of different device parameters

int (*init)(...)
void (*uninit)(...)
void (*destructor)(...)
int (*open)(...)
int (*stop)(...)
Used to initialize, clean up, destroy, enable, and disable a device. Not all of them are always used.

struct net_device_stats* (*get_stats)(...)
struct iw_statistics* (*get_wireless_stats)(...)
Some statistics collected by the device driver can be displayed with user-space applications such as ifconfig and ip, and others are strictly used by the kernel. These two methods are used to collect statistics. get_stats operates on a normal device and get_wireless_stats on a wireless device

int (*hard_start_xmit)(...)
Used to transmit a frame

int (*hard_header)(...)
int (*rebuild_header)(...)
int (*hard_header_cache)(...)
void (*header_cache_update)(...)
int (*hard_header_parse)(...)
int (*neigh_setup)(...)
Used by the neighboring layer

int (*do_ioctl)(...)
ioctl is the system call used to issue commands to devices. This method is called to process some of the ioctl commands.

void (*set_multicast_list)(...)
This method is used to ask the device driver to configure the device to listen to those addresses. Usually it is not called directly, but through wrappers such as dev_mc_upload or its lockless version, _ _dev_mc_upload. When a device cannot install a list of multicast addresses, it simply enables all of them.

int (*set_mac_address)(...)
Changes the device MAC address. When the device does not provide this capability (as in the case of Bridge virtual devices), it is set to NULL.

int (*set_config)(...)
Configures driver parameters, such as the hardware parameters irq, io_addr, and if_port. Higher-layer parameters (such as protocol addresses) are handled by do_ioctl. Not many devices use this method, especially among the new devices that are better able to implement probe functions.

int (*change_mtu)(...)
Changes the device MTU. Changing this field has no effect on the device driver but simply forces the kernel software to respect the new MTU and to handle fragmentation accordingly.

void (*tx_timeout)(...)
The method invoked at the expiration of the watchdog timer, which determines whether a transmission is taking a suspiciously long time to complete. The watchdog timer is not even started unless this method is defined

int (*accept_fastpath)(...)
Fast switching (also called FASTROUTE) was a kernel feature that allowed device drivers to route incoming traffic during interrupt context using a small cache (bypassing all the software layers). Fast switching is no longer supported, starting with the 2.6.8 kernel. This method was used to test whether the fastswitching feature could be used on the device.