Mac Developer Library

Developer

IOEthernetController Class Reference

Options
Deployment Target:

On This Page
Language:

IOEthernetController

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.6 and later.
  • Creates an IOEthernetInterface object.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Frees the IOEthernetController instance.

    Declaration

    C++

    virtual void free();

    Discussion

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

  • Gets the Ethernet controller's permanent station address.

    Declaration

    C++

    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.

  • Gets the Ethernet controller's station address.

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual IOReturn getMaxPacketSize( UInt32 *maxSize) const;

    Parameters

    maxSize

    Pointer to the return value.

    Return Value

    Returns kIOReturnSuccess on success, or an error code otherwise.

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

    Declaration

    C++

    virtual IOReturn getMinPacketSize( UInt32 *minSize) const;

    Parameters

    minSize

    Pointer to the return value.

    Return Value

    Returns kIOReturnSuccess on success, or an error code otherwise.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual bool getVlanTagDemand( mbuf_tm, 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.

  • Initializes an IOEthernetController object.

    Declaration

    C++

    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.

  • IOEthernetController class initializer.

    Declaration

    C++

    static void initialize();

    Discussion

    Creates global OSSymbol objects that are used as keys.

  • Publishes Ethernet controller properties and capabilities.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual IOReturn setHardwareAddress( const void *addr, UInt32addrBytes);

    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.

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

    Declaration

    C++

    virtual IOReturn setMulticastList( IOEthernetAddress *addrs, UInt32count);

    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().

  • Enables or disables multicast mode.

    Declaration

    C++

    virtual IOReturn setMulticastMode( boolactive);

    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.

  • Enables or disables promiscuous mode.

    Declaration

    C++

    virtual IOReturn setPromiscuousMode( boolactive);

    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.

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

    Declaration

    C++

    virtual void setVlanTag( mbuf_tm, UInt32vlanTag);

    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.

  • Enables or disables the wake on Magic Packet support.

    Declaration

    C++

    virtual IOReturn setWakeOnMagicPacket( boolactive);

    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 for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;