iokit/IOKit/network/IOEthernetController.h

   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 /*! @defined kIOEthernetControllerClass
  38     @abstract kIOEthernetControllerClass is the name of the
  39         IOEthernetController class. */
  40
  41 #define kIOEthernetControllerClass        "IOEthernetController"
  42
  43 /*! @defined kIOEthernetAddressSize
  44     @abstract The number of bytes in an Ethernet hardware address. */
  45
  46 #define kIOEthernetAddressSize            6
  47
  48 /*! @defined kIOEthernetMaxPacketSize
  49     @abstract The maximum size of an Ethernet packet, including
  50         the FCS bytes. */
  51
  52 #define kIOEthernetMaxPacketSize          1518
  53
  54 /*! @defined kIOEthernetMinPacketSize
  55     @abstract The minimum size of an Ethernet packet, including
  56         the FCS bytes. */
  57
  58 #define kIOEthernetMinPacketSize          64
  59
  60 /*! @defined kIOEthernetCRCSize
  61     @abstract The size in bytes of the 32-bit CRC value appended
  62         to the end of each Ethernet frame. */
  63
  64 #define kIOEthernetCRCSize                4
  65
  66 /*! @defined kIOEthernetWakeOnLANFilterGroup
  67     @abstract kIOEthernetWakeOnLANFilterGroup describes the name assigned
  68         to the Ethernet wake-On-LAN filter group. */
  69
  70 #define kIOEthernetWakeOnLANFilterGroup   "IOEthernetWakeOnLANFilterGroup"
  71
  72 /*! @enum Enumeration of wake-On-LAN filters.
  73     @discussion An enumeration of all filters in the wake-on-LAN filter
  74         group. Each filter listed will respond to a network event that
  75         will trigger a system wake-up.
  76     @constant kIOEthernetWakeOnMagicPacket Reception of a Magic Packet. */
  77
  78 enum {
  79     kIOEthernetWakeOnMagicPacket = 0x1
  80 };
  81
  82 /*
  83  * Kernel
  84  */
  85 #if defined(KERNEL) && defined(__cplusplus)
  86
  87 struct IOEthernetAddress {
  88         UInt8 bytes[kIOEthernetAddressSize];
  89 };
  90
  91 extern "C" {  // FIXME - remove
  92 #include <sys/socket.h>
  93 #include <net/if.h>
  94 #include <net/etherdefs.h>
  95 }
  96
  97 /*!     @defined gIOEthernetWakeOnLANFilterGroup
  98     @discussion gIOEthernetWakeOnLANFilterGroup is an OSSymbol object
  99         that contains the name of the Ethernet wake-on-LAN filter group
 100         defined by kIOEthernetWakeOnLANFilterGroup. */
 101
 102 extern const OSSymbol * gIOEthernetWakeOnLANFilterGroup;
 103
 104 /*! @class IOEthernetController : public IONetworkController
 105     @abstract An abstract superclass for Ethernet controllers. Ethernet
 106     controller drivers should subclass IOEthernetController, and implement
 107     or override the hardware specific methods to create an Ethernet driver.
 108     An interface object (an IOEthernetInterface instance) must be
 109     instantiated by the driver, through attachInterface(), to connect
 110     the controller driver to the data link layer. */
 111
 112 class IOEthernetController : public IONetworkController
 113 {
 114     OSDeclareAbstractStructors( IOEthernetController )
 115
 116 protected:
 117     struct ExpansionData { };
 118     /*! @var reserved
 119         Reserved for future use.  (Internal use only)  */
 120     ExpansionData *  _reserved;
 121
 122
 123 public:
 124
 125 /*! @function initialize
 126     @abstract IOEthernetController class initializer.
 127     @discussion Create global OSSymbol objects that are used as keys. */
 128
 129     static void initialize();
 130
 131 /*! @function init
 132     @abstract Initialize an IOEthernetController object.
 133     @param properties A dictionary object containing a property table
 134         associated with this instance.
 135     @result true on success, false otherwise. */
 136
 137     virtual bool init(OSDictionary * properties);
 138
 139 /*! @function getPacketFilters
 140     @abstract Get the set of packet filters supported by the Ethernet
 141     controller in the given filter group.
 142     @discussion The default implementation of the abstract method inherited
 143     from IONetworkController. When the filter group specified is
 144     gIONetworkFilterGroup, then this method will return a value formed by
 145     a bitwise OR of kIOPacketFilterUnicast, kIOPacketFilterBroadcast,
 146     kIOPacketFilterMulticast, kIOPacketFilterPromiscuous. Otherwise, the
 147     return value will be set to zero (0). Subclasses must override this
 148     method if their filtering capability differs from what is reported by
 149     this default implementation. This method is called from the workloop
 150     context, and the result is published to the I/O Kit registry.
 151     @param group The name of the filter group.
 152     @param filters Pointer to the mask of supported filters returned by
 153         this method.
 154     @result kIOReturnSuccess. Drivers that override this
 155     method must return kIOReturnSuccess to indicate success, or an error
 156     return code otherwise. */
 157
 158     virtual IOReturn getPacketFilters(const OSSymbol * group,
 159                                       UInt32 *         filters) const;
 160
 161 /*! @function enablePacketFilter
 162     @abstract Enable one of the supported packet filters from the
 163     given filter group.
 164     @discussion The default implementation of the abstract method inherited
 165     from IONetworkController. This method will call setMulticastMode() or
 166     setPromiscuousMode() when the multicast or the promiscuous filter is to be
 167     enabled. Requests to disable the Unicast or Broadcast filters are handled
 168     silently, without informing the subclass. Subclasses can override this
 169     method to change this default behavior, or to extend it to handle
 170     additional filter types or filter groups. This method call is synchronized
 171     by the workloop's gate.
 172     @param group The name of the filter group containing the filter to be
 173     enabled.
 174     @param aFilter The filter to enable.
 175     @param enabledFilters All filters currently enabled by the client.
 176     @param options Optional flags for the enable request.
 177     @result The return from setMulticastMode() or setPromiscuousMode() if
 178     either of those two methods are called. kIOReturnSuccess if the filter
 179     specified is kIOPacketFilterUnicast or kIOPacketFilterBroadcast.
 180     kIOReturnUnsupported if the filter group specified is not
 181     gIONetworkFilterGroup. */
 182
 183     virtual IOReturn enablePacketFilter(const OSSymbol * group,
 184                                         UInt32           aFilter,
 185                                         UInt32           enabledFilters,
 186                                         IOOptionBits     options = 0);
 187
 188 /*! @function disablePacketFilter
 189     @abstract Disable a packet filter that is currently enabled from the
 190     given filter group.
 191     @discussion The default implementation of the abstract method inherited
 192     from IONetworkController. This method will call setMulticastMode() or
 193     setPromiscuousMode() when the multicast or the promiscuous filter is to be
 194     disabled. Requests to disable the Unicast or Broadcast filters are handled
 195     silently, without informing the subclass. Subclasses can override this
 196     method to change this default behavior, or to extend it to handle
 197     additional filter types or filter groups. This method call is synchronized
 198     by the workloop's gate.
 199     @param group The name of the filter group containing the filter to be
 200     disabled.
 201     @param aFilter The filter to disable.
 202     @param enabledFilters All filters currently enabled by the client.
 203     @param options Optional flags for the disable request.
 204     @result The return from setMulticastMode() or setPromiscuousMode() if
 205     either of those two methods are called. kIOReturnSuccess if the filter
 206     specified is kIOPacketFilterUnicast or kIOPacketFilterBroadcast.
 207     kIOReturnUnsupported if the filter group specified is not
 208     gIONetworkFilterGroup. */
 209
 210     virtual IOReturn disablePacketFilter(const OSSymbol * group,
 211                                          UInt32           aFilter,
 212                                          UInt32           enabledFilters,
 213                                          IOOptionBits     options = 0);
 214
 215 /*! @function getHardwareAddress
 216     @abstract Get the Ethernet controller's station address.
 217     @discussion The default implementation of the abstract method inherited
 218     from IONetworkController. This method will call the overloaded form
 219     IOEthernetController::getHardwareAddress() that subclasses are expected
 220     to override.
 221     @param addr The buffer where the controller's hardware address should
 222            be written.
 223     @param inOutAddrBytes The size of the address buffer provided by the
 224            client, and replaced by this method with the actual size of
 225            the hardware address in bytes.
 226     @result kIOReturnSuccess on success, or an error otherwise. */
 227
 228     virtual IOReturn getHardwareAddress(void *   addr,
 229                                         UInt32 * inOutAddrBytes);
 230
 231 /*! @function setHardwareAddress
 232     @abstract Set or change the station address used by the Ethernet
 233     controller.
 234     @discussion The default implementation of the abstract method inherited
 235     from IONetworkController. This method will call the overloaded form
 236     IOEthernetController::setHardwareAddress() that subclasses are expected
 237     to override.
 238     @param addr The buffer containing the hardware address provided by
 239     the client.
 240     @param addrBytes The size of the address buffer provided by the
 241     client in bytes.
 242     @result kIOReturnSuccess on success, or an error otherwise. */
 243
 244     virtual IOReturn setHardwareAddress(const void * addr,
 245                                         UInt32       addrBytes);
 246
 247 /*! @function getMaxPacketSize
 248     @abstract Get the maximum packet size supported by the Ethernet
 249         controller, including the frame header and FCS.
 250     @param maxSize Pointer to the return value.
 251     @result kIOReturnSuccess on success, or an error code otherwise. */
 252
 253     virtual IOReturn getMaxPacketSize(UInt32 * maxSize) const;
 254
 255 /*! @function getMinPacketSize
 256     @abstract Get the minimum packet size supported by the Ethernet
 257         controller, including the frame header and FCS.
 258     @param minSize Pointer to the return value.
 259     @result kIOReturnSuccess on success, or an error code otherwise. */
 260
 261     virtual IOReturn getMinPacketSize(UInt32 * minSize) const;
 262
 263 /*! @function getPacketFilters
 264     @abstract Get the set of packet filters supported by the Ethernet
 265     controller in the network filter group.
 266     @param filters Pointer to the return value containing a mask of
 267     supported filters.
 268     @result kIOReturnSuccess. Drivers that override this
 269     method must return kIOReturnSuccess to indicate success, or an error
 270     return code otherwise. */
 271
 272     virtual IOReturn getPacketFilters(UInt32 * filters) const;
 273
 274 /*! @function getHardwareAddress
 275     @abstract Get the Ethernet controller's permanent station address.
 276     @discussion. Ethernet drivers must implement this method, by reading the
 277     address from hardware and writing it to the buffer provided. This method
 278     is called from the workloop context.
 279     @param addrP Pointer to an IOEthernetAddress where the hardware address
 280     should be returned.
 281     @result kIOReturnSuccess on success, or an error return code otherwise. */
 282
 283     virtual IOReturn getHardwareAddress(IOEthernetAddress * addrP) = 0;
 284
 285 /*! @function setHardwareAddress
 286     @abstract Set or change the station address used by the Ethernet
 287         controller.
 288     @discussion This method is called in response to a client command to
 289     change the station address used by the Ethernet controller. Implementation
 290     of this method is optional. This method is called from the workloop context.
 291     @param addrP Pointer to an IOEthernetAddress containing the new station
 292     address.
 293     @result The default implementation will always return kIOReturnUnsupported.
 294     If overridden, drivers must return kIOReturnSuccess on success, or an error
 295     return code otherwise. */
 296
 297     virtual IOReturn setHardwareAddress(const IOEthernetAddress * addrP);
 298
 299 /*! @function setMulticastMode
 300     @abstract Enable or disable multicast mode.
 301     @discussion Called by enablePacketFilter() or disablePacketFilter()
 302     when there is a change in the activation state of the multicast filter
 303     identified by kIOPacketFilterMulticast. This method is called from the
 304     workloop context.
 305     @param active True to enable multicast mode, false to disable it.
 306     @result kIOReturnUnsupported. If overridden, drivers must return
 307     kIOReturnSuccess on success, or an error return code otherwise. */
 308
 309     virtual IOReturn setMulticastMode(bool active);
 310
 311 /*! @function setMulticastList
 312     @abstract Set the list of multicast addresses that the multicast filter
 313     should use to match against the destination address of an incoming frame.
 314     The frame should be accepted when a match occurs.
 315     @discussion Called when the multicast group membership of an interface
 316     object is changed. Drivers that support kIOPacketFilterMulticast should
 317     override this method and update the hardware multicast filter using the
 318     list of Ethernet addresses provided. Perfect multicast filtering is
 319     preferred if supported by the hardware, to order to reduce the number of
 320     unwanted packets received. If the number of multicast addresses in the
 321     list exceeds what the hardware is capable of supporting, or if perfect
 322     filtering is not supported, then ideally the hardware should be programmed
 323     to perform imperfect filtering, thorugh some form of hash filtering
 324     mechanism. Only at the last resort should the driver enable reception of
 325     all multicast packets to satisfy this request. This method is called
 326     from the workloop context, and only if the driver reports
 327     kIOPacketFilterMulticast support in getPacketFilters().
 328     @param addrs An array of Ethernet addresses. This argument must be
 329         ignored if the count argument is 0.
 330     @param count The number of Ethernet addresses in the list. This value
 331         will be zero when the list becomes empty.
 332     @result kIOReturnUnsupported. Drivers must return kIOReturnSuccess to
 333     indicate success, or an error return code otherwise. */
 334
 335     virtual IOReturn setMulticastList(IOEthernetAddress * addrs,
 336                                       UInt32              count);
 337
 338 /*! @function setPromiscuousMode
 339     @abstract Enable or disable promiscuous mode.
 340     @discussion Called by enablePacketFilter() or disablePacketFilter()
 341     when there is a change in the activation state of the promiscuous
 342     filter identified by kIOPacketFilterPromiscuous. This method is
 343     called from the workloop context.
 344     @param active True to enable promiscuous mode, false to disable it.
 345     @result kIOReturnUnsupported. If overridden, drivers must return
 346     kIOReturnSuccess on success, or an error return code otherwise. */
 347
 348     virtual IOReturn setPromiscuousMode(bool active);
 349
 350 /*! @function setWakeOnMagicPacket
 351     @abstract Enable or disable the wake on Magic Packet support.
 352     @discussion Called by enablePacketFilter() or disablePacketFilter()
 353     when there is a change in the activation state of the wake-on-LAN
 354     filter identified by kIOEthernetWakeOnMagicPacket. This method is
 355     called from the workloop context.
 356     @param active True to enable support for system wake on reception
 357     of a Magic Packet, false to disable it.
 358     @result kIOReturnUnsupported. If overridden, drivers must return
 359     kIOReturnSuccess on success, or an error return code otherwise. */
 360
 361     virtual IOReturn setWakeOnMagicPacket(bool active);
 362
 363 protected:
 364
 365 /*! @function createInterface
 366     @abstract Create an IOEthernetInterface object.
 367     @discussion Allocate and return a new IOEthernetInterface instance.
 368     A subclass of IONetworkController must implement this method and return
 369     a matching interface object. The implementation in IOEthernetController
 370     will return an IOEthernetInterface object. Subclasses of
 371     IOEthernetController, such as Ethernet controller drivers, will have
 372     little reason to override this implementation.
 373     @result A newly allocated and initialized IOEthernetInterface object. */
 374
 375     virtual IONetworkInterface * createInterface();
 376
 377 /*! @function free
 378     @abstract Free the IOEthernetController instance. Release resources,
 379     then followed by a call to super::free(). */
 380
 381     virtual void free();
 382
 383 /*! @function publishProperties
 384     @abstract Publish Ethernet controller properties and capabilities.
 385     @discussion Publish Ethernet controller properties to the property
 386     table. For instance, getHardwareAddress() is called to fetch the
 387     hardware address, and the address is then published to the property
 388     table. This method call is synchronized by the workloop's gate,
 389     and must never be called directly by subclasses.
 390     @result true if all properties and capabilities were discovered,
 391     and published successfully, false otherwise. Returning false will
 392     prevent client objects from attaching to the Ethernet controller
 393     since a property that a client relies upon may be missing. */
 394
 395     virtual bool publishProperties();
 396
 397     // Virtual function padding
 398     OSMetaClassDeclareReservedUnused( IOEthernetController,  0);
 399     OSMetaClassDeclareReservedUnused( IOEthernetController,  1);
 400     OSMetaClassDeclareReservedUnused( IOEthernetController,  2);
 401     OSMetaClassDeclareReservedUnused( IOEthernetController,  3);
 402     OSMetaClassDeclareReservedUnused( IOEthernetController,  4);
 403     OSMetaClassDeclareReservedUnused( IOEthernetController,  5);
 404     OSMetaClassDeclareReservedUnused( IOEthernetController,  6);
 405     OSMetaClassDeclareReservedUnused( IOEthernetController,  7);
 406     OSMetaClassDeclareReservedUnused( IOEthernetController,  8);
 407     OSMetaClassDeclareReservedUnused( IOEthernetController,  9);
 408     OSMetaClassDeclareReservedUnused( IOEthernetController, 10);
 409     OSMetaClassDeclareReservedUnused( IOEthernetController, 11);
 410     OSMetaClassDeclareReservedUnused( IOEthernetController, 12);
 411     OSMetaClassDeclareReservedUnused( IOEthernetController, 13);
 412     OSMetaClassDeclareReservedUnused( IOEthernetController, 14);
 413     OSMetaClassDeclareReservedUnused( IOEthernetController, 15);
 414     OSMetaClassDeclareReservedUnused( IOEthernetController, 16);
 415     OSMetaClassDeclareReservedUnused( IOEthernetController, 17);
 416     OSMetaClassDeclareReservedUnused( IOEthernetController, 18);
 417     OSMetaClassDeclareReservedUnused( IOEthernetController, 19);
 418     OSMetaClassDeclareReservedUnused( IOEthernetController, 20);
 419     OSMetaClassDeclareReservedUnused( IOEthernetController, 21);
 420     OSMetaClassDeclareReservedUnused( IOEthernetController, 22);
 421     OSMetaClassDeclareReservedUnused( IOEthernetController, 23);
 422     OSMetaClassDeclareReservedUnused( IOEthernetController, 24);
 423     OSMetaClassDeclareReservedUnused( IOEthernetController, 25);
 424     OSMetaClassDeclareReservedUnused( IOEthernetController, 26);
 425     OSMetaClassDeclareReservedUnused( IOEthernetController, 27);
 426     OSMetaClassDeclareReservedUnused( IOEthernetController, 28);
 427     OSMetaClassDeclareReservedUnused( IOEthernetController, 29);
 428     OSMetaClassDeclareReservedUnused( IOEthernetController, 30);
 429     OSMetaClassDeclareReservedUnused( IOEthernetController, 31);
 430 };
 431
 432 /*
 433  * FIXME: remove this.
 434  */
 435 enum {
 436     kIOEnetPromiscuousModeOff   = false,
 437     kIOEnetPromiscuousModeOn    = true,
 438     kIOEnetPromiscuousModeAll   = true,
 439     kIOEnetMulticastModeOff     = false,
 440     kIOEnetMulticastModeFilter  = true
 441 };
 442 typedef bool IOEnetPromiscuousMode;
 443 typedef bool IOEnetMulticastMode;
 444
 445 #endif /* defined(KERNEL) && defined(__cplusplus) */
 446
 447 #endif /* !_IOETHERNETCONTROLLER_H */