IOEthernetController

Inherits from
IONetworkController
Availability
Available in OS X v10.6 and later.
Declared in
IOEthernetController.h

Overview

Abstract superclass for Ethernet controllers.

Ethernet controller drivers should subclass IOEthernetController, and implement or override the hardware specific methods to create an Ethernet driver. An interface object (an IOEthernetInterface instance) must be instantiated by the driver, through attachInterface(), to connect the controller driver to the data link layer.

Tasks

Miscellaneous

Instance Methods

createInterface

Creates an IOEthernetInterface object.

virtual IONetworkInterface * createInterface();
Return Value

Returns a newly allocated and initialized IOEthernetInterface object.

Discussion

This method allocates and returns a new IOEthernetInterface instance. A subclass of IONetworkController must implement this method and return a matching interface object. The implementation in IOEthernetController will return an IOEthernetInterface object. Subclasses of IOEthernetController, such as Ethernet controller drivers, will have little reason to override this implementation.

disablePacketFilter

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

virtual IOReturn disablePacketFilter( const OSSymbol *group, UInt32 aFilter, UInt32 enabledFilters, IOOptionBits options = 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 the value returned by setMulticastMode() or setPromiscuousMode() if either of those two methods are called. Returns kIOReturnSuccess if the filter specified is kIOPacketFilterUnicast or kIOPacketFilterBroadcast. Returns kIOReturnUnsupported if the filter group specified is not gIONetworkFilterGroup.

Discussion

The default implementation of the abstract method inherited from IONetworkController. This method will call setMulticastMode() or setPromiscuousMode() when the multicast or the promiscuous filter is to be disabled. Requests to disable the Unicast or Broadcast filters are handled silently, without informing the subclass. Subclasses can override this method to change this default behavior, or to extend it to handle additional filter types or filter groups. This method call is synchronized by the workloop's gate.

enablePacketFilter

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

virtual IOReturn enablePacketFilter( const OSSymbol *group, UInt32 aFilter, UInt32 enabledFilters, IOOptionBits options = 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 the value returned by setMulticastMode() or setPromiscuousMode() if either of those two methods are called. Returns kIOReturnSuccess if the filter specified is kIOPacketFilterUnicast or kIOPacketFilterBroadcast. Returns kIOReturnUnsupported if the filter group specified is not gIONetworkFilterGroup.

Discussion

The default implementation of the abstract method inherited from IONetworkController. This method will call setMulticastMode() or setPromiscuousMode() when the multicast or the promiscuous filter is to be enabled. Requests to disable the Unicast or Broadcast filters are handled silently, without informing the subclass. Subclasses can override this method to change this default behavior, or to extend it to handle additional filter types or filter groups. This method call is synchronized by the workloop's gate.

free

Frees the IOEthernetController instance.

virtual void free();
Discussion

This method releases resources, and is then followed by a call to super::free().

getHardwareAddress(IOEthernetAddress *)

Gets the Ethernet controller's permanent station address.

virtual IOReturn getHardwareAddress( IOEthernetAddress *addrP) = 0;
Parameters
addrP

Pointer to an IOEthernetAddress where the hardware address should be returned.

Return Value

Returns kIOReturnSuccess on success, or an error return code otherwise.

Discussion

Ethernet drivers must implement this method, by reading the address from hardware and writing it to the buffer provided. This method is called from the workloop context.

getHardwareAddress(void *, UInt32 *)

Gets the Ethernet controller's station address.

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

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

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

The default implementation of the abstract method inherited from IONetworkController. This method will call the overloaded form IOEthernetController::getHardwareAddress() that subclasses are expected to override.

getMaxPacketSize

Gets the maximum packet size supported by the Ethernet controller, including the frame header and FCS.

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

Pointer to the return value.

Return Value

Returns kIOReturnSuccess on success, or an error code otherwise.

getMinPacketSize

Gets the minimum packet size supported by the Ethernet controller, including the frame header and FCS.

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

Pointer to the return value.

Return Value

Returns kIOReturnSuccess on success, or an error code otherwise.

getPacketFilters(const OSSymbol *, UInt32 *)

Gets the set of packet filters supported by the Ethernet controller in the given filter group.

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

The name of the filter group.

filters

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

Return Value

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

Discussion

The default implementation of the abstract method inherited from IONetworkController. When the filter group specified is gIONetworkFilterGroup, then this method will return a value formed by a bitwise OR of kIOPacketFilterUnicast, kIOPacketFilterBroadcast, kIOPacketFilterMulticast, kIOPacketFilterPromiscuous. Otherwise, the return value will be set to zero (0). Subclasses must override this method if their filtering capability differs from what is reported by this default implementation. This method is called from the workloop context, and the result is published to the I/O Kit Registry.

getPacketFilters(UInt32 *)

Gets the set of packet filters supported by the Ethernet controller in the network filter group.

virtual IOReturn getPacketFilters( UInt32 *filters) const;
Parameters
filters

Pointer to the return value containing a mask of supported filters.

Return Value

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

getVlanTagDemand

Fetch the demand for hardware vlan tag stuffing for the given packet before it is transmitted on the network.

virtual bool getVlanTagDemand( mbuf_t m, UInt32 *vlanTag);
Parameters
m

A mbuf containing a packet that may require vlan tag stuffing.

vlanTag

After calling, the low order 16 bits contain the 802.1Q priority and vlan ID tag in host order. The hi-order 16 bits are currently unused and should be ignored.

Return Value

true if vlanTag has been set and should be used. false if no vlan tag stuffing is required for this packet.

Discussion

A network controller that can insert 802.1Q vlan tags for output packets must call this method to obtain vlan tag information that it must insert into the given output packet.

init

Initializes an IOEthernetController object.

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.

initialize

IOEthernetController class initializer.

static void initialize();
Discussion

Creates global OSSymbol objects that are used as keys.

publishProperties

Publishes Ethernet controller properties and capabilities.

virtual bool publishProperties();
Return Value

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

Discussion

This method publishes Ethernet controller properties to the property table. For instance, getHardwareAddress() is called to fetch the hardware address, and the address is then published to the property table. This method call is synchronized by the workloop's gate, and must never be called directly by subclasses.

setHardwareAddress(const IOEthernetAddress *)

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

virtual IOReturn setHardwareAddress( const IOEthernetAddress *addrP);
Parameters
addrP

Pointer to an IOEthernetAddress containing the new station address.

Return Value

The default implementation will always return kIOReturnUnsupported. If overridden, drivers must return kIOReturnSuccess on success, or an error return code otherwise.

Discussion

This method is called in response to a client command to change the station address used by the Ethernet controller. Implementation of this method is optional. This method is called from the workloop context.

setHardwareAddress(const void *, UInt32)

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

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

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

The default implementation of the abstract method inherited from IONetworkController. This method will call the overloaded form IOEthernetController::setHardwareAddress() that subclasses are expected to override.

setMulticastList

Sets the list of multicast addresses a multicast filter should use to match against the destination address of an incoming frame.

virtual IOReturn setMulticastList( IOEthernetAddress *addrs, UInt32 count);
Parameters
addrs

An array of Ethernet addresses. This argument must be ignored if the count argument is 0.

count

The number of Ethernet addresses in the list. This value will be zero when the list becomes empty.

Return Value

Returns kIOReturnUnsupported. Drivers must return kIOReturnSuccess to indicate success, or an error return code otherwise.

Discussion

This method sets the list of multicast addresses that the multicast filter should use to match against the destination address of an incoming frame. The frame should be accepted when a match occurs. Called when the multicast group membership of an interface object is changed. Drivers that support kIOPacketFilterMulticast should override this method and update the hardware multicast filter using the list of Ethernet addresses provided. Perfect multicast filtering is preferred if supported by the hardware, in order to reduce the number of unwanted packets received. If the number of multicast addresses in the list exceeds what the hardware is capable of supporting, or if perfect filtering is not supported, then ideally the hardware should be programmed to perform imperfect filtering, through some form of hash filtering mechanism. Only as a last resort should the driver enable reception of all multicast packets to satisfy this request. This method is called from the workloop context, and only if the driver reports kIOPacketFilterMulticast support in getPacketFilters().

setMulticastMode

Enables or disables multicast mode.

virtual IOReturn setMulticastMode( bool active);
Parameters
active

True to enable multicast mode, false to disable it.

Return Value

Returns kIOReturnUnsupported. If overridden, drivers must return kIOReturnSuccess on success, or an error return code otherwise.

Discussion

Called by enablePacketFilter() or disablePacketFilter() when there is a change in the activation state of the multicast filter identified by kIOPacketFilterMulticast. This method is called from the workloop context.

setPromiscuousMode

Enables or disables promiscuous mode.

virtual IOReturn setPromiscuousMode( bool active);
Parameters
active

True to enable promiscuous mode, false to disable it.

Return Value

Returns kIOReturnUnsupported. If overridden, drivers must return kIOReturnSuccess on success, or an error return code otherwise.

Discussion

Called by enablePacketFilter() or disablePacketFilter() when there is a change in the activation state of the promiscuous filter identified by kIOPacketFilterPromiscuous. This method is called from the workloop context.

setVlanTag

Encode a received packet with the vlan tag result reported by the hardware.

virtual void setVlanTag( mbuf_t m, UInt32 vlanTag);
Parameters
m

A mbuf containing a packet that has had its 802.1q vlan tag stripped by the hardware.

vlanTag

A value in host order that contains the 802.1q vlan tag and priority in the low order 16 bits. The hi order word is currently unused and should be set to 0.

Discussion

A network controller that can strip 802.1Q vlan tag information for a received packet should call this method to encode the result on the packet, before passing it up towards the protocol stacks.

setWakeOnMagicPacket

Enables or disables the wake on Magic Packet support.

virtual IOReturn setWakeOnMagicPacket( bool active);
Parameters
active

True to enable support for system wake on reception of a Magic Packet, false to disable it.

Return Value

Returns kIOReturnUnsupported. If overridden, drivers must return kIOReturnSuccess on success, or an error return code otherwise.

Discussion

Called by enablePacketFilter() or disablePacketFilter() when there is a change in the activation state of the Wake-on-LAN filter identified by kIOEthernetWakeOnMagicPacket. This method is called from the workloop context.

Instance Variables

reserved

ExpansionData * _reserved;

Reserved for future use. (Internal use only)

See Also

_reserved

ExpansionData * _reserved;

Reserved for future use. (Internal use only)

See Also