Return to IOEthernetController.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / network

Annotation of XNU/iokit/IOKit/network/IOEthernetController.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
        !             3:  *
        !             4:  * @APPLE_LICENSE_HEADER_START@
        !             5:  * 
        !             6:  * The contents of this file constitute Original Code as defined in and
        !             7:  * are subject to the Apple Public Source License Version 1.1 (the
        !             8:  * "License").  You may not use this file except in compliance with the
        !             9:  * License.  Please obtain a copy of the License at
        !            10:  * http://www.apple.com/publicsource and read it before using this file.
        !            11:  * 
        !            12:  * This Original Code and all software distributed under the License are
        !            13:  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
        !            14:  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
        !            15:  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
        !            16:  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
        !            17:  * License for the specific language governing rights and limitations
        !            18:  * under the License.
        !            19:  * 
        !            20:  * @APPLE_LICENSE_HEADER_END@
        !            21:  */
        !            22: /*
        !            23:  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved. 
        !            24:  *
        !            25:  * IOEthernetController.h
        !            26:  *
        !            27:  * HISTORY
        !            28:  *
        !            29:  * Dec 3, 1998  jliu - C++ conversion.
        !            30:  */
        !            31: 
        !            32: #ifndef _IOETHERNETCONTROLLER_H
        !            33: #define _IOETHERNETCONTROLLER_H
        !            34: 
        !            35: #include <IOKit/network/IONetworkController.h>
        !            36: 
        !            37: extern "C" {
        !            38: #include <sys/socket.h>
        !            39: #include <net/if.h>
        !            40: #include <net/etherdefs.h>
        !            41: }
        !            42: 
        !            43: // Property keys.
        !            44: //
        !            45: #define kIOMACAddress           "IOMACAddress"
        !            46: 
        !            47: /*! @enum IOEnetPromiscuousMode
        !            48:     @discussion A promiscuous mode setting passed to setPromiscuousMode() 
        !            49:     method.
        !            50:     @constant kIOEnetPromiscuousModeOff Turn off promiscuous mode.
        !            51:     @constant kIOEnetPromiscuousModeOn  Receive all good frames.
        !            52:               All good frames on the wire are to be received and submitted
        !            53:               to the attached interface.
        !            54:     @constant kIOEnetPromiscuousModeAll Receive all frames, including bad
        !            55:               frames. More work is needed to communicate the error bits
        !            56:               to the upper layers. */
        !            57: 
        !            58: enum IOEnetPromiscuousMode {
        !            59:      kIOEnetPromiscuousModeOff,
        !            60:      kIOEnetPromiscuousModeOn,
        !            61:      kIOEnetPromiscuousModeAll
        !            62: };
        !            63: 
        !            64: /*! @enum IOEnetMulticastMode
        !            65:     @discussion A multicast mode setting passed to setMulticastMode() 
        !            66:     method.
        !            67:     @constant kIOEnetMulticastModeOff Turn off multicast filter.
        !            68:     @constant kIOEnetMulticastModeFilter Enable multicast filter.
        !            69:               All frames with a destination address that matches an
        !            70:               entry in the controller's multicast address list
        !            71:               should be received.
        !            72:     @constant kIOEnetMulticastModeAll Receive all multicast frames. All
        !            73:               frames with a multicast destination address should be
        !            74:               received. */
        !            75: 
        !            76: enum IOEnetMulticastMode {
        !            77:      kIOEnetMulticastModeOff,
        !            78:      kIOEnetMulticastModeFilter,
        !            79:      kIOEnetMulticastModeAll
        !            80: };
        !            81: 
        !            82: /*! @class IOEthernetController
        !            83:     @abstract An abstract superclass for Ethernet controllers.  
        !            84:     Ethernet drivers should subclass IOEthernetController, and implement
        !            85:     or override the hardware specific methods to create a working driver.
        !            86:     An interface object (normally an IOEthernetInterface instance) must
        !            87:     be instantiated to connect the driver to the network layer. */
        !            88:     
        !            89: class IOEthernetController : public IONetworkController
        !            90: {
        !            91:     OSDeclareAbstractStructors(IOEthernetController)
        !            92: 
        !            93: private:
        !            94:     IOEnetMulticastMode     _mcMode;  /* current effective MC mode */
        !            95:     IOEnetPromiscuousMode   _prMode;  /* current effective PR mode */
        !            96: 
        !            97: public:
        !            98: 
        !            99: /*! @function init
        !           100:     @abstract Initialize an IOEthernetController instance.
        !           101:     @param properties A dictionary containing a property table.
        !           102:     @result true if initialized successfully, false otherwise. */
        !           103: 
        !           104:     virtual bool init(OSDictionary * properties);
        !           105: 
        !           106: /*! @function getFamilyFeatureSet
        !           107:     @discussion Get the Ethernet features supported by the controller.
        !           108:     Ethernet controller drivers may override this method and return a mask
        !           109:     containing all supported feature bits.
        !           110:     @result IOEthernetController will always return 0. */
        !           111: 
        !           112:     virtual UInt32 getFamilyFeatureSet() const;
        !           113: 
        !           114: /*! @function doGetHardwareAddress
        !           115:     @discussion Call getHardwareAddress() through syncRequest().
        !           116:     See getHardwareAddress(). */
        !           117: 
        !           118:     virtual IOReturn doGetHardwareAddress(IOService *   client,
        !           119:                                           enet_addr_t * addr);
        !           120: 
        !           121: /*! @function doSetHardwareAddress
        !           122:     @discussion Call setHardwareAddress() through syncRequest().
        !           123:     See setHardwareAddress(). */
        !           124: 
        !           125:     virtual IOReturn doSetHardwareAddress(IOService *         client,
        !           126:                                           const enet_addr_t * addr);
        !           127: 
        !           128: /*! @function doSetMulticastList
        !           129:     @discussion Call setMulticastList() through syncRequest().
        !           130:     See setMulticastList(). */
        !           131: 
        !           132:     virtual IOReturn doSetMulticastList(IOService *   client,
        !           133:                                         enet_addr_t * addrs,
        !           134:                                         UInt          count);
        !           135: 
        !           136: protected:
        !           137: 
        !           138: /*! @function createInterface
        !           139:     @abstract Create an IONetworkInterface object.
        !           140:     @discussion Allocate and return a new IOEthernetInterface instance.
        !           141:     The controller class from each network family must implement this
        !           142:     method inherited from IONetworkController to return the corresponding
        !           143:     interface object when attachInterface() is called.
        !           144:     Subclasses of IOEthernetController (Ethernet drivers) have
        !           145:     little reason to override this implementation.
        !           146:     @result The allocated and initialized IOEthernetInterface instance. */
        !           147: 
        !           148:     virtual IONetworkInterface * createInterface();
        !           149: 
        !           150: /*! @function free
        !           151:     @abstract Frees the IOEthernetController instance. */
        !           152: 
        !           153:     virtual void free();
        !           154: 
        !           155: /*! @function getHardwareAddress
        !           156:     @abstract Get the controller's hardware address (MAC address).
        !           157:     @discussion. Ethernet drivers must implement this method,
        !           158:     by reading the address from hardware and writing it to the buffer provided.
        !           159:     @param addrP Pointer to an enet_addr_t where the hardware address should be
        !           160:     written to.
        !           161:     @result kIOReturnSuccess on success, or an error otherwise. */
        !           162: 
        !           163:     virtual IOReturn getHardwareAddress(enet_addr_t * addrP) = 0;
        !           164: 
        !           165: /*! @function setHardwareAddress
        !           166:     @abstract Change the station's unicast address.
        !           167:     @discussion Called when a client wishes to change the unicast
        !           168:     address used by the controller's hardware filter.
        !           169:     Implementation of this method is optional.
        !           170:     @param addrP Pointer to an enet_addr_t containing the new Ethernet address.
        !           171:     @result kIOReturnUnsupported. Drivers must return kIOReturnSuccess to
        !           172:     indicate success, or an error otherwise. */
        !           173: 
        !           174:     virtual IOReturn setHardwareAddress(const enet_addr_t * addrP);
        !           175: 
        !           176: /*! @function setMulticastMode
        !           177:     @abstract Select a new setting for the controller's multicast filter.
        !           178:     @discussion Called by enablePacketFilters() when the controller's
        !           179:     multicast filter mode needs to be changed. See IOEnetMulticastMode
        !           180:     for the list of defined modes.
        !           181:     @param mode The new multicast filter mode.
        !           182:     @result kIOReturnUnsupported. Drivers must return kIOReturnSuccess to
        !           183:     indicate success, or an error otherwise. */   
        !           184: 
        !           185:     virtual IOReturn setMulticastMode(IOEnetMulticastMode mode);
        !           186: 
        !           187: /*! @function setMulticastList
        !           188:     @abstract Set the list of multicast addresses to be allowed through by
        !           189:     the multicast filter.
        !           190:     @discussion Called by an interface client when its multicast group
        !           191:     membership changes. Drivers that support multicasting should override
        !           192:     this method and update the hardware filter using the address list
        !           193:     provided.
        !           194:     Perfect multicast filtering is preferred if supported by the hardware,
        !           195:     in order to reduce the number of unwanted packets that are received.
        !           196:     If the number of multicast addresses in the list exceed the limit
        !           197:     set by the hardware, or if perfect filtering is not supported,
        !           198:     then ideally the hardware should be programmed to perform imperfect 
        !           199:     filtering, perhaps through a hash table built by the driver.
        !           200:     This method will be called only if getPacketFilters() reports that 
        !           201:     kIOPacketFilterMulticast is supported.
        !           202:     @param addrs Pointer to a list of multicast addresses. Not valid if
        !           203:            the count argument is 0.
        !           204:     @param count The number of multicast addresses in the list. May be
        !           205:            zero if the list is empty.
        !           206:     @result kIOReturnUnsupported. Drivers must return kIOReturnSuccess to
        !           207:     indicate success, or an error otherwise. */
        !           208: 
        !           209:     virtual IOReturn setMulticastList(enet_addr_t * addrs, UInt count);
        !           210: 
        !           211: /*! @function setPromiscuousMode
        !           212:     @abstract Select a new promiscuous mode.
        !           213:     @discussion Called by enablePacketFilters() when the controller's
        !           214:     promiscuous filter mode needs to be changed. See IOEnetPromiscuousMode
        !           215:     for the list of defined modes.
        !           216:     @param mode The new promiscuous filter mode.
        !           217:     @result kIOReturnUnsupported. Drivers must return kIOReturnSuccess to
        !           218:     indicate success, or an error otherwise. */
        !           219: 
        !           220:     virtual IOReturn setPromiscuousMode(IOEnetPromiscuousMode mode);
        !           221: 
        !           222: /*! @function publishCapabilities
        !           223:     @abstract Publish Ethernet controller's properties and capabilities.
        !           224:     @discussion Publish Ethernet specific properties to the property
        !           225:     table. For instance, getHardwareAddress() is called to fetch the
        !           226:     hardware address. This method is called by the superclass and
        !           227:     should never be called by drivers.
        !           228:     @result true if all capabilities were discovered and published
        !           229:     successfully, false otherwise. Returning false will prevent client
        !           230:     objects from attaching to the Ethernet controller since a property
        !           231:     that a client depends on may be missing. */
        !           232: 
        !           233:     virtual bool publishCapabilities();
        !           234: 
        !           235: /*! @function getPacketFilters
        !           236:     @abstract Get the set of packet filters supported by the Ethernet 
        !           237:     controller.
        !           238:     @discussion Returns all the packet filters supported by the Ethernet
        !           239:     controller. See IONetworkController for the list of packet filters.
        !           240:     This method will perform a bitwise OR of kIOPacketFilterUnicast, 
        !           241:     kIOPacketFilterBroadcast, kIOPacketFilterMulticast,
        !           242:     kIOPacketFilterPromiscuous, and write the result to the integer
        !           243:     pointed by 'filtersP'. Drivers that support a different set of filters
        !           244:     should override this method.
        !           245:     @param filtersP Pointer to an integer that shall be updated by this
        !           246:     method to contain the set of supported filters.
        !           247:     @result kIOReturnSuccess. Drivers that override this
        !           248:     method must return kIOReturnSuccess to indicate success, or an error 
        !           249:     otherwise. */
        !           250: 
        !           251:     virtual IOReturn getPacketFilters(UInt32 * filtersP);
        !           252: 
        !           253: /*! @function enablePacketFilters
        !           254:     @abstract Enable a set of packet filters supported by the Ethernet 
        !           255:     controller.
        !           256:     @discussion Called by an interface object to change the set of
        !           257:     packet filters that are enabled by the controller.
        !           258:     The implementation in IOEthernetController will trap
        !           259:     any changes to multicast or promiscuous filters and translate
        !           260:     the changes into a filter mode for setMulticastMode() and
        !           261:     setPromiscuousMode() methods. This is done strictly as a
        !           262:     convenience for drivers, which may choose to override this method
        !           263:     to handle the filter changes directly.
        !           264:     Unicast and Broadcast filters are assumed to be always enabled,
        !           265:     no driver intervention is required.
        !           266:     @param filters Each bit that is set indicates a particular filter that
        !           267:            should be enabled. Filter bits that cleared should be disabled.
        !           268:     @param activeFiltersP Must be updated by this method to contain the filter
        !           269:            set that was activated. Ideally, it should be the same as the filter 
        !           270:            set specified by the first argument.
        !           271:     @result kIOReturnSuccess on success, otherwise an error code is
        !           272:     returned. If (*activeFiltersP != filters), then an error is expected. */
        !           273: 
        !           274:     virtual IOReturn enablePacketFilters(UInt32   filters,
        !           275:                                          UInt32 * activeFiltersP);
        !           276: };
        !           277: 
        !           278: #endif /* !_IOETHERNETCONTROLLER_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.