I/O Kit Fundamentals: Network

Contact ADC

< Previous PageNext Page >

Hide TOC

Network

The Network family provides support for network controllers. The Network family consists of two logical layers:

Controller layer—this layer represents the network controller.
Interface layer—this layer represents the network interface published by the network controller.

Bundle identifier:

com.apple.iokit.IONetworkingFamily

Headers in:

Kernel resident: Kernel.framework/Headers/IOKit/network/
Device interface: IOKit.framework/Headers/network/

Class hierarchy:

Device interface:

The device interface for this family is usually the BSD network stack. Applications use the socket interface provided by the network stack to access indirectly the services provided by the Network family.

Power management:

The Network family performs most of the power-management set-up and tear-down tasks for subclassed device drivers. If you’re developing a driver for a network device that can be passively power managed (which describes most network devices), you can meet most of your basic power-management needs by overriding the IONetworkController method registerWithPolicyMaker and calling the IOService method registerPowerDriver.

In your implementation of registerWithPolicyMaker, create an array of IOPMPowerState structures to define your device’s power states and pass them in to registerPowerDriver. Then, return kIOReturnSuccess from registerWithPolicyMaker to tell the Network family that your driver can respond to power-management calls. (The default implementation of registerPowerDriver returns kIOReturnUnsupported.) The following code snippet shows one way to do this:

IOReturn MyEthernetDriver::registerWithPolicyMaker( IOService * policyMaker )

IOReturn ioreturn;

static IOPMPowerState powerStateArray[ kPowerStateCount ] = {

   { 1,0,0,0,0,0,0,0,0,0,0,0 },

   { 1,kIOPMDeviceUsable,kIOPMPowerOn,kIOPMPowerOn,0,0,0,0,0,0,0,0 }

};

fCurrentPowerState = kPowerStateOn;

ioreturn = policyMaker->registerPowerDriver( this, powerStateArray, kPowerStateCount );

return ioreturn;

Most network device drivers handle power changes related to sleep and wake in their implementations of the IONetworkController methods enable and disable. Note that the Network family enables a device when it transitions to a power state for which the kIOPMDeviceUsable flag is set. When a currently enabled device moves to a power state for which the kIOPMDeviceUsable flag is not set, the Network family disables it.

If you need to perform additional tasks to handle sleep and wake, you can override the IOService method setPowerState. Be aware, however, that the Network family will call disable before you receive a call to your setPowerState implementation if the new power state puts the device into an unusable state. Conversely, the Network family calls enable after you receive a setPowerState call to move the device to a usable state.

If your network device driver performs DMA, you should override the IOService method systemWillShutdown, which was introduced in Mac OS X v10.5. This is especially important for drivers that run in Intel-based Macintosh computers. In your implementation of systemWillShutdown, you should make sure that the DMA engine is shut off, which results in the necessary disabling of the port.

Important: As described in “Receiving Shutdown and Restart Notifications” the systemWillShutdown call is made to drivers in the power plane, in leaf-to-root order. If your driver returns kIOReturnUnsupported from registerWithPolicyMaker, it will not be attached to the power plane and will not receive a systemWillShutdown call.

**Table A-7** Clients and providers of the Network family
	Client of the nub	Provider for the nub
Action		Drives a network controller.
Example		Controllers on Ethernet, Token Ring, and FDDI adapters.
Classes		Driver must be an instance of a subclass of a controller class that implements generic network controller functionality, such as IONetworkController or of a controller class that builds upon IONetworkController to specialize for Ethernet controller support (IOEthernetController). See discussion on Network family classes below for more information.
Notes	Drivers are typically not clients of the Network family. The primary system client of this family is the DLIL (Data Link Interface Layer) module in the BSD network stack.

Member drivers must also create IONetworkInterface objects that are registered with the DLIL; such registration associates the driver with a network interface (for example, en0) in the system. You can create a Network Kernel Extension (NKE) and insert it at various locations above the IOKit/DLIL boundary to intercept the packets, commands, or other event traffic between an IONetworkInterface object and the upper layers.

Another client of this family is the KDP (Kernel Debugger Protocol) module in the kernel. A driver can create an IOKernelDebugger object that vends debugging services and allows kernel debugging through the network hardware managed by the driver. Only drivers that drive a built-in network controller are required to provide this support.

Other classes of the Network family include:

IOOutputQueue—assists in queuing outbound packets.
IOPacketQueue—represents a generic mbuf packet FIFO queue.
IOMbufMemoryCursor—translates mbuf packets into a scatter-gather list of physical addresses and length pairs.
IONetworkData—represents a container for a single group of statistics counters.
IONetworkMedium—represents a single network medium supported by the network device.

< Previous PageNext Page >

Hide TOC

Last updated: 2007-05-17

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice