Manual Pages  — IFNET

The system keeps a linked list of interfaces using the TAILQ macros defined in queue(3); this list is headed by a struct ifnethead called ifnet. The elements of this list are of type struct ifnet, and most kernel routines which manipulate interface as such accept or return pointers to these structures. Each interface structure contains an if_data structure used for statistics and information. Each interface also has a TAILQ of interface addresses, described by ifaddr structures. An AF_LINK address (see link_addr(3)) describing the link layer implemented by the interface (if any) is accessed by the ifaddr_byindex() function or if_addr structure. (Some trivial interfaces do not provide any link layer addresses; this structure, while still present, serves only to identify the interface name and index.)

Finally, those interfaces supporting reception of multicast datagrams have a TAILQ of multicast group memberships, described by ifmultiaddr structures. These memberships are reference-counted.

Interfaces are also associated with an output queue, defined as a struct ifqueue; this structure is used to hold packets while the interface is in the process of sending another.

The macro IFF_CANTCHANGE defines the bits which cannot be set by a user program using the SIOCSIFFLAGS command to ioctl(2); these are indicated by an asterisk (‘*’) in the following listing.

IFF_UP	<D> The interface has been configured up by the user-level code.
IFF_BROADCAST	<S*> The interface supports broadcast.
IFF_DEBUG	<D> Used to enable/disable driver debugging code.
IFF_LOOPBACK	<S> The interface is a loopback device.
IFF_POINTOPOINT
	<S*> The interface is point-to-point; "broadcast" address is actually the address of the other end.
IFF_DRV_RUNNING
	<D*> The interface has been configured and dynamic resources were successfully allocated. Probably only useful internal to the interface.
IFF_NOARP	<D> Disable network address resolution on this interface.
IFF_PROMISC	<D*> This interface is in promiscuous mode.
IFF_PPROMISC	<D> This interface is in the permanently promiscuous mode (implies IFF_PROMISC).
IFF_ALLMULTI	<D*> This interface is in all-multicasts mode (used by multicast routers).
IFF_DRV_OACTIVE
	<D*> The interface's hardware output queue (if any) is full; output packets are to be queued.
IFF_SIMPLEX	<S*> The interface cannot hear its own transmissions.
IFF_LINK0 IFF_LINK1 IFF_LINK2
	<D> Control flags for the link layer. (Currently abused to select among multiple physical layers on some devices.)
IFF_MULTICAST	<S*> This interface supports multicast.
IFF_CANTCONFIG	<S*> The interface is not configurable in a meaningful way. Primarily useful for IFT_USB interfaces registered at the interface list.
IFF_MONITOR	<D> This interface blocks transmission of packets and discards incoming packets after BPF processing. Used to monitor network traffic but not interact with the network in question.
IFF_STATICARP	<D> Used to enable/disable ARP requests on this interface.
IFF_DYING	<D*> Set when the ifnet structure of this interface is being released and still has if_refcount references.
IFF_RENAMING	<D> Set when this interface is being renamed.

It should be stressed that a capability can be completely uncontrolled (i.e., stay always enabled with no way to disable it) or allow limited control over itself (e.g., depend on another capability's state.) Such peculiarities are determined solely by the hardware and driver of a particular interface. Only the driver possesses the knowledge on whether and how the interface capabilities can be controlled. Consequently, capabilities flags in if_capenable should never be modified directly by kernel code other than the interface driver. The command SIOCSIFCAP to ifioctl() is the dedicated means to attempt altering if_capenable on an interface. Userland code shall use ioctl(2).

The following capabilities are currently supported by the system:

IFCAP_RXCSUM	This interface can do checksum validation on receiving data. Some interfaces do not have sufficient buffer storage to store frames above a certain MTU-size completely. The driver for the interface might disable hardware checksum validation if the MTU is set above the hardcoded limit.
IFCAP_TXCSUM	This interface can do checksum calculation on transmitting data.
IFCAP_HWCSUM	A shorthand for ( IFCAP_RXCSUM | IFCAP_TXCSUM).
IFCAP_NETCONS	This interface can be a network console.
IFCAP_VLAN_MTU	The vlan(4) driver can operate over this interface in software tagging mode without having to decrease MTU on vlan(4) interfaces below 1500 bytes. This implies the ability of this interface to cope with frames somewhat longer than permitted by the Ethernet specification.
IFCAP_VLAN_HWTAGGING
	This interface can do VLAN tagging on output and demultiplex frames by their VLAN tag on input.
IFCAP_JUMBO_MTU	This Ethernet interface can transmit and receive frames up to 9000 bytes long.
IFCAP_POLLING	This interface supports polling(4). See below for details.
IFCAP_VLAN_HWCSUM	This interface can do checksum calculation on both transmitting and receiving data on vlan(4) interfaces (implies IFCAP_HWCSUM).
IFCAP_TSO4	This Ethernet interface supports TCP4 Segmentation offloading.
IFCAP_TSO6	This Ethernet interface supports TCP6 Segmentation offloading.
IFCAP_TSO	A shorthand for ( IFCAP_TSO4 | IFCAP_TSO6).
IFCAP_TOE4	This Ethernet interface supports TCP offloading.
IFCAP_TOE6	This Ethernet interface supports TCP6 offloading.
IFCAP_TOE	A shorthand for ( IFCAP_TOE4 | IFCAP_TOE6).
IFCAP_WOL_UCAST	This Ethernet interface supports waking up on any Unicast packet.
IFCAP_WOL_MCAST	This Ethernet interface supports waking up on any Multicast packet.
IFCAP_WOL_MAGIC	This Ethernet interface supports waking up on any Magic packet such as those sent by wake(8).
IFCAP_WOL	A shorthand for ( IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC).
IFCAP_TOE4	This Ethernet interface supports TCP4 Offload Engine.
IFCAP_TOE6	This Ethernet interface supports TCP6 Offload Engine.
IFCAP_TOE	A shorthand for ( IFCAP_TOE4 | IFCAP_TOE6).
IFCAP_VLAN_HWFILTER	This interface supports frame filtering in hardware on vlan(4) interfaces.
IFCAP_VLAN_HWTSO	This interface supports TCP Segmentation offloading on vlan(4) interfaces (implies IFCAP_TSO).
IFCAP_LINKSTATE	This Ethernet interface supports dynamic link state changes.
IFCAP_NETMAP	This Ethernet interface supports netmap(4).

The ability of advanced network interfaces to offload certain computational tasks from the host CPU to the board is limited mostly to TCP/IP. Therefore a separate field associated with an interface (see ifnet.if_data.ifi_hwassist below) keeps a detailed description of its enabled capabilities specific to TCP/IP processing. The TCP/IP module consults the field to see which tasks can be done on an outgoing packet by the interface. The flags defined for that field are a superset of those for mbuf.m_pkthdr.csum_flags, namely:

CSUM_IP	The interface will compute IP checksums.
CSUM_TCP	The interface will compute TCP checksums.
CSUM_UDP	The interface will compute UDP checksums.

An interface notifies the TCP/IP module about the tasks the former has performed on an incoming packet by setting the corresponding flags in the field mbuf.m_pkthdr.csum_flags of the mbuf chain containing the packet. See mbuf(9) for details.

The capability of a network interface to operate in polling(4) mode involves several flags in different global variables and per-interface fields. The capability flag IFCAP_POLLING set in interface's if_capabilities indicates support for polling(4) on the particular interface. If set in if_capabilities, the same flag can be marked or cleared in the interface's if_capenable within ifioctl(), thus initiating switch of the interface to polling(4) mode or interrupt mode, respectively. The actual mode change is managed by the driver-specific if_ioctl() routine. The polling(4) handler returns the number of packets processed.

The structure additionally contains generic statistics applicable to a variety of different interface types (except as noted, all members are of type u_long):

ifi_link_state
	(u_char) The current link state of Ethernet interfaces. See the Interface Link States section for possible values.
ifi_ipackets
	Number of packets received.
ifi_ierrors
	Number of receive errors detected (e.g., FCS errors, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB.
ifi_opackets
	Number of packets transmitted.
ifi_oerrors
	Number of output errors detected (e.g., late collisions, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB.
ifi_collisions
	Total number of collisions detected on output for CSMA interfaces. (This member is sometimes [ab]used by other types of interfaces for other output error counts.)
ifi_ibytes
	Total traffic received, in bytes.
ifi_obytes
	Total traffic transmitted, in bytes.
ifi_imcasts
	Number of packets received which were sent by link-layer multicast.
ifi_omcasts
	Number of packets sent by link-layer multicast.
ifi_iqdrops
	Number of packets dropped on input. Rarely implemented.
ifi_oqdrops
	Number of packets dropped on output.
ifi_noproto
	Number of packets received for unknown network-layer protocol.
ifi_lastchange
	(struct timeval) The time of the last administrative change to the interface (as required for SNMP).

The members of struct ifaddr are as follows:

ifa_addr
	(struct sockaddr *) The local address of the interface.
ifa_dstaddr
	(struct sockaddr *) The remote address of point-to-point interfaces, and the broadcast address of broadcast interfaces. ( ifa_broadaddr is a macro for ifa_dstaddr.)
ifa_netmask
	(struct sockaddr *) The network mask for multi-access interfaces, and the confusion generator for point-to-point interfaces.
ifa_ifp
	(struct ifnet *) A link back to the interface structure.
ifa_link
	(TAILQ_ENTRY(ifaddr)) queue(3) glue for list of addresses on each interface.
ifa_rtrequest
	See below.
ifa_flags
	(u_short) Some of the flags which would be used for a route representing this address in the route table.
ifa_refcnt
	(short) The reference count.

References to ifaddr structures are gained by calling the ifa_ref() function and released by calling the ifa_free() function.

ifa_rtrequest() is a pointer to a function which receives callouts from the routing code (rtrequest()) to perform link-layer-specific actions upon requests to add, or delete routes. The cmd argument indicates the request in question: RTM_ADD, or RTM_DELETE. The rt argument is the route in question; the info argument contains the specific destination being manipulated.

Gary R. Wright, W. Richard Stevens, TCP/IP Illustrated, Addison-Wesley, ISBN 0-201-63354-X, Vol. 2,