ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

 


IONetworkController

Inherits from:
Declared In:

Overview

Implements the framework for a generic network controller.

Discussion

A subclass of IONetworkController must provide additional functionality specific for a particular networking type. In addition, the driver must implement (override) a basic set of hardware dependent methods to create a working driver.

IONetworkController attaches itself to the data link layer (DLIL) via an IONetworkInterface object. A controller object without a companion interface is not accessible to the networking system. The controller interacts with DLIL by calling methods defined by the interface object. And conversely, DLIL will issue commands and packets to the controller through the interface object.

IONetworkController will create an IOCommandGate and attach this event source to an IOWorkLoop object. All commands sent from the interface object are handled through the IOCommandGate object, which will serialize access to the controller. Outbound packets sent from the interface to the controller have no implicit serialization. Drivers must implement an output function that is thread safe, or use an IOOutputQueue object which will provide a serialization model.

Note: IONetworkController internally uses some private messaging constants in the sys_iokit | sub_iokit_networking range defined in "IONetworkControllerPrivate.h". If you create a client for your controller (for example an IOUserClient), and it overrides the IOService::message method, your client may receive these messages. It should ignore these messages and pass them to super::message()



Functions

allocatePacket

Allocates a packet with a data buffer that is larger than or equal to the size specified.

attachDebuggerClient

Attaches a new IOKernelDebugger client object.

attachInterface

Attaches a new interface client object.

configureInterface

Configures a newly created network interface object.

copyMediumDictionary

Returns a copy of the medium dictionary published by the driver.

copyPacket

Allocates a new packet, containing data copied from an existing source packet.

createInterface

Creates a new network interface object.

createOutputQueue

Creates an IOOutputQueue to handle output packet queueing, and also to resolve contention for the controller's transmitter from multiple client threads.

createWorkLoop

Method called by IONetworkController prior to the initial getWorkLoop() call.

detachDebuggerClient

Detaches an IOKernelDebugger client object.

detachInterface

Detaches an interface client object.

disable

A disable request from an IOKernelDebugger client.

disable(IONetworkInterface *)

A request from an interface client to disable the controller.

disable(IOService *)

Handles a disable request from a client.

disablePacketFilter

Disables a packet filter that is currently enabled from the given filter group.

doDisable

Makes a synchronized call to disable() through executeCommand().

doEnable

Makes a synchronized call to enable() through executeCommand().

enable

An enable request from an IOKernelDebugger client.

enable(IONetworkInterface *)

A request from an interface client to enable the controller.

enable(IOService *)

Handles an enable request from a client.

enablePacketFilter

Enables one of the supported packet filters from the given filter group.

executeCommand

Makes a C function call through the command gate.

free

Frees the IONetworkController object.

freePacket

Releases the packet given back to the free pool.

getChecksumDemand

Fetches the demand for hardware checksum computation and insertion for the given packet before it is transmitted on the network.

getChecksumSupport

Gets checksums that are supported by the network controller for the given checksum family.

getCommandClient

Gets the command client object.

getCommandGate

Gets the IOCommandGate object created by IONetworkController.

getFeatures

Reports generic features supported by the controller and/or the driver.

getHardwareAddress

Gets the network controller's permanent hardware/station address.

getMaxPacketSize

Gets the maximum packet size supported by the controller.

getMediumDictionary

Returns the medium dictionary published by the driver.

getMinPacketSize

Gets the minimum packet size supported by the controller.

getOutputHandler

Gets the address of the method designated to handle output packets for the network controller.

getOutputQueue

Gets the IOOutputQueue object created by createOutputQueue().

getPacketBufferConstraints

Gets the controller's packet buffer constraints.

getPacketFilters

Gets the set of packet filters supported by the network controller for the given filter group.

getSelectedMedium

Gets the current selected medium.

handleClose

Handles a client close.

handleIsOpen

Queries whether a client has an open on the controller.

handleOpen

Handles a client open.

init

Initializes the IONetworkController object.

newModelString
newRevisionString
newVendorString
outputPacket

Transmits an output packet.

prepare

Prepares the controller before an IOService is created and attached as a client.

publishMediumDictionary

Publishes a dictionary of IONetworkMedium objects to advertise the media selection supported by the network controller.

publishProperties

Publishes controller properties and capabilities.

receivePacket

Debugger polled-mode receive handler.

registerWithPolicyMaker

Implemented by controller drivers to register with the power management policy-maker.

releaseDebuggerLock

Releases the global debugger lock.

releaseFreePackets

Releases all packets held in the free packet queue.

replaceOrCopyPacket

A helper method that combines the functionality of copyPacket() and replacePacket() to process a packet containing a received frame.

replacePacket

Allocates a new packet to replace an existing packet, the existing packet is then returned.

reserveDebuggerLock

Takes the global debugger lock.

selectMedium

A client request to change the medium selection.

selectMediumWithName

A client request to change the medium selection.

sendPacket

Debugger polled-mode transmit handler.

setChecksumResult

Encodes a received packet with the checksum result reported by the hardware.

setHardwareAddress

Sets or changes the station address used by the network controller.

setLinkStatus

Reports the link status and the active medium.

setMaxPacketSize

A client request to change the maximum packet size.

setSelectedMedium

Designates an entry in the published medium dictionary as the current selected medium.

start

Starts the network controller.

stop

Stops the network controller.


allocatePacket


Allocates a packet with a data buffer that is larger than or equal to the size specified.

public

virtual mbuf_t allocatePacket( UInt32 size);
Parameters
size

The minimum size of the data buffer for the mbuf packet allocated.

Return Value

Returns an mbuf packet, or 0 if allocation failed.

Discussion

This method will always return a single mbuf unless the size requested (plus the alignment padding) is greater than MCLBYTES. The data buffer for the mbuf (or an mbuf chain) returned is aligned according to the constraints reported by getPacketBufferConstraints(). The length fields in each mbuf returned are set by this method, thus allowing the mbuf to be passed directly to an IOMbufMemoryCursor object in order to convert the mbuf to a physical address scatter-gather list.


attachDebuggerClient


Attaches a new IOKernelDebugger client object.

protected

virtual bool attachDebuggerClient( IOKernelDebugger **debuggerP);
Parameters
debuggerP

A handle that will return the new IOKernelDebugger object created.

Return Value

Returns true on success, false otherwise.

Discussion

This method allocates an IOKernelDebugger object and attaches it as a client. Having a debugger client implies that the controller supports kernel debugging, and therefore must implement the two polled-mode methods that are called by the debugger client. See sendPacket() and receivePacket(). Only a single debugger client should be attached to each controller.


attachInterface


Attaches a new interface client object.

protected

virtual bool attachInterface( IONetworkInterface **interface, bool doRegister = true);
Parameters
interface

Upon success (return value is true), the interface object will be written to the handle provided.

doRegister

If true, then registerService() is called to register the interface, which will trigger the matching process, and will ultimately cause the interface to become registered with the data link layer. Drivers that wish to delay the registration can set doRegister to false, and call registerService() on the interface object when the controller becomes ready. This allows the driver to attach an interface without making its services available to the rest of the system.

Return Value

Returns true on success, false otherwise.

Discussion

This method creates a new interface object and attaches it to the controller. The createInterface() method is called to perform the interface allocation and initialization, followed by a call to configureInterface() to configure it. Subclasses can override those two methods to customize the interface client attached. Drivers will usually call this method from start(), after they are ready to process client requests. Since most drivers will have a single interface client, this method will likely be called only once.


configureInterface


Configures a newly created network interface object.

protected

virtual bool configureInterface( IONetworkInterface *interface);
Parameters
interface

The interface object to be configured.

Return Value

Returns true if the operation was successful, false otherwise (this will cause attachInterface() to fail and return 0).

Discussion

This method configures an interface object that was created by createInterface(). Subclasses can override this method to customize and examine the interface object that will be attached to the controller as a client.


copyMediumDictionary


Returns a copy of the medium dictionary published by the driver.

public

virtual OSDictionary * copyMediumDictionary() const;
Return Value

Returns a copy of the medium dictionary, or 0 if the driver has not published a medium dictionary through publishMediumDictionary().

Discussion

The caller is responsible for releasing the dictionary object returned. Use getMediumDictionary() to get a reference to the published medium dictionary instead of creating a copy.


copyPacket


Allocates a new packet, containing data copied from an existing source packet.

public

virtual mbuf_t copyPacket( const mbuf_t m, UInt32 size = 0);
Parameters
m

The source packet.

size

The number of bytes to copy. If set to 0, then the entire data buffer from the source packet is copied.

Return Value

Returns a new packet containing the same data as the source packet.

Discussion

The source packet is not modified by this method.


createInterface


Creates a new network interface object.

protected

virtual IONetworkInterface * createInterface() = 0;
Return Value

Returns a newly allocated and initialized interface object.

Discussion

This method is called by attachInterface() to perform allocation and initialization of a new interface object. A subclass of IONetworkController must implement this method and return a matching interface object. For example, IOEthernetController's implementation will return an IOEthernetInterface object when createInterface() is called.


createOutputQueue


Creates an IOOutputQueue to handle output packet queueing, and also to resolve contention for the controller's transmitter from multiple client threads.

protected

virtual IOOutputQueue * createOutputQueue();
Return Value

Returns a newly allocated and initialized IOOutputQueue object.

Discussion

This method is called by start() to create an IOOutputQueue object to handle output packet queueing. The default implementation will always return 0, hence no output queue will be created. A driver may override this method and return a subclass of IOOutputQueue. IONetworkController will keep a reference to the queue created, and will release this object when IONetworkController is freed. Also see getOutputQueue().


createWorkLoop


Method called by IONetworkController prior to the initial getWorkLoop() call.

protected

virtual bool createWorkLoop();
Return Value

Returns true to indicate success, false otherwise. Returning false will fail IONetworkController::start().

Discussion

Before IONetworkController calls getWorkLoop() in its start() method, it will call createWorkLoop() to make sure that a subclass that wants to create a workloop, will do so before its first use.


detachDebuggerClient


Detaches an IOKernelDebugger client object.

protected

virtual void detachDebuggerClient( IOKernelDebugger *debugger);
Parameters
debugger

The IOKernelDebugger object to be detached and terminated. If the argument provided is NULL or is not an IOKernelDebugger, this method will return immediately.

Discussion

This method detaches and terminates the IOKernelDebugger client object provided. A synchronous termination is issued, and this method will return after the debugger client has been terminated. The debugger client should be released following this call.


detachInterface


Detaches an interface client object.

protected

virtual void detachInterface( IONetworkInterface *interface, bool sync = false);
Parameters
interface

An interface object to be detached and terminated.

sync

If true, the interface is terminated synchronously. This may cause this method to block for an indeterminate amount of time.

Discussion

This method will verify that the object provided is indeed an IONetworkInterface instance, and then call its terminate() method. Note that an interface object will close and detach from its controller after the data link layer has removed all references to all data structures exposed by the interface. The interface object should be released following this call.


disable


A disable request from an IOKernelDebugger client.

protected

virtual IOReturn disable( IOKernelDebugger *debugger);
Parameters
debugger

The IOKernelDebugger client requesting the disable.

Return Value

Returns kIOReturnSuccess. Drivers must return kIOReturnSuccess on success, or an error otherwise.

Discussion

Drivers that provide debugging support may either override this method to disable support for the polled-mode send and receive methods, or override the base enable() and disable() methods that take an IOService argument.


disable(IONetworkInterface *)


A request from an interface client to disable the controller.

protected

virtual IOReturn disable( IONetworkInterface *interface);
Parameters
interface

The interface object that requested the disable.

Return Value

kIOReturnUnsupported. Drivers that override this method must return Returns kIOReturnSuccess on success, or an error code otherwise.

Discussion

This method is called by an interface client to disable the controller. This method should stop the hardware and disable hardware interrupt sources. Any resources allocated by enable() should also be deallocated. This method call is synchronized by the workloop's gate.


disable(IOService *)


Handles a disable request from a client.

public

virtual IOReturn disable( IOService *client);
Parameters
client

The client object requesting the disable.

Return Value

Returns the return from the overloaded disable() method, or kIOReturnBadArgument if the client type is unknown.

Discussion

This method handles a disable request from a client. A client will call disable if it has previously enabled the controller, and it no longer needs to transport packets or perform I/O using the controller. The client object is typecasted using OSDynamicCast, and depending on whether the client is an IOKernelDebugger or an IONetworkInterface, then an overloaded disable method that takes a more specific argument type is called. If the client matches neither type, then kIOReturnBadArgument is returned. A driver has the option of overriding this base disable method, or the overloaded form. This method call is synchronized by the workloop's gate.


disablePacketFilter


Disables a packet filter that is currently enabled from the given filter group.

public

virtual IOReturn disablePacketFilter( const OSSymbol * group, UInt32 aFilter, UInt32 enabledFilters, IOOptionBits options = 0) = 0;
Parameters
group

The name of the filter group containing the filter to be disabled.

aFilter

The filter to disable.

enabledFilters

All filters currently enabled by the client.

options

Optional flags for the disable request.

Return Value

Returns kIOReturnSuccess on success, or an error otherwise.

Discussion

After a supported filter has been successfully enabled, a client can call this method to disable that filter. This method call is synchronized by the workloop's gate.


doDisable


Makes a synchronized call to disable() through executeCommand().

public

virtual IOReturn doDisable( IOService *client);
Discussion

Do not use this method, it may be removed in the future. See disable().


doEnable


Makes a synchronized call to enable() through executeCommand().

public

virtual IOReturn doEnable( IOService *client);
Discussion

Do not use this method, it may be removed in the future. See enable().


enable


An enable request from an IOKernelDebugger client.

protected

virtual IOReturn enable( IOKernelDebugger *debugger);
Parameters
debugger

The IOKernelDebugger client requesting the enable.

Return Value

Returns kIOReturnSuccess. Drivers must return kIOReturnSuccess on success, or an error otherwise.

Discussion

Drivers that provide debugging support may either override this method and set up the hardware to support the polled-mode send and receive methods, receivePacket() and sendPacket(), or override the base enable() and disable() methods that take an IOService argument.


enable(IONetworkInterface *)


A request from an interface client to enable the controller.

protected

virtual IOReturn enable( IONetworkInterface *interface);
Parameters
interface

The interface client object that requested the enable.

Return Value

Returns kIOReturnUnsupported. Drivers that override this method must return kIOReturnSuccess on success, or an error code otherwise.

Discussion

This method is called by an interface client to enable the controller. Upon receiving this command, the controller driver must bring up the hardware and become ready to transmit and receive packets. A driver should also delay the allocation of most runtime resources until this method is called in order to conserve system resources. This method call is synchronized by the workloop's gate.


enable(IOService *)


Handles an enable request from a client.

public

virtual IOReturn enable( IOService *client);
Parameters
client

The client object requesting the enable.

Return Value

Returns the return value from the overloaded enable() method, or kIOReturnBadArgument if the client type is unknown.

Discussion

This method handles an enable request from a client. A client will call enable after it has opened the controller, and before it starts to use the controller to send and to receive packets over the network. The client object provided is typecasted using OSDynamicCast, and depending on whether the client is an IOKernelDebugger or an IONetworkInterface, then an overloaded enable method that takes a more specific argument type is called. If the client matches neither type, then kIOReturnBadArgument is returned. A driver has the option of overriding this base enable method, or the overloaded form. This method call is synchronized by the workloop's gate.


enablePacketFilter


Enables one of the supported packet filters from the given filter group.

public

virtual IOReturn enablePacketFilter( const OSSymbol * group, UInt32 aFilter, UInt32 enabledFilters, IOOptionBits options = 0) = 0;
Parameters
group

The name of the filter group containing the filter to be enabled.

aFilter

The filter to enable.

enabledFilters

All filters currently enabled by the client.

options

Optional flags for the enable request.

Return Value

Returns kIOReturnSuccess on success, or an error otherwise.

Discussion

A client will call this method to enable a supported filter from the filter group specified. If the client wishes to enable more than one filter, it must call this method multiple times to enable the desired set of filters. This method call is synchronized by the workloop's gate.


executeCommand


Makes a C function call through the command gate.

public

virtual IOReturn executeCommand( OSObject *client, Action action, void *target, void *param0 = 0, void *param1 = 0, void *param2 = 0, void *param3 = 0);
Parameters
client

The client requesting the action. This parameter is not passed to the function.

action

Pointer to a C function to be executed.

target

The first parameter in the action callout.

param0

Action parameter 0.

param1

Action parameter 1.

param2

Action parameter 2.

param3

Action parameter 3.

Return Value

Returns the value returned by the action.

Discussion

This method makes a call to a C function that will be synchronized with the workloop thread, and any other threads that are called with the workloop's gate closed.


free


Frees the IONetworkController object.

protected

virtual void free();
Discussion

Frees the IONetworkController object by releasing all allocated resources, followed by a call to super::free().


freePacket


Releases the packet given back to the free pool.

public

virtual void freePacket( mbuf_t, IOOptionBits options = 0);
Parameters
m

The packet to be freed.

options

When kDelayFree option is set, then the packet provided to this function will be queued on the free packet queue. A subsequent call to releaseFreePackets() will release all queued packets by making a single BSD function call. Without the kDelayFree option, the packet provided will be released immediately.


getChecksumDemand


Fetches the demand for hardware checksum computation and insertion for the given packet before it is transmitted on the network.

public

virtual void getChecksumDemand( const mbuf_t packet, UInt32 checksumFamily, UInt32 * demandMask, void * param0 = 0, void *param1 = 0 );
Parameters
packet

An mbuf containing a packet that may be missing one or more checksums in the specified checksum family.

checksumFamily

A value that specifies the checksum family.

demandMask

A mask of all checksums that the hardware must compute and insert into the appropriate checksum fields in the packet.

param0

Optional parameter 0, defaults to 0.

param1

Optional parameter 1, defaults to 0.

Discussion

A network controller that can insert a checksum for output packets must call this method to obtain the set of checksums that it must compute, and insert into the appropriate fields in the given output packet.


getChecksumSupport


Gets checksums that are supported by the network controller for the given checksum family.

public

virtual IOReturn getChecksumSupport( UInt32 *checksumMask, UInt32 checksumFamily, bool isOutput );
Parameters
checksumMask

A pointer to the mask of supported checksums returned by this method.

checksumFamily

A value that specifies the checksum family.

isOutput

Set to true to query the support for checksum insertion on output packets, or false to query the support for checksum verification on input packets. Controllers that have symmetric hardware checksum support can return a fixed checksum mask value, and ignore this argument.

Return Value

Default return is kIOReturnUnsupported. Controllers that override this method must return kIOReturnSuccess. Any other return value will be interpretated as a lack of checksum support, regardless of the value returned through the first argument.

Discussion

A network controller that is capable of inserting and verifying checksums on output and input packets, should override this method and advertise its capability in order to assist or offload the software checksum calculations performed by the protocol stacks.


getCommandClient


Gets the command client object.

protected

virtual OSObject * getCommandClient() const;
Return Value

Returns the command client. If the caller is not running on the workloop thread, or if the thread does not have the workloop's gate closed, then 0 is returned.

Discussion

Methods called on the workloop context to service a client request can call this method to get the client object that initiated the command.


getCommandGate


Gets the IOCommandGate object created by IONetworkController.

public

virtual IOCommandGate * getCommandGate() const;
Return Value

Returns the IOCommandGate object created by IONetworkController.

Discussion

When IONetworkController is started, an IOCommandGate object is instantiated and attached to the workloop returned by getWorkLoop(). This IOCommandGate object is used internally to synchronize client commands handled through executeCommand(). Subclasses that need an IOCommandGate should try to reuse the object returned by this method, rather than creating a new instance. See IOCommandGate documentation.


getFeatures


Reports generic features supported by the controller and/or the driver.

public

virtual UInt32 getFeatures() const;
Return Value

This method will always return 0. Subclasses may override this method and return a bit mask of all supported features.


getHardwareAddress


Gets the network controller's permanent hardware/station address.

public

virtual IOReturn getHardwareAddress( void *addr, UInt32 *inOutAddrBytes) = 0;
Parameters
addr

The buffer where the controller's hardware address should be stored.

inOutAddrBytes

The size of the address buffer provided by the client, and replaced by this method with the actual size of the hardware address in bytes.

Return Value

Returns kIOReturnSuccess on success, or an error otherwise.

Discussion

This method call is synchronized by the workloop's gate.


getMaxPacketSize


Gets the maximum packet size supported by the controller.

public

virtual IOReturn getMaxPacketSize( UInt32 *maxSize) const = 0;
Parameters
maxSize

Pointer to the return value.

Return Value

Returns kIOReturnSuccess on success, or an error code otherwise.


getMediumDictionary


Returns the medium dictionary published by the driver.

public

virtual const OSDictionary * getMediumDictionary() const;
Return Value

Returns the published medium dictionary, or 0 if the driver has not yet published a medium dictionary through publishMediumDictionary().

Discussion

Returns the medium dictionary published by the driver through publishMediumDictionary(). Use copyMediumDictionary() to create and get a copy of the medium dictionary.


getMinPacketSize


Gets the minimum packet size supported by the controller.

public

virtual IOReturn getMinPacketSize( UInt32 *minSize) const = 0;
Parameters
minSize

Pointer to the return value.

Return Value

Returns kIOReturnSuccess on success, or an error code otherwise.


getOutputHandler


Gets the address of the method designated to handle output packets for the network controller.

public

virtual IOOutputAction getOutputHandler() const;
Return Value

Returns a pointer to the outputPacket() method.


getOutputQueue


Gets the IOOutputQueue object created by createOutputQueue().

public

virtual IOOutputQueue * getOutputQueue() const;
Return Value

Returns a reference to the output queue object created by createOutputQueue().


getPacketBufferConstraints


Gets the controller's packet buffer constraints.

public

virtual void getPacketBufferConstraints( IOPacketBufferConstraints *constraints) const;
Parameters
constraints

A pointer to an IOPacketBufferConstraints structure that this method is expected to initialize. See IOPacketBufferConstraints structure definition.

Discussion

Called by start() to obtain the constraints on the memory buffer for each mbuf packet allocated through allocatePacket(). Drivers can override this method to specify the buffer constraints imposed by their bus master hardware. Note that outbound packets, those that originate from the network stack, are not currently subject to the constraints reported here.


getPacketFilters


Gets the set of packet filters supported by the network controller for the given filter group.

public

virtual IOReturn getPacketFilters( const OSSymbol * group, UInt32 * filters) const = 0;
Parameters
group

The name of the filter group.

filters

Pointer to the mask of supported filters returned by this method.

Return Value

Returns kIOReturnSuccess on success, or an error to indicate a failure to discover the set of supported filters.

Discussion

A subclass must implement this method and report the set of filters that are supported for the given filter group. This method call is synchronized by the workloop's gate.


getSelectedMedium


Gets the current selected medium.

public

virtual const IONetworkMedium * getSelectedMedium() const;
Return Value

Returns the current selected medium, the default medium, or 0.

Discussion

If the driver has previously called setSelectedMedium() to indicate its current media selection, then this method will return that medium object. Otherwise, the driver's property table is consulted and a default medium property is examined, and the corresponding entry in the medium dictionary is returned.


handleClose


Handles a client close.

protected

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

The client that is closing the controller.

options

Not used. See IOService.

Discussion

This method handles a close from one of the client objects. IOService calls this method with the arbitration lock held. Subclasses should not override this method.


handleIsOpen


Queries whether a client has an open on the controller.

protected

virtual bool handleIsOpen( const IOService * client) const;
Return Value

Returns true if the specified client, or any client if none (0) is specified, presently has an open on this object.

Discussion

This method is always called by IOService with the arbitration lock held. Subclasses should not override this method.


handleOpen


Handles a client open.

protected

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

The client that is attempting to open the controller.

options

Not used. See IOService.

argument

Not used. See IOService.

Return Value

Returns true to accept the client open, false to refuse it.

Discussion

This method handles a client open on the controller object. IOService calls this method with the arbitration lock held. Subclasses should not override this method.


init


Initializes the IONetworkController object.

public

virtual bool init( OSDictionary *properties);
Parameters
properties

A dictionary object containing a property table associated with this instance.

Return Value

Returns true on success, false otherwise.

Discussion

Instance variables are initialized, then super::init() is called.


newModelString


public

virtual const OSString * newModelString() const;
Return Value

Returns a string describing the model of the network controller. The caller is responsible for releasing the string object returned.


newRevisionString


public

virtual const OSString * newRevisionString() const;
Return Value

Returns a string describing the hardware revision of the network controller. The caller is responsible for releasing the string object returned.


newVendorString


public

virtual const OSString * newVendorString() const;
Return Value

Returns a string describing the vendor of the network controller. The caller is responsible for releasing the string object returned.


outputPacket


Transmits an output packet.

public

virtual UInt32 outputPacket( mbuf_t, void *param);
Parameters
packet

An mbuf chain containing the output packet to be sent on the network.

param

A parameter provided by the caller.

Return Value

Returns a return code defined by the caller.

Discussion

If an IOOutputQueue was created by createOutputQueue(), then this method will be called by the output queue object. Otherwise, an interface object will call this method directly when it receives an output packet from the data link layer.

There is no upper limit on the number of mbufs, hence the number of memory fragments, in the mbuf chain provided. Drivers must be able to handle cases when the mbuf count might exceed the limit supported by their DMA engines, and perform coalescing to copy the various memory fragments into a lesser number of fragments. This complexity can be hidden from the driver when an IOMbufMemoryCursor is used, which is able to convert an mbuf chain into a physical address scatter-gather list that will not exceed a specified number of physically contiguous memory segments. See IOMbufMemoryCursor.

The implementation in IONetworkController performs no useful action and will drop all packets. A driver must override this method and process the output packet provided. The implementation in the driver must not block, since this may cause the network stack to be reentered from an unsafe point.


prepare


Prepares the controller before an IOService is created and attached as a client.

protected

virtual IOReturn prepare();
Return Value

Returns kIOReturnSuccess on success, or an error code otherwise. Returning an error will fail the client attach.

Discussion

This method is called by attachInterface() or attachDebuggerClient() to prepare the controller before the new client object is attached. This method will call publishProperties() to publish controller capabilities and properties that may be used by client objects. However, publishProperties() will be called only once, even if prepare() is called multiple times. This method call is synchronized by the workloop's gate.


publishMediumDictionary


Publishes a dictionary of IONetworkMedium objects to advertise the media selection supported by the network controller.

public

virtual bool publishMediumDictionary( const OSDictionary * mediumDict);
Parameters
mediumDict

A dictionary of IONetworkMedium objects.

Return Value

Returns true if the dictionary is valid, and was successfully exported to the property table, false otherwise.

Discussion

Called by drivers to publish their medium dictionary. Each entry in the dictionary is an IONetworkMedium object that represents a single medium that is supported by the controller. This method will make a copy of the dictionary provided, then add the copy to the driver's property table. The dictionary provided can be released by the caller upon returning from this method. It is permissible to call this method multiple times, which may be necessary if the hardware's media capability changes dynamically. However, if the capability is static, which is often the case, then a driver will typically call this method only once from its start() method.

Several methods depend on the presence of a medium dictionary. They should be called after the medium dictionary has been published. Those methods are: setSelectedMedium() getSelectedMedium() getMediumDictionary() copyMediumDictionary()


publishProperties


Publishes controller properties and capabilities.

protected

virtual bool publishProperties();
Return Value

Returns true if all properties were discovered and published successfully, false otherwise. Returning false will prevent client objects from attaching to the controller, since a property that a client relies upon may be missing.

Discussion

Called by IONetworkController to discover controller properties, and publish them to the property table in the I/O Kit Registry. This method is called once by prepare().


receivePacket


Debugger polled-mode receive handler.

protected

virtual void receivePacket( void *pkt, UInt32 *pktSize, UInt32 timeout);
Parameters
pkt

Address of a receive buffer where the received packet should be stored. This buffer has room for 1518 bytes.

pktSize

Address where the number of bytes received must be recorded. Set this to zero if no packets were received during the timeout interval.

timeout

The maximum amount of time in milliseconds to poll for a packet to arrive before this method must return.

Discussion

This method must be implemented by a driver that supports kernel debugging. After a debugger client has been attached through attachDebuggerClient(), this method will be called by the debugger client to poll for an incoming packet when the kernel debugger is active. This method may be called from the primary interrupt context, and the implementation must avoid any memory allocation, and must never block. The receivePacket() method in IONetworkController is used as a placeholder, it performs no useful action, and should not be called. A driver that attaches a debugger client must override this method.


registerWithPolicyMaker


Implemented by controller drivers to register with the power management policy-maker.

protected

virtual IOReturn registerWithPolicyMaker( IOService *policyMaker);
Parameters
policyMaker

The policy-maker chosen to manage power for this network controller.

Return Value

Returns kIOReturnSuccess on success, kIOReturnUnsupported if the driver does not support power management, or an appropriate error return code. The default return is kIOReturnUnsupported.

Discussion

Drivers that are able to power manage their hardware should override this method and register with the policy-maker provided by calling IOService::registerPowerDriver(). IONetworkController will call this method before the initial attempt is made to attach a client.


releaseDebuggerLock


Releases the global debugger lock.

protected

void releaseDebuggerLock();
Discussion

This method should not be used. Instead, call the unlock() method provided by IOKernelDebugger.


releaseFreePackets


Releases all packets held in the free packet queue.

public

virtual UInt32 releaseFreePackets();
Return Value

Returns the number of packets queued and released.

Discussion

The free packet queue is not protected by a lock. This function must be called in a single-threaded manner with respect to all calls to freePacket() with the kDelayFree option set.


replaceOrCopyPacket


A helper method that combines the functionality of copyPacket() and replacePacket() to process a packet containing a received frame.

public

virtual mbuf_t replaceOrCopyPacket( mbuf_t *mp, UInt32 length, bool *replaced);
Parameters
mp

A handle to the existing packet that may be replaced.

length

The number of bytes received held in the packet. Must be greater than zero.

replaced

Pointer to a return value that is set to true to indicate that the existing packet was replaced, or false to indicate that the existing packet was not replaced, and a copy was created.

Return Value

Returns a replacement or a copy of the existing packet, or 0 if packet allocation failed.

Discussion

This method will either make a copy or replace the existing packet, whichever is more time efficient. Packets containing small frames are copied, otherwise they are replaced. If replaced, then the existing packet is returned, and a new packet with the same buffer size is created to take its place. If copied, the existing packet is left intact, while a copy is returned that will hold a copy of the data from the source packet.


replacePacket


Allocates a new packet to replace an existing packet, the existing packet is then returned.

public

virtual mbuf_t replacePacket( mbuf_t *mp, UInt32 size = 0);
Parameters
mp

A handle to the existing packet.

size

If size is 0, then the new packet shall have the same buffer size as the original packet that is being replaced. Otherwise, the new packet shall have the buffer size specified by this value.

Return Value

If packet allocation was successful, then a replacement will take place and the original packet will be returned. Otherwise, 0 is returned, and the original packet will be left untouched.


reserveDebuggerLock


Takes the global debugger lock.

protected

void reserveDebuggerLock();
Discussion

This method should not be used. Instead, call the lock() method provided by IOKernelDebugger.


selectMedium


A client request to change the medium selection.

public

virtual IOReturn selectMedium( const IONetworkMedium * medium);
Parameters
medium

An entry from the published medium dictionary that represents the selection chosen by the client.

Return Value

Returns kIOReturnUnsupported. Drivers may override this method and return kIOReturnSuccess if the selection was successful, or an error code otherwise.

Discussion

This method is called when a client issues a command for the controller to change its current medium selection. The implementation must call setSelectedMedium() after the change has occurred. This method call is synchronized by the workloop's gate.


selectMediumWithName


A client request to change the medium selection.

public

virtual IOReturn selectMediumWithName( const OSSymbol * mediumName);
Parameters
mediumName

An OSSymbol object that describes the name of the new medium selected by the client.

Return Value

Returns the return from selectMedium() if a matching entry was found from the medium dictionary. Returns kIOReturnUnsupported if a medium dictionary does not exist, or kIOReturnBadArgument if the name given does not match any entry in the medium dictionary.

Discussion

This method is called when a client issues a command for the controller to change its current medium selection. This implementation will look for an entry in the medium dictionary published by the driver that is associated with the key given. If a match is found, then selectMedium() is called to perform the selection, otherwise an error is reported back to the client. Subclasses should override selectMedium() and not this method. This method call is synchronized by the workloop's gate.


sendPacket


Debugger polled-mode transmit handler.

protected

virtual void sendPacket( void *pkt, UInt32 pktSize);
Parameters
pkt

Pointer to a transmit buffer containing the packet to be sent on the network.

pktSize

The size of the transmit buffer in bytes.

Discussion

This method must be implemented by a driver that supports kernel debugging. After a debugger client has been attached through attachDebuggerClient(), this method will be called by the debugger to send an outbound packet only when the kernel debugger is active. This method may be called from the primary interrupt context, and the implementation must avoid any memory allocation, and must never block. The sendPacket() method in IONetworkController is used as a placeholder, it performs no useful action, and should not be called. A driver that attaches a debugger client must override this method.


setChecksumResult


Encodes a received packet with the checksum result reported by the hardware.

public

virtual bool setChecksumResult( mbuf_t packet, UInt32 checksumFamily, UInt32 resultMask, UInt32 validMask, UInt32 param0 = 0, UInt32 param1 = 0 );
Parameters
packet

An mbuf containing a packet that has been checksummed by the hardware.

checksumFamily

A value that specifies the checksum family.

resultMask

A mask of all checksums that were checked or computed. Setting a bit implies that the driver is able to report the result of the checksum computation, by asserting the validity of the checksum, or by returning a partial checksum value.

validMask

A mask of all checksums are were computed and verified by the hardware as valid. Certain types of checksum performed by the hardware are inheritely incomplete, and therefore should never be marked as valid. A checksum cannot be marked valid unless it has also been checked.

param0

Optional parameter 0, defaults to 0.

param1

Optional parameter 1, defaults to 0.

Return Value

Returns true if the checksum family is valid and the packet has been encoded with the checksum result provided, false otherwise.

Discussion

A network controller that can verify the checksum(s) for a received packet, should call this method to encode the result on the packet, before passing it up towards the protocol stacks.


setHardwareAddress


Sets or changes the station address used by the network controller.

public

virtual IOReturn setHardwareAddress( const void * addr, UInt32 addrBytes) = 0;
Parameters
buffer

The buffer containing the hardware address provided by the client.

addrBytes

The size of the address buffer provided by the client in bytes.

Return Value

Returns kIOReturnSuccess on success, or an error otherwise.

Discussion

This method call is synchronized by the workloop's gate.


setLinkStatus


Reports the link status and the active medium.

public

virtual bool setLinkStatus( UInt32 status, const IONetworkMedium * activeMedium = 0, UInt64 speed = 0, OSData *data = 0);
Parameters
status

Link status bits. See IONetworkMedium for the definition of the link status bits.

activeMedium

An object in the published medium dictionary that represents the active medium. This may not be the same as the selected medium. Set this to 0 if the link is inactive.

speed

Link speed in units of bits per second. If zero, then the link speed is taken from the medium object provided.

data

An OSData containing any additional link parameter that the driver wishes to publish to the registry.

Return Value

Returns true if all link properties were successfully updated, false otherwise.

Discussion

Drivers must call this method when a link change is detected. IONetworkController will update the link status properties in the registry, and generate an event to inform the upper layers about the change.


setMaxPacketSize


A client request to change the maximum packet size.

public

virtual IOReturn setMaxPacketSize( UInt32 maxSize);
Parameters
maxSize

The new maximum packet size.

Return Value

Returns kIOReturnUnsupported. Drivers may override this method and return either kIOReturnSuccess to indicate that the new size was accepted and is in effect, or an error code to indicate failure.

Discussion

This method call is synchronized by the workloop's gate.


setSelectedMedium


Designates an entry in the published medium dictionary as the current selected medium.

public

virtual bool setSelectedMedium( const IONetworkMedium * medium);
Parameters
medium

A medium object representing the current selection.

Return Value

Returns true if the property table update was successful, false if the update failed, or if the medium provided does not match any entry from the published medium dictionary.

Discussion

After the driver has configured the hardware to select one of its supported media types, it must call this method to inform its parent about the change that has occurred. IONetworkController will update a property in the registry to reflect the current selection.


start


Starts the network controller.

public

virtual bool start( IOService *provider);
Parameters
provider

The provider that the controller was matched (and attached) to.

Return Value

Returns true on success, false otherwise.

Discussion

After the controller driver has successfully matched to a provider, this method is called to start the network controller. IONetworkController will allocate resources and gather controller properties in its implementation. No I/O will be performed until the subclass tries to attach a client object. A driver must override this method, and call super::start() at the beginning of its own implementation. Then check the return value to make sure that its superclass was started successfully before proceeding. Tasks that are usually performed by a driver's start method are: resource allocation, hardware initialization, allocation of IOEventSources and attaching them to a workloop, publishing a medium dictionary, and finally, attaching an interface object when it is ready to handle client requests.


stop


Stops the network controller.

public

virtual void stop( IOService *provider);
Parameters
provider

The provider that the controller was matched (and attached) to.

Discussion

The counterpart of start(). The controller has been instructed to stop running. The stop() method should release resources and undo actions performed by the start() method. Subclasses must override this method and call super::stop() at the end of its implementation.

Typedefs


Action


See Also:

IONetworkController::Action

public

typedef IOReturn ( *Action)( void *target, void *param0, void *param1, void *param2, void *param3);
Fields
target

The first argument passed to action.

param0

Action parameter 0.

param1

Action parameter 1.

param2

Action parameter 2.

param3

Action parameter 3.

Discussion

Definition of a C function that can be called through executeCommand().


IONetworkController::Action


See Also:

Action

public

typedef IOReturn ( *Action)( void *target, void *param0, void *param1, void *param2, void *param3);
Fields
target

The first argument passed to action.

param0

Action parameter 0.

param1

Action parameter 1.

param2

Action parameter 2.

param3

Action parameter 3.

Discussion

Definition of a C function that can be called through executeCommand().

Member Data


_reserved


See Also:

reserved

private

ExpansionData * _reserved;
Discussion

Reserved for future use. (Internal use only)


reserved


See Also:

_reserved

private

ExpansionData * _reserved;
Discussion

Reserved for future use. (Internal use only)

Enumerations


TCP/IPChecksums


TCP/IP checksums that may be supported by the hardware.

public

enum { kChecksumFamilyTCPIP = 0x00000001, kChecksumIP = 0x0001, kChecksumTCP = 0x0002, kChecksumUDP = 0x0004, kChecksumTCPNoPseudoHeader = 0x0100, kChecksumUDPNoPseudoHeader = 0x0200, kChecksumTCPSum16 = 0x1000 };
Constants
kChecksumFamilyTCPIP

A value that describes the collection of TCP/IP checksums.

kChecksumIP

An IP header checksum.

kChecksumTCP

A TCP checksum that covers the TCP header and TCP data.

kChecksumUDP

A UDP checksum that covers the UDP header and UDP data.

kChecksumTCPNoPseudoHeader

A TCP checksum that covers the TCP header and the TCP data, but the pseudo header is not included in the checksum computation. A partial 16-bit checksum value must be provided to allow the protocol stacks to calculate and verify the final checksum. This type of checksum is not currently supported on the output path.

kChecksumUDPNoPseudoHeader

A UDP checksum that covers the UDP header and the UDP data, but the pseudo header is not included in the checksum computation. A partial 16-bit checksum value must be provided to allow the protocol stacks to calculate and verify the final checksum. This type of checksum is not currently supported on the output path.

kChecksumTCPSum16

The hardware has a simple checksum engine that can perform a TCP style ones complement sum of 16-bit words over a certain range of bytes in a packet. The hardware does not have the ability to scan for IP or TCP headers, and the driver must pass/get additional parameter(s) to or from the protocol stack to coordinate the checksumming effort.


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.

 

Last Updated: 2009-02-23