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