IONetworkInterface

Inherits from
IOService
Availability
Available in OS X v10.6 and later.
Declared in
IONetworkInterface.h

Overview

Abstract class that manages the connection between an IONetworkController and the data link interface layer.

An IONetworkInterface object manages the connection between an IONetworkController and the data link interface layer (DLIL). All interactions between the controller and DLIL must go through an interface object. Any data structures that are required by DLIL for a particular interface type shall be allocated and mantained by the interface object. IONetworkInterface is an abstract class that must be extended by a concrete subclass to specialize for a particular network type.

Although most drivers will allocate a single interface object, it is possible for multiple interfaces to be attached to a single controller. This controller driver will be responsible for arbitrating access among its multiple interface clients.

IONetworkInterface also maintains a dictionary of IONetworkData objects containing statistics structures. Controller drivers can ask for a particular data object by name and update the statistics counters within directly. This dictionary is added to the interface's property table and is visible outside of the kernel.

Tasks

Miscellaneous

Instance Methods

addNetworkData

Adds an IONetworkData object to the interface.

virtual bool addNetworkData( IONetworkData *aData );
Parameters
aData

The IONetworkData object.

Return Value

Returns true if the object was added, false otherwise.

Discussion

The IONetworkData object is added to a collection using the key from IONetworkData::getKey(). The object provided is retained.

attachToDataLinkLayer

Attach the network interface to the BSD data link layer.

virtual IOReturn attachToDataLinkLayer( IOOptionBits options, void *parameter );
Parameters
options

Options for the attach call. None are currently defined.

parameter

Parameter for the attach call. Not currently used.

Return Value

Returns kIOReturnSuccess on success.

Discussion

This method is called internally to attach the network interface to the BSD data link layer, after an unit number has been assigned. The calling context is not synchronized against the driver's work loop. Subclasses may override this method to perform additional setup before the network stack attach. The getIfnet() method will return the BSD interface being attached.

clearInputQueue

Discards all packets in the input queue.

virtual UInt32 clearInputQueue( void );
Return Value

Returns the number of packets freed.

Discussion

This method removes all packets from the input queue and releases them back to the free mbuf pool. It is unusual for a driver to call this method.

controllerDidChangePowerState

Handles a notification that the network controller servicing this interface object has transitioned to a new power state.

virtual IOReturn controllerDidChangePowerState( IONetworkController *controller, IOPMPowerFlags flags, UInt32 stateNumber, IOService *policyMaker );
Parameters
controller

The network controller object.

flags

Flags that describe the capability of the controller in the new power state.

stateNumber

An index to a state in the network controller's power state array that the controller has switched to.

policyMaker

A reference to the network controller's policy-maker, and is also the originator of this notification.

Return Value

The return value is always kIOReturnSuccess.

controllerDidOpen

Sends a notification that the interface has opened the network controller.

virtual bool controllerDidOpen( IONetworkController *controller );
Parameters
controller

The controller that was opened.

Return Value

Must return true in order for handleOpen() to accept the client open. If the return is false, then the controller will be closed and the client open will fail.

Discussion

This method is called by handleOpen() to notify subclasses that the controller was opened. The open on the controller occurs when the interface receives the initial open request from a client. Subclasses can override this method and inspect the controller before allowing the client open. This method is called with the arbitration lock held, hence issuing I/O to the controller must be avoided to eliminate the possibility of a deadlock.

controllerWillChangePowerState

Handles a notification that the network controller servicing this interface object will transition to a new power state.

virtual IOReturn controllerWillChangePowerState( IONetworkController *controller, IOPMPowerFlags flags, UInt32 stateNumber, IOService *policyMaker );
Parameters
controller

The network controller object.

flags

Flags that describe the capability of the controller in the new power state.

stateNumber

An index to a state in the network controller's power state array that the controller is switching to.

policyMaker

A reference to the network controller's policy-maker, and is also the originator of this notification.

Return Value

The return value is always kIOReturnSuccess.

controllerWillClose

Sends a notification that the interface will close the network controller.

virtual void controllerWillClose( IONetworkController *controller );
Parameters
controller

The controller that is about to be closed.

Discussion

This method is called by handleClose() after receiving a close from the last interface client, and just before the controller is closed. Subclasses can override this method to perform any cleanup action before the controller is closed. This method is called with the arbitration lock held, hence issuing I/O to the controller should be avoided to eliminate the possibility of a deadlock.

debuggerRegistered

Tells the IONetworkData that this interface will be used by the debugger.

void debuggerRegistered( void );

detachFromDataLinkLayer

Detach the network interface from the BSD data link layer.

virtual void detachFromDataLinkLayer( IOOptionBits options, void *parameter );
Parameters
options

Options for the detach call. None are currently defined.

parameter

Parameter for the detach call. Not currently used.

Discussion

This method is called internally to detach the network interface from the BSD data link layer, after the interface has been terminated and before the last client close. This method will block until the detach operation is complete. The calling context is not synchronized against the driver's work loop. Subclasses may override this method to perform additional cleanup before or after detaching from the network stack. The getIfnet() method will return NULL after detach.

feedPacketInputTap

Feed received packets to the BPF

virtual void feedPacketInputTap( mbuf_t );
Parameters
mbuf_t

Pointer to the input packet.

Discussion

This function is called internally to send input packets to the BPF input tap when it is enabled. Subclasses are not expected to override this method.

feedPacketOutputTap

Feed output packets to the BPF

virtual void feedPacketOutputTap( mbuf_t );
Parameters
mbuf_t

Pointer to the output packet.

Discussion

This function is called internally to send output packets to the BPF output tap when it is enabled. Subclasses are not expected to override this method.

flushInputQueue

Submit all packets held in the input queue to the network stack.

virtual UInt32 flushInputQueue( void );
Return Value

Returns the number of packets that were submitted to the network stack. Returns zero if the queue was empty.

Discussion

Allow drivers to remove all packets from the input queue and submit them to the network stack. This method should be used in concert with the inputPacket() method, to flush the input queue after queueing a number of received packets.

free

Frees the IONetworkInterface object.

virtual void free( void );
Discussion

Resource allocated by init() are released, and clearInputQueue() is called to ensure that the input queue is empty. The interface should have already detached from the network stack.

getController

Gets the IONetworkController object that created this interface.

virtual IONetworkController * getController( void ) const;
Return Value

Returns the parent IONetworkController object.

Discussion

The controller object passed to init() will be retained until the interface closes the controller. Subclasses can safely call this method before the controller is closed.

getExtraFlags

Gets the current interface eflags.

virtual UInt32 getExtraFlags( void ) const;
Return Value

Returns the value of the interface eflags.

Discussion

This method calls ifnet_eflags and returns the current interface eflags.

getFlags

Gets the current interface flags.

virtual UInt16 getFlags( void ) const;
Return Value

Returns the interface flags.

Discussion

This method calls ifnet_flags and returns the current interface flags.

getIfnet

Returns the ifnet_t allocated by the interface object.

virtual ifnet_t getIfnet( void ) const;
Return Value

Returns the ifnet_t after the interface has attached to the network stack and before the interface is detached, otherwise returns NULL.

Discussion

Gets the interface's ifnet_t, which is managed primarily by IONetworkInterface, however subclasses or drivers can use this method to obtain a reference to the ifnet_t for interface KPI calls.

getInterfaceState

Reports the current state of the interface object.

virtual UInt32 getInterfaceState( void ) const;
Return Value

Returns the current interface state flags.

getInterfaceType

Gets the interface type.

virtual UInt8 getInterfaceType( void ) const;
Return Value

Returns a constant defined in bsd/net/if_types.h that describes the interface type.

Discussion

This method returns the interface type previously set by setInterfaceType.

getMaxTransferUnit

Gets the maximum transfer unit for this interface.

virtual UInt32 getMaxTransferUnit( void ) const;
Return Value

Returns the interface MTU size in bytes.

Discussion

This method calls ifnet_mtu and returns the maximum transfer unit.

getMediaAddressLength

Gets the size of the media (MAC-layer) address.

virtual UInt8 getMediaAddressLength( void ) const;
Return Value

Returns the size of the media address in bytes.

Discussion

This method calls ifnet_addrlen and returns the media address length.

getMediaHeaderLength

Gets the size of the media header.

virtual UInt8 getMediaHeaderLength( void ) const;
Return Value

Returns the size of the media header in bytes.

Discussion

This method calls ifnet_hdrlen and returns the media header length.

getNamePrefix

Returns the BSD name prefix as a C-string.

virtual const char * getNamePrefix() const = 0;
Return Value

Returns a pointer to a constant C-string.

Discussion

The BSD name for each interface object is generated by concatenating the string returned by this method, along with an unit number assigned by IONetworkStack. A concrete interface subclass must implement this method and return a distinct name prefix for its instances.

getNetworkData(const char *)

Gets an IONetworkData object from the interface.

virtual IONetworkData * getNetworkData( const char *aKey ) const;
Parameters
aKey

A C-string identifying the object.

Return Value

Returns a reference to the matching IONetworkData object, or NULL if no match was found.

Discussion

Returns a reference to an IONetworkData object that was previously added to the interface, and is associated with the provided key.

getNetworkData(const OSSymbol *)

Gets an IONetworkData object from the interface.

virtual IONetworkData * getNetworkData( const OSSymbol *aKey) const;
Parameters
aKey

An OSSymbol identifying the object.

Return Value

Returns a reference to the matching IONetworkData object, or NULL if no match was found.

Discussion

Returns a reference to an IONetworkData object that was previously added to the interface, and is associated with the provided key.

getUnitNumber

Gets the unit number assigned to this interface object.

virtual UInt16 getUnitNumber( void ) const;
Return Value

Returns the assigned interface unit number.

Discussion

This method calls ifnet_unit and returns the unit number assigned by IONetworkStack.

handleClientClose

Handles a client close on the interface.

virtual void handleClientClose( IOService *client, IOOptionBits options );
Parameters
client

The client object requesting the close.

options

Options same options passed to handleClose().

Discussion

This method is called by handleClose() to allow a subclass to handle a client close. The arbitration lock is held.

handleClientOpen

Handles a client open on the interface.

virtual bool handleClientOpen( IOService *client, IOOptionBits options, void *argument );
Parameters
client

The client object requesting the open.

options

Options passed to handleOpen().

argument

Argument passed to handleOpen().

Return Value

Returns true to accept the client open, false to reject the open.

Discussion

This method is called by handleOpen() to allow a subclass to handle a client close. The arbitration lock is held.

init

Initializes the IONetworkInterface object.

virtual bool init( IONetworkController *controller );
Parameters
controller

A network controller object that will service the the interface.

Return Value

Returns true on success, false otherwise.

Discussion

Resources are allocated, but an ifnet_t will not be allocated until the interface is assigned a BSD name and attached to the network stack.

initIfnetParams

Allows a subclass to provide ifnet initialization parameters specific to an interface type.

virtual bool initIfnetParams( struct ifnet_init_params *params );
Parameters
params

Pointer to an ifnet_init_params allocated by the caller.

Return Value

Returns true on success, false otherwise.

Discussion

This method initializes the parameters that are common to all network interfaces. An interface subclass is expected to override this method, call the superclass implementation first, then initialize the parameters specific to that interface type. This method is called after an unit number has been assigned to the interface, and just before the interface is attached to BSD.

inputEvent

Sends an event to the network stack.

virtual bool inputEvent( UInt32 type, void *data );
Parameters
type

A constant describing the event type.

data

An optional data associated with the event.

Return Value

Returns true if the event was delivered, false if the event type specified is invalid, or if the event delivery failed.

Discussion

This method can be used by the driver to send an event to the network stack.

inputPacket

For drivers to submit a received packet to the network stack.

virtual UInt32 inputPacket( mbuf_t packet, UInt32 length = 0, IOOptionBits options = 0, void *param = 0 );
Parameters
mbuf_t

The mbuf containing the received packet.

length

Specify the size of the received packet in the mbuf. The mbuf length fields are updated with this value. If zero, then the mbuf length fields are not updated.

options

Pass kInputOptionQueuePacket to enqueue the input packet. Pass zero to bypass the input queue, and immediately submit the packet to the network stack.

param

A parameter provided by the driver. Not used.

Return Value

Returns the number of packets that were submitted to the network stack, or zero if the packet was enqueued.

Discussion

The packet provided to this method may be added to an input queue managed by the interface object, which the driver can use to postpone the packet handoff to the network stack, until all received packets have been added to the input queue. A subsequent call to flushInputQueue(), will transfer the entire contents of the input queue to the network stack. This input queue is not protected by a lock. Drivers that leverage this input queue must either access the queue from a single thread, or enforce serialized access.

isPrimaryInterface

Queries whether the interface is the primary network interface on the system.

virtual bool isPrimaryInterface( void ) const;
Return Value

Returns true if the interface is the primary interface, false otherwise.

Discussion

The definition of a primary interface and its discovery is platform specific.

isRegistered

Queries if the interface has attached to the BSD network stack.

virtual bool isRegistered( void ) const;
Return Value

Returns true if interface is registered and attached to the network stack, false otherwise.

Discussion

Once attached a kIOBSDNameKey property is added to the interface object with the assigned BSD name.

lock

Acquires a recursive lock owned by the interface.

virtual void lock( void );
Discussion

A recursive lock is allocated and initialized in init(). This lock is otherwise not used by the IONetworkInterface class. This method call acquires the lock and must be balanced with an unlock().

performCommand

Handles an ioctl command sent to the network interface.

virtual SInt32 performCommand( IONetworkController *controller, unsigned long cmd, void *arg0, void *arg1 );
Parameters
controller

The controller object.

cmd

The ioctl command code.

arg0

Command argument 0. Generally a pointer to an ifnet structure associated with the interface.

arg1

Command argument 1.

Return Value

Returns a BSD return value defined in bsd/sys/errno.h.

Discussion

This method handles socket ioctl commands sent to the network interface from DLIL. IONetworkInterface handles commands that are common for all network interface types. A subclass of IONetworkInterface may override this method to override the command handling in IONetworkInterface, or to extend the command processing to handle additional commands. The ioctl commands handled by IONetworkInterface are SIOCGIFMTU (Get interface MTU size), SIOCSIFMTU (Set interface MTU size), SIOCSIFMEDIA (Set media), and SIOCGIFMEDIA (Get media and link status).

powerStateDidChangeTo

Handles a post-change power interest notification from the network controller.

virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags flags, unsigned long stateNumber, IOService *policyMaker );
Parameters
flags

Flags that describe the capability of the controller in the new power state.

stateNumber

An index to a state in the network controller's power state array that the controller has switched to.

policyMaker

A reference to the network controller's policy-maker, and is also the originator of this notification.

Return Value

Returns IOPMAckImplied to indicate synchronous completion.

Discussion

The controllerDidChangePowerState() method is called by this handler. Subclasses are not expected to override this method.

powerStateWillChangeTo

Handles a pre-change power interest notification from the network controller.

virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags flags, unsigned long stateNumber, IOService *policyMaker );
Parameters
flags

Flags that describe the capability of the controller in the new power state.

stateNumber

An index to a state in the network controller's power state array that the controller is switching to.

policyMaker

A reference to the network controller's policy-maker, and is also the originator of this notification.

Return Value

Returns IOPMAckImplied to indicate synchronous completion.

Discussion

The controllerWillChangePowerState() method is called by this handler. Subclasses are not expected to override this method.

registerOutputHandler

Registers a target/action to handle outbound packets.

virtual bool registerOutputHandler( OSObject *target, IOOutputAction action );
Parameters
target

Object that implements the output handler.

action

The function that will handle output packets.

Return Value

Returns true if the target/action provided was accepted, false otherwise.

Discussion

The interface object will forward all output packets sent from the network stack to the target and action registered using this method. The registration must occur before the interface is registered and opened by IONetworkStack, otherwise the default handler will be used. The default target and action is set by init() as the controller, and the handler returned by the controller's getOutputHandler() method.

removeNetworkData(const char *)

Removes an IONetworkData object from the interface.

virtual bool removeNetworkData( const char *aKey );
Parameters
aKey

A C-string identifying the object to be removed.

Return Value

Returns true if the object was found and removed, false otherwise.

Discussion

This method removes an IONetworkData object from the collection managed by the interface. The object removed is released.

removeNetworkData(const OSSymbol *)

Removes an IONetworkData object from the interface.

virtual bool removeNetworkData( const OSSymbol *aKey );
Parameters
aKey

An OSSymbol identifying the object to be removed.

Return Value

Returns true if the object was found and removed, false otherwise.

Discussion

This method removes an IONetworkData object from the collection managed by the interface. The object removed is released.

setFlags

Performs a read-modify-write operation on the current interface flags value.

virtual bool setFlags( UInt16 flags, UInt16 clear = 0 );
Parameters
flags

The bits that should be set.

clear

The bits that should be cleared. If zero, then non of the flags are cleared and the result is formed by OR'ing the original flags value with the new flags.

Return Value

Always returns true.

Discussion

Calls ifnet_set_flags if the interface is attached to the network stack, and updates the kIOInterfaceFlags property using the provided value. See bsd/net/if.h header file for the flag constants.

setInterfaceState

Updates the interface object state flags.

virtual UInt32 setInterfaceState( UInt32 set, UInt32 clear = 0 );
Parameters
set

The flags that should be set.

clear

The flags that should be cleared.

Return Value

Returns the new interface state flags.

Discussion

The flags reflect the current state of the interface, and is also published through the kIOInterfaceState property.

setInterfaceType

Sets the interface type.

virtual bool setInterfaceType( UInt8 type );
Parameters
type

A constant defined in bsd/net/if_types.h that describes the interface type.

Return Value

Returns true to indicate success if the interface has not yet attached to the network stack, otherwise returns false.

Discussion

Sets the interface type before the interface is attached to the network stack. See bsd/net/if_types.h for defined types. The kIOInterfaceType is also updated using the provided type.

setMaxTransferUnit

Sets the maximum transfer unit for this interface.

virtual bool setMaxTransferUnit( UInt32 mtu );
Parameters
mtu

The interface MTU size in bytes.

Return Value

Always returns true.

Discussion

Calls ifnet_set_mtu if the interface is attached to the network stack, and updates the kIOMaxTransferUnit property using the provided value.

setMediaAddressLength

Sets the size of the media (MAC-layer) address.

virtual bool setMediaAddressLength( UInt8 length );
Parameters
length

The size of the media address in bytes.

Return Value

Always returns true.

Discussion

Calls ifnet_set_addrlen if interface is attached to the network stack, and updates the kIOMediaAddressLength property using the provided value.

setMediaHeaderLength

Sets the size of the media header.

virtual bool setMediaHeaderLength( UInt8 length );
Parameters
length

The size of the media header in bytes.

Return Value

Always returns true.

Discussion

Calls ifnet_set_hdrlen if interface is attached to the network stack, and updates the kIOMediaHeaderLength property using the provided value.

setUnitNumber

Assigns an unique unit number to this interface.

virtual bool setUnitNumber( UInt16 unit );
Parameters
unit

The unit number assigned to this interface object.

Return Value

Returns true to indicate success if the interface has not yet attached to the network stack, otherwise returns false.

Discussion

This method is called internally before the interface is attached to the network stack, to assign an unique unit number to the interface object. The kIOInterfaceUnit property is also updated using the provided value.

unlock

Releases the recursive lock owned by the interface.

virtual void unlock( void );
Discussion

A recursive lock is allocated and initialized in init(). This lock is otherwise not used by the IONetworkInterface class. This method call releases the lock to balance a prior lock().

Constants

InputOptionQueuePacket

enum {
   kInputOptionQueuePacket = 0x1
};
Constants
kInputOptionQueuePacket

Enqueue the input packet provided to the input packet queue. Calls to inputPacket() must be serialized.

Discussion

Options for inputPacket().