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