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 _IONETWORKCONTROLLER_H 24#define _IONETWORKCONTROLLER_H 25 26/*! @defined kIONetworkControllerClass 27 @abstract The name of the IONetworkController class. */ 28 29#define kIONetworkControllerClass "IONetworkController" 30 31/*! @defined kIOVendor 32 @abstract A property of IONetworkController objects. 33 @discussion The kIOVendor property is a property of IONetworkController objects. It has an OSString value that describes the vendor of the network controller. */ 34 35#define kIOVendor "IOVendor" 36 37/*! @defined kIOModel 38 @abstract A property of IONetworkController objects. 39 @discussion The kIOModel property is a property of IONetworkController objects. It has an OSString value that describes the model of the network controller. */ 40 41#define kIOModel "IOModel" 42 43/*! @defined kIORevision 44 @abstract A property of IONetworkController objects. 45 @discussion The kIORevision property is a property of IONetworkController objects. It has an OSString value that describes the revision level of the network controller. */ 46 47#define kIORevision "IORevision" 48 49/*! @defined kIOFeatures 50 @abstract A property of IONetworkController objects. 51 @discussion The kIOFeatures property is a property of IONetworkController objects. It has an OSNumber value that describes generic features defined by IONetworkController that are supported by the 52 network controller. */ 53 54#define kIOFeatures "IOFeatures" 55 56/*! @defined kIOMediumDictionary 57 @abstract A property of IONetworkController objects. 58 @discussion The kIOMediumDictionary property is a property of IONetworkController 59 objects. It has an OSDictionary value that is a container for the 60 collection of IONetworkMedium objects that represent the media 61 types supported by the network controller. 62 Each entry in the dictionary is a key/value pair consisting of 63 the medium name, and a dictionary value that contains the 64 properties for that medium entry. */ 65 66#define kIOMediumDictionary "IOMediumDictionary" 67 68/*! @defined kIODefaultMedium 69 @abstract A property of IONetworkController objects. 70 @discussion The kIODefaultMedium property is a property of IONetworkController 71 objects. It has an OSString value that describes the name of the 72 default medium. This definition may change or disappear in the 73 future. */ 74 75#define kIODefaultMedium "IODefaultMedium" 76 77/*! @defined kIOSelectedMedium 78 @abstract A property of IONetworkController objects. 79 @discussion The kIOSelectedMedium property is a property of IONetworkController 80 objects. It has an OSSymbol value that describes the name of the 81 current selected medium. This name can be used as a key into the 82 medium dictionary to gather additional information about the 83 selected medium. */ 84 85#define kIOSelectedMedium "IOSelectedMedium" 86 87/*! @defined kIOActiveMedium 88 @abstract A property of IONetworkController objects. 89 @discussion The kIOActiveMedium property is a property of IONetworkController 90 objects. It has an OSSymbol value that describes the name of the 91 active medium. This is the name of the medium where an active 92 link has been established. This name can be used as a key into 93 the medium dictionary to gather additional information about the 94 active medium. */ 95 96#define kIOActiveMedium "IOActiveMedium" 97 98/*! @defined kIOLinkSpeed 99 @abstract A property of IONetworkController objects. 100 @discussion The kIOLinkSpeed property is a property of IONetworkController 101 objects. It has an OSNumber value that describes the speed of the 102 link established over the active medium in bits per second. */ 103 104#define kIOLinkSpeed "IOLinkSpeed" 105 106/*! @defined kIOLinkStatus 107 @abstract A property of IONetworkController objects. 108 @discussion The kIOLinkStatus property is a property of IONetworkController 109 objects. It has an OSNumber value that describes the current network 110 link status. See IONetworkMedium for the definition of the link 111 status bits. */ 112 113#define kIOLinkStatus "IOLinkStatus" 114 115/*! @defined kIOLinkData 116 @abstract A property of IONetworkController objects. 117 @discussion The kIOLinkData property is a property of IONetworkController 118 objects. It has an OSData value that contains additional information 119 describing the active link that was established. 120 Its interpretation is not defined. */ 121 122#define kIOLinkData "IOLinkData" 123 124/*! @defined kIOPacketFilters 125 @abstract A property of IONetworkController objects. 126 @discussion The kIOPacketFilters property is a property of IONetworkController 127 objects. It has an OSDictionary value that describes the entire 128 set of packet filters supported by the controller. Each entry 129 in the dictionary is a key/value pair consisting of the filter 130 group name, and an OSNumber describing the set of supported 131 filters for that group. */ 132 133#define kIOPacketFilters "IOPacketFilters" 134 135/*! @defined kIOMACAddress 136 @abstract A property of IONetworkController objects. 137 @discussion The kIOMACAddress property is a property of IONetworkController 138 objects. It has an OSData value that describes the hardware 139 MAC (media access controller) address, or station address, 140 of the network controller. */ 141 142#define kIOMACAddress "IOMACAddress" 143 144/*! @defined kIOMaxPacketSize 145 @abstract A property of IONetworkController objects. 146 @discussion The kIOMaxPacketSize property is a property of IONetworkController 147 objects. It has an OSNumber value that describes the maximum 148 packet size supported by the controller. */ 149 150#define kIOMaxPacketSize "IOMaxPacketSize" 151 152/*! @defined kIOMinPacketSize 153 @abstract A property of IONetworkController objects. 154 @discussion The kIOMinPacketSize property is a property of IONetworkController 155 objects. It has an OSNumber value that describes the minimum 156 packet size supported by the controller. */ 157 158#define kIOMinPacketSize "IOMinPacketSize" 159 160/*! @defined kIONetworkFilterGroup 161 @abstract The name assigned to the standard network filter group. */ 162 163#define kIONetworkFilterGroup "IONetworkFilterGroup" 164 165/*! @enum StandardPacketFilters 166 @abstract All standard packet filters. 167 @discussion Each filter will allow the reception of certain class of packets 168 depending on its destination MAC address. 169 @constant kIOPacketFilterUnicast Reception of unicast packets. 170 @constant kIOPacketFilterBroadcast Reception of broadcast packets. 171 @constant kIOPacketFilterMulticast Reception of multicast packets 172 addressed to a set of multicast addresses. 173 @constant kIOPacketFilterMulticastAll Reception of all multicast 174 packets. 175 @constant kIOPacketFilterPromiscuous Reception of all packets. 176 @constant kIOPacketFilterPromiscuousAll Reception of all packets, 177 including bad packets. */ 178 179enum { 180 kIOPacketFilterUnicast = 0x1, 181 kIOPacketFilterBroadcast = 0x2, 182 kIOPacketFilterMulticast = 0x10, 183 kIOPacketFilterMulticastAll = 0x20, 184 kIOPacketFilterPromiscuous = 0x100, 185 kIOPacketFilterPromiscuousAll = 0x200 186}; 187 188/*! @enum Network Feature Flags 189 @abstract Feature flags returned by the getFeatures() method. 190 @constant kIONetworkFeatureNoBSDWait Set this bit in the value 191 returned by getFeatures() to disable the automatic wait for 192 "IOBSD" resource by the IONetworkController::start() method. 193 @constant kIONetworkFeatureHardwareVlan Set this bit in the value 194 returned by getFeatures() to indicate the controller supports hardware 195 stripping and stuffing of 802.1q vlan tags. If the controller supports 196 this feature it must enable it when initializing so that all received 197 packets delivered to higher layers have the tag stripped. The controller 198 should use setVlanTag() to provide the tag information out of band. 199 @constant kIONetworkFeatureSoftwareVlan Set this bit in the value 200 returned by getFeatures() to indicate that the controller can support software 201 based vlan by transmitting and receiving packets 4 bytes longer that normal. 202 @constant kIONetworkFeatureMultiPages Set this bit if the driver is 203 capable of handling packets coming down from the network stack that 204 reside in virtually, but not in physically contiguous span of the 205 external mbuf clusters. In this case, the data area of a packet in 206 the external mbuf cluster might cross one or more physical pages that 207 are disjoint, depending on the interface MTU and the packet size. 208 Such a use of larger than system page size clusters by the network 209 stack is done for better system efficiency. Drivers that utilize the 210 IOMbufNaturalMemoryCursor with the getPhysicalSegmentsWithCoalesce 211 interfaces and enumerate the list of vectors should set this flag 212 for possible gain in performance during bulk data transfer. 213 @constant kIONetworkFeatureTSOIPv4 Set this bit to advertise support 214 for TCP/IPv4 segmentation offload. 215 @constant kIONetworkFeatureTSOIPv6 Set this bit to advertise support 216 for TCP/IPv6 segmentation offload. 217 @constant kIONetworkFeatureTransmitCompletionStatus Set this bit to 218 advertise the capability to report per-packet transmit completion status. 219 See <code>IONetworkInterface::reportTransmitCompletionStatus</code>. 220*/ 221 222enum { 223 kIONetworkFeatureNoBSDWait = 0x01, 224 kIONetworkFeatureHardwareVlan = 0x02, 225 kIONetworkFeatureSoftwareVlan = 0x04, 226 kIONetworkFeatureMultiPages = 0x08, 227 kIONetworkFeatureTSOIPv4 = 0x10, 228 kIONetworkFeatureTSOIPv6 = 0x20, 229 kIONetworkFeatureTransmitCompletionStatus = 0x40 230}; 231 232#ifdef KERNEL 233#ifdef __cplusplus 234 235#include <IOKit/IOService.h> 236#include <IOKit/IOWorkLoop.h> 237#include <IOKit/network/IONetworkInterface.h> 238#include <IOKit/network/IOKernelDebugger.h> 239 240class IOCommandGate; 241class IOOutputQueue; 242class IONetworkMedium; 243 244/*! @typedef IOPacketBufferConstraints 245 @discussion Constraint parameters, specified by a driver, 246 for the data buffer in a packet mbuf. This is observed by 247 allocatePacket() to satisfy the stated requirements. 248 @field alignStart Starting address byte alignment. 249 @field alignLength Buffer length byte alignment. */ 250 251typedef struct { 252 UInt32 alignStart; 253 UInt32 alignLength; 254 UInt32 reserved[6]; 255} IOPacketBufferConstraints; 256 257// Some frequently used alignment constants. 258// 259enum { 260 kIOPacketBufferAlign1 = 1, 261 kIOPacketBufferAlign2 = 2, 262 kIOPacketBufferAlign4 = 4, 263 kIOPacketBufferAlign8 = 8, 264 kIOPacketBufferAlign16 = 16, 265 kIOPacketBufferAlign32 = 32 266}; 267 268/*! @const gIONetworkFilterGroup 269 @discussion gIONetworkFilterGroup is an OSSymbol object that contains 270 the name of the standard network filter group as defined by 271 kIONetworkFilterGroup. */ 272 273extern const OSSymbol * gIONetworkFilterGroup; 274 275/*! @class IONetworkController 276 @abstract Implements the framework for a generic 277 network controller. 278 @discussion A subclass of IONetworkController must provide 279 additional functionality specific for a particular networking type. 280 In addition, the driver must implement (override) a basic set of 281 hardware dependent methods to create a working driver. 282 283 IONetworkController attaches itself to the data link layer (DLIL) via 284 an IONetworkInterface object. A controller object without a companion 285 interface is not accessible to the networking system. The controller 286 interacts with DLIL by calling methods defined by the interface object. 287 And conversely, DLIL will issue commands and packets to the controller 288 through the interface object. 289 290 IONetworkController will create an IOCommandGate and attach this 291 event source to an IOWorkLoop object. All commands sent from the 292 interface object are handled through the IOCommandGate object, 293 which will serialize access to the controller. Outbound packets sent 294 from the interface to the controller have no implicit serialization. 295 Drivers must implement an output function that is thread safe, or use 296 an IOOutputQueue object which will provide a serialization model. 297 298 Note: IONetworkController internally uses some private messaging constants 299 in the sys_iokit | sub_iokit_networking range defined in 300 "IONetworkControllerPrivate.h". If you create a client for your controller 301 (for example an IOUserClient), and it overrides the IOService::message 302 method, your client may receive these messages. It should ignore these 303 messages and pass them to super::message() 304 */ 305 306class IONetworkController : public IOService 307{ 308 OSDeclareAbstractStructors( IONetworkController ) 309 310private: 311 312 IOWorkLoop * _workLoop; 313 IOCommandGate * _cmdGate; 314 IOOutputQueue * _outputQueue; 315 OSSet * _clientSet; 316 OSCollectionIterator * _clientSetIter; 317 OSObject * _cmdClient; 318 UInt32 _alignStart; 319 UInt32 _alignLength; 320 UInt32 _alignPadding; 321 bool _propertiesPublished; 322 IOLock * _mediumLock; 323 IODebuggerLockState _debugLockState; 324 SInt32 _debugLockCount; 325 OSNumber * _linkStatus; 326 OSNumber * _linkSpeed; 327 const OSData * _lastLinkData; 328 const OSSymbol * _lastActiveMediumName; 329 const OSSymbol * _lastCurrentMediumName; 330 mbuf_t _freeList; 331 332 struct ExpansionData { }; 333 /*! @var reserved 334 Reserved for future use. (Internal use only) */ 335 ExpansionData * _reserved; 336 337 338 bool _broadcastEvent(UInt32 type, void * data = 0); 339 340 static void debugRxHandler(IOService * handler, 341 void * buffer, 342 UInt32 * length, 343 UInt32 timeout); 344 345 static void debugTxHandler(IOService * handler, 346 void * buffer, 347 UInt32 length); 348 349 static UInt32 debugLinkStatusHandler(IOService * handler); 350 static bool debugSetModeHandler(IOService * handler, bool active); 351 352 static IOReturn executeCommandAction(OSObject * owner, 353 void * arg0, 354 void * arg1, 355 void * arg2, 356 void * arg3); 357 358 static IOReturn handleCommand(void * target, 359 void * param0, 360 void * param1, 361 void * param2, 362 void * param3); 363 364public: 365 366/*! @function init 367 @abstract Initializes the IONetworkController object. 368 @discussion Instance variables are initialized, then super::init() 369 is called. 370 @param properties A dictionary object containing a property table 371 associated with this instance. 372 @result Returns true on success, false otherwise. 373*/ 374 375 virtual bool init(OSDictionary * properties); 376 377/*! @function start 378 @abstract Starts the network controller. 379 @discussion After the controller driver has successfully matched 380 to a provider, this method is called to start the network controller. 381 IONetworkController will allocate resources and gather controller 382 properties in its implementation. No I/O will be performed until 383 the subclass tries to attach a client object. A driver must override 384 this method, and call super::start() at the beginning of its own 385 implementation. Then check the return value to make sure that its 386 superclass was started successfully before proceeding. Tasks that 387 are usually performed by a driver's start method are: resource 388 allocation, hardware initialization, allocation of IOEventSources 389 and attaching them to a workloop, publishing a medium dictionary, 390 and finally, attaching an interface object when it is ready to 391 handle client requests. 392 @param provider The provider that the controller was matched 393 (and attached) to. 394 @result Returns true on success, false otherwise. 395*/ 396 397 virtual bool start(IOService * provider); 398 399/*! @function stop 400 @abstract Stops the network controller. 401 @discussion The counterpart of start(). The controller has been 402 instructed to stop running. The stop() method should release 403 resources and undo actions performed by the start() method. 404 Subclasses must override this method and call super::stop() 405 at the end of its implementation. 406 @param provider The provider that the controller was matched 407 (and attached) to. */ 408 409 virtual void stop(IOService * provider); 410 411/*! @function message 412 @abstract Receives messages delivered from an attached provider. 413 @discussion Handles the <code>kIOMessageDeviceSignaledWakeup</code> message 414 from a provider identifying the IONetworkController as the wakeup source. 415 @param type A type defined in <code>IOMessage.h</code>. 416 @param provider The provider from which the message originates. 417 @param argument An argument defined by the message type. 418 @result An IOReturn code defined by the message type. 419*/ 420 421 virtual IOReturn message( 422 UInt32 type, IOService * provider, void * argument ); 423 424/*! @typedef IONetworkController::Action 425 @discussion Definition of a C function that can be called 426 through executeCommand(). 427 @param target The first argument passed to action. 428 @param param0 Action parameter 0. 429 @param param1 Action parameter 1. 430 @param param2 Action parameter 2. 431 @param param3 Action parameter 3. */ 432 433 typedef IOReturn (*Action)(void * target, void * param0, 434 void * param1, 435 void * param2, 436 void * param3); 437 438/*! @function executeCommand 439 @abstract Makes a C function call through the command gate. 440 @discussion This method makes a call to a C function that will be synchronized 441 with the workloop thread, and any other threads that are called 442 with the workloop's gate closed. 443 @param client The client requesting the action. This parameter is not 444 passed to the function. 445 @param action Pointer to a C function to be executed. 446 @param target The first parameter in the action callout. 447 @param param0 Action parameter 0. 448 @param param1 Action parameter 1. 449 @param param2 Action parameter 2. 450 @param param3 Action parameter 3. 451 @result Returns the value returned by the action. 452*/ 453 454 virtual IOReturn executeCommand(OSObject * client, 455 Action action, 456 void * target, 457 void * param0 = 0, 458 void * param1 = 0, 459 void * param2 = 0, 460 void * param3 = 0); 461 462/*! @function outputPacket 463 @abstract Transmits an output packet. 464 @discussion If an IOOutputQueue was created by createOutputQueue(), 465 then this method will be called by the output queue object. 466 Otherwise, an interface object will call this method directly when 467 it receives an output packet from the data link layer. 468 469 There is no upper limit on the number of mbufs, hence the number of 470 memory fragments, in the mbuf chain provided. Drivers must be able to 471 handle cases when the mbuf count might exceed the limit supported by their 472 DMA engines, and perform coalescing to copy the various memory fragments 473 into a lesser number of fragments. This complexity can be hidden from 474 the driver when an IOMbufMemoryCursor is used, which is able to convert 475 an mbuf chain into a physical address scatter-gather list that will not 476 exceed a specified number of physically contiguous memory segments. 477 See IOMbufMemoryCursor. 478 479 The implementation in IONetworkController performs no useful action 480 and will drop all packets. A driver must override this method and 481 process the output packet provided. The implementation in the driver 482 must not block, since this may cause the network stack to be reentered 483 from an unsafe point. 484 @param mbuf_t An mbuf chain containing the output packet to be sent on 485 the network. 486 @param param A parameter provided by the caller. 487 @result Returns a return code defined by the caller. 488*/ 489 490 virtual UInt32 outputPacket(mbuf_t, void * param); 491 492/*! @function getFeatures 493 @abstract Reports generic features supported by the controller and/or 494 the driver. 495 @result This method will always return 0. Subclasses may override 496 this method and return a bit mask of all supported features. */ 497 498 virtual UInt32 getFeatures() const; 499 500/*! @function newVendorString 501 @result Returns a string describing the vendor of the network controller. 502 The caller is responsible for releasing the string object returned. */ 503 504 virtual const OSString * newVendorString() const; 505 506/*! @function newModelString 507 @result Returns a string describing the model of the network controller. 508 The caller is responsible for releasing the string object returned. */ 509 510 virtual const OSString * newModelString() const; 511 512/*! @function newRevisionString 513 @result Returns a string describing the hardware revision of the 514 network controller. The caller is responsible for releasing the 515 string object returned. */ 516 517 virtual const OSString * newRevisionString() const; 518 519/*! @function getSelectedMedium 520 @abstract Gets the current selected medium. 521 @discussion If the driver has previously called setSelectedMedium() 522 to indicate its current media selection, then this method will return 523 that medium object. Otherwise, the driver's property table is 524 consulted and a default medium property is examined, and the 525 corresponding entry in the medium dictionary is returned. 526 @result Returns the current selected medium, the default medium, or 0. 527*/ 528 529 virtual const IONetworkMedium * getSelectedMedium() const; 530 const IONetworkMedium * getCurrentMedium() const; 531 532/*! @function getMediumDictionary 533 @abstract Returns the medium dictionary published by the driver. 534 @discussion Returns the medium dictionary published by the driver 535 through publishMediumDictionary(). Use copyMediumDictionary() to 536 create and get a copy of the medium dictionary. 537 @result Returns the published medium dictionary, or 0 if the driver has not 538 yet published a medium dictionary through publishMediumDictionary(). 539*/ 540 541 virtual const OSDictionary * getMediumDictionary() const; 542 543/*! @function copyMediumDictionary 544 @abstract Returns a copy of the medium dictionary published by the 545 driver. 546 @discussion The caller is responsible for releasing the dictionary 547 object returned. Use getMediumDictionary() to get a reference to the 548 published medium dictionary instead of creating a copy. 549 @result Returns a copy of the medium dictionary, or 0 if the driver has not 550 published a medium dictionary through publishMediumDictionary(). 551*/ 552 553 virtual OSDictionary * copyMediumDictionary() const; 554 555/*! @function getOutputHandler 556 @abstract Gets the address of the method designated to handle output 557 packets for the network controller. 558 @result Returns a pointer to the outputPacket() method. 559*/ 560 561 virtual IOOutputAction getOutputHandler() const; 562 563/*! @function doEnable 564 @abstract Makes a synchronized call to enable() through executeCommand(). 565 @discussion Do not use this method, it may be removed in the future. 566 See enable(). 567*/ 568 569 virtual IOReturn doEnable(IOService * client); 570 571/*! @function doDisable 572 @abstract Makes a synchronized call to disable() through executeCommand(). 573 @discussion Do not use this method, it may be removed in the future. 574 See disable(). 575*/ 576 577 virtual IOReturn doDisable(IOService * client); 578 579/*! @function getCommandGate 580 @abstract Gets the IOCommandGate object created by IONetworkController. 581 @discussion When IONetworkController is started, an IOCommandGate object 582 is instantiated and attached to the workloop returned by getWorkLoop(). 583 This IOCommandGate object is used internally to synchronize client 584 commands handled through executeCommand(). Subclasses that need an 585 IOCommandGate should try to reuse the object returned by this method, 586 rather than creating a new instance. See IOCommandGate documentation. 587 @result Returns the IOCommandGate object created by IONetworkController. 588*/ 589 590 virtual IOCommandGate * getCommandGate() const; 591 592/*! @function getHardwareAddress 593 @abstract Gets the network controller's permanent hardware/station 594 address. 595 @discussion This method call is synchronized by the workloop's gate. 596 @param addr The buffer where the controller's hardware address should 597 be stored. 598 @param inOutAddrBytes The size of the address buffer provided by the 599 client, and replaced by this method with the actual size of 600 the hardware address in bytes. 601 @result Returns kIOReturnSuccess on success, or an error otherwise. 602*/ 603 604 virtual IOReturn getHardwareAddress(void * addr, 605 UInt32 * inOutAddrBytes) = 0; 606 607/*! @function setHardwareAddress 608 @abstract Sets or changes the station address used by the network 609 controller. 610 @discussion This method call is synchronized by the workloop's gate. 611 @param addr The buffer containing the hardware address provided by 612 the client. 613 @param addrBytes The size of the address buffer provided by the 614 client in bytes. 615 @result Returns kIOReturnSuccess on success, or an error otherwise. 616*/ 617 618 virtual IOReturn setHardwareAddress(const void * addr, 619 UInt32 addrBytes) = 0; 620 621/*! @function enable 622 @abstract Handles an enable request from a client. 623 @discussion This method handles an enable request from a client. A client will call 624 enable after it has opened the controller, and before it starts to use 625 the controller to send and to receive packets over the network. The 626 client object provided is typecasted using OSDynamicCast, and depending 627 on whether the client is an IOKernelDebugger or an IONetworkInterface, 628 then an overloaded enable method that takes a more specific argument 629 type is called. If the client matches neither type, then 630 kIOReturnBadArgument is returned. A driver has the option of overriding 631 this base enable method, or the overloaded form. This method call is 632 synchronized by the workloop's gate. 633 @param client The client object requesting the enable. 634 @result Returns the return value from the overloaded enable() method, or 635 kIOReturnBadArgument if the client type is unknown. 636*/ 637 638 virtual IOReturn enable(IOService * client); 639 640/*! @function disable 641 @abstract Handles a disable request from a client. 642 @discussion This method handles a disable request from a client. A client will call 643 disable if it has previously enabled the controller, and it no longer 644 needs to transport packets or perform I/O using the controller. 645 The client object is typecasted using OSDynamicCast, and depending on 646 whether the client is an IOKernelDebugger or an IONetworkInterface, 647 then an overloaded disable method that takes a more specific argument 648 type is called. If the client matches neither type, then 649 kIOReturnBadArgument is returned. A driver has the option of overriding 650 this base disable method, or the overloaded form. This method call is 651 synchronized by the workloop's gate. 652 @param client The client object requesting the disable. 653 @result Returns the return from the overloaded disable() method, or 654 kIOReturnBadArgument if the client type is unknown. 655*/ 656 657 virtual IOReturn disable(IOService * client); 658 659/*! @function setMaxPacketSize 660 @abstract A client request to change the maximum packet size. 661 @discussion This method call is synchronized by the workloop's gate. 662 @param maxSize The new maximum packet size. 663 @result Returns kIOReturnUnsupported. Drivers may override this method 664 and return either kIOReturnSuccess to indicate that the new size 665 was accepted and is in effect, or an error code to indicate failure. 666*/ 667 668 virtual IOReturn setMaxPacketSize(UInt32 maxSize); 669 670/*! @function getMaxPacketSize 671 @abstract Gets the maximum packet size supported by the controller. 672 @param maxSize Pointer to the return value. 673 @result Returns kIOReturnSuccess on success, or an error code otherwise. 674*/ 675 676 virtual IOReturn getMaxPacketSize(UInt32 * maxSize) const = 0; 677 678/*! @function getMinPacketSize 679 @abstract Gets the minimum packet size supported by the controller. 680 @param minSize Pointer to the return value. 681 @result Returns kIOReturnSuccess on success, or an error code otherwise. 682*/ 683 684 virtual IOReturn getMinPacketSize(UInt32 * minSize) const = 0; 685 686/*! @function selectMedium 687 @abstract A client request to change the medium selection. 688 @discussion This method is called when a client issues a command 689 for the controller to change its current medium selection. 690 The implementation must call setSelectedMedium() after the change 691 has occurred. This method call is synchronized by the workloop's 692 gate. 693 @param medium An entry from the published medium dictionary that 694 represents the selection chosen by the client. 695 @result Returns kIOReturnUnsupported. Drivers may override this method and 696 return kIOReturnSuccess if the selection was successful, 697 or an error code otherwise. 698*/ 699 700 virtual IOReturn selectMedium(const IONetworkMedium * medium); 701 702/*! @function selectMediumWithName 703 @abstract A client request to change the medium selection. 704 @discussion This method is called when a client issues a command 705 for the controller to change its current medium selection. 706 This implementation will look for an entry in the medium 707 dictionary published by the driver that is associated with the 708 key given. If a match is found, then selectMedium() is called to 709 perform the selection, otherwise an error is reported back to the 710 client. Subclasses should override selectMedium() and not this 711 method. This method call is synchronized by the workloop's gate. 712 @param mediumName An OSSymbol object that describes the name of the 713 new medium selected by the client. 714 @result Returns the return from selectMedium() if a matching entry was found 715 from the medium dictionary. Returns kIOReturnUnsupported if a medium 716 dictionary does not exist, or kIOReturnBadArgument if the name given 717 does not match any entry in the medium dictionary. 718*/ 719 720 virtual IOReturn selectMediumWithName(const OSSymbol * mediumName); 721 722/*! @function getPacketFilters 723 @abstract Gets the set of packet filters supported by the network 724 controller for the given filter group. 725 @discussion A subclass must implement this method and report the 726 set of filters that are supported for the given filter group. 727 This method call is synchronized by the workloop's gate. 728 @param group The name of the filter group. 729 @param filters Pointer to the mask of supported filters returned by 730 this method. 731 @result Returns kIOReturnSuccess on success, or an error to indicate a 732 failure to discover the set of supported filters. 733*/ 734 735 virtual IOReturn getPacketFilters(const OSSymbol * group, 736 UInt32 * filters) const = 0; 737 738/*! @function enablePacketFilter 739 @abstract Enables one of the supported packet filters from the 740 given filter group. 741 @discussion A client will call this method to enable a supported filter 742 from the filter group specified. If the client wishes to enable more 743 than one filter, it must call this method multiple times to enable the 744 desired set of filters. This method call is synchronized by the 745 workloop's gate. 746 @param group The name of the filter group containing the filter to be 747 enabled. 748 @param aFilter The filter to enable. 749 @param enabledFilters All filters currently enabled by the client. 750 @param options Optional flags for the enable request. 751 @result Returns kIOReturnSuccess on success, or an error otherwise. 752*/ 753 754 virtual IOReturn enablePacketFilter(const OSSymbol * group, 755 UInt32 aFilter, 756 UInt32 enabledFilters, 757 IOOptionBits options = 0) = 0; 758 759/*! @function disablePacketFilter 760 @abstract Disables a packet filter that is currently enabled from the 761 given filter group. 762 @discussion After a supported filter has been successfully enabled, 763 a client can call this method to disable that filter. This method call 764 is synchronized by the workloop's gate. 765 @param group The name of the filter group containing the filter to be 766 disabled. 767 @param aFilter The filter to disable. 768 @param enabledFilters All filters currently enabled by the client. 769 @param options Optional flags for the disable request. 770 @result Returns kIOReturnSuccess on success, or an error otherwise. 771*/ 772 773 virtual IOReturn disablePacketFilter(const OSSymbol * group, 774 UInt32 aFilter, 775 UInt32 enabledFilters, 776 IOOptionBits options = 0) = 0; 777 778/*! @function getOutputQueue 779 @abstract Gets the IOOutputQueue object created by createOutputQueue(). 780 @result Returns a reference to the output queue object created by 781 createOutputQueue(). 782*/ 783 784 virtual IOOutputQueue * getOutputQueue() const; 785 786/*! @function getPacketBufferConstraints 787 @abstract Gets the controller's packet buffer constraints. 788 @discussion Called by start() to obtain the constraints on the 789 memory buffer for each mbuf packet allocated through allocatePacket(). 790 Drivers can override this method to specify the buffer constraints 791 imposed by their bus master hardware. Note that outbound packets, 792 those that originate from the network stack, are not currently 793 subject to the constraints reported here. 794 @param constraints A pointer to an IOPacketBufferConstraints 795 structure that this method is expected to initialize. 796 See IOPacketBufferConstraints structure definition. 797*/ 798 799 virtual void getPacketBufferConstraints( 800 IOPacketBufferConstraints * constraints) const; 801 802/*! @function allocatePacket 803 @abstract Allocates a packet with a data buffer that is larger than 804 or equal to the size specified. 805 @discussion This method will always return a single mbuf unless the 806 size requested (plus the alignment padding) is greater than MCLBYTES. 807 The data buffer for the mbuf (or an mbuf chain) returned is aligned 808 according to the constraints reported by getPacketBufferConstraints(). 809 The length fields in each mbuf returned are set by this method, thus 810 allowing the mbuf to be passed directly to an IOMbufMemoryCursor object 811 in order to convert the mbuf to a physical address scatter-gather list. 812 @param size The minimum size of the data buffer for the mbuf 813 packet allocated. 814 @result Returns an mbuf packet, or 0 if allocation failed. 815*/ 816 817 virtual mbuf_t allocatePacket(UInt32 size); 818 819/*! @function copyPacket 820 @abstract Allocates a new packet, containing data copied from an 821 existing source packet. 822 @discussion The source packet is not modified by this method. 823 @param m The source packet. 824 @param size The number of bytes to copy. If set to 0, then the 825 entire data buffer from the source packet is copied. 826 @result Returns a new packet containing the same data as the source packet. 827*/ 828 829 virtual mbuf_t copyPacket(const mbuf_t m, UInt32 size = 0); 830 831/*! @function replacePacket 832 @abstract Allocates a new packet to replace an existing packet, the 833 existing packet is then returned. 834 @param mp A handle to the existing packet. 835 @param size If size is 0, then the new packet shall have the same buffer 836 size as the original packet that is being replaced. Otherwise, the new 837 packet shall have the buffer size specified by this value. 838 @result If packet allocation was successful, then a replacement will 839 take place and the original packet will be returned. Otherwise, 0 840 is returned, and the original packet will be left untouched. 841*/ 842 843 virtual mbuf_t replacePacket(mbuf_t * mp, UInt32 size = 0); 844 845/*! @function replaceOrCopyPacket 846 @abstract A helper method that combines the functionality of 847 copyPacket() and replacePacket() to process a packet containing 848 a received frame. 849 @discussion This method will either make a copy or replace the existing 850 packet, whichever is more time efficient. Packets containing small frames 851 are copied, otherwise they are replaced. If replaced, then the existing 852 packet is returned, and a new packet with the same buffer size is created 853 to take its place. If copied, the existing packet is left intact, while a 854 copy is returned that will hold a copy of the data from the source packet. 855 @param mp A handle to the existing packet that may be replaced. 856 @param length The number of bytes received held in the packet. 857 Must be greater than zero. 858 @param replaced Pointer to a return value that is set to true to indicate 859 that the existing packet was replaced, or false to indicate that the 860 existing packet was not replaced, and a copy was created. 861 @result Returns a replacement or a copy of the existing packet, or 0 if packet 862 allocation failed. 863*/ 864 865 virtual mbuf_t replaceOrCopyPacket(mbuf_t * mp, 866 UInt32 length, 867 bool * replaced); 868 869 enum { 870 kDelayFree = 0x01 871 }; 872 873/*! @function freePacket 874 @abstract Releases the packet given back to the free pool. 875 @param mbuf_t The packet to be freed. 876 @param options When kDelayFree option is set, then the packet 877 provided to this function will be queued on the free packet queue. 878 A subsequent call to releaseFreePackets() will release all queued 879 packets by making a single BSD function call. Without the kDelayFree 880 option, the packet provided will be released immediately. 881*/ 882 883 virtual void freePacket(mbuf_t, IOOptionBits options = 0); 884 885/*! @function releaseFreePackets 886 @abstract Releases all packets held in the free packet queue. 887 @discussion The free packet queue is not protected by a lock. This 888 function must be called in a single-threaded manner with respect to 889 all calls to freePacket() with the kDelayFree option set. 890 @result Returns the number of packets queued and released. 891*/ 892 893 virtual UInt32 releaseFreePackets(); 894 895/*! @enum TCP/IP Checksums 896 @abstract TCP/IP checksums that may be supported by the 897 hardware. 898 @constant kChecksumFamilyTCPIP A value that describes the collection 899 of TCP/IP checksums. 900 @constant kChecksumIP An IP header checksum. 901 @constant kChecksumTCP A TCP checksum that covers the TCP header and TCP 902 data. 903 @constant kChecksumUDP A UDP checksum that covers the UDP header and UDP 904 data. 905 @constant kChecksumTCPIPv6 A TCP checksum that covers the IPv6 pseudo header, 906 TCP header and TCP data. 907 @constant kChecksumUDPIPv6 A UDP checksum that covers the IPv6 pseudo header, 908 UDP header and UDP data. 909 @constant kChecksumTCPNoPseudoHeader A TCP checksum that covers the TCP 910 header and the TCP data, but the pseudo header is not included in the 911 checksum computation. A partial 16-bit checksum value must be provided 912 to allow the protocol stacks to calculate and verify the final checksum. 913 This type of checksum is not currently supported on the output path. 914 @constant kChecksumUDPNoPseudoHeader A UDP checksum that covers the UDP 915 header and the UDP data, but the pseudo header is not included in the 916 checksum computation. A partial 16-bit checksum value must be provided 917 to allow the protocol stacks to calculate and verify the final checksum. 918 This type of checksum is not currently supported on the output path. 919 @constant kChecksumTCPSum16 The hardware has a simple checksum engine 920 that can perform a TCP style ones complement sum of 16-bit words over 921 a certain range of bytes in a packet. The hardware does not have the 922 ability to scan for IP or TCP headers, and the driver must pass/get 923 additional parameter(s) to or from the protocol stack to coordinate 924 the checksumming effort. 925*/ 926 927 enum { 928 kChecksumFamilyTCPIP = 0x00000001, 929 kChecksumIP = 0x0001, 930 kChecksumTCP = 0x0002, 931 kChecksumUDP = 0x0004, 932 kChecksumTCPIPv6 = 0x0020, 933 kChecksumUDPIPv6 = 0x0040, 934 kChecksumTCPNoPseudoHeader = 0x0100, 935 kChecksumUDPNoPseudoHeader = 0x0200, 936 kChecksumTCPSum16 = 0x1000 937 }; 938 939/*! @function getChecksumSupport 940 @abstract Gets checksums that are supported by the network controller for 941 the given checksum family. 942 @discussion A network controller that is capable of inserting and verifying 943 checksums on output and input packets, should override this method and 944 advertise its capability in order to assist or offload the software checksum 945 calculations performed by the protocol stacks. 946 @param checksumMask A pointer to the mask of supported checksums returned 947 by this method. 948 @param checksumFamily A value that specifies the checksum family. 949 @param isOutput Set to true to query the support for checksum insertion on 950 output packets, or false to query the support for checksum verification 951 on input packets. Controllers that have symmetric hardware checksum support 952 can return a fixed checksum mask value, and ignore this argument. 953 @result Default return is kIOReturnUnsupported. Controllers that override 954 this method must return kIOReturnSuccess. Any other return value will be 955 interpretated as a lack of checksum support, regardless of the value 956 returned through the first argument. 957*/ 958 959 virtual IOReturn getChecksumSupport( UInt32 * checksumMask, 960 UInt32 checksumFamily, 961 bool isOutput ); 962 963/*! @function setChecksumResult 964 @abstract Encodes a received packet with the checksum result reported 965 by the hardware. 966 @discussion A network controller that can verify the checksum(s) for a 967 received packet, should call this method to encode the result on the 968 packet, before passing it up towards the protocol stacks. 969 @param packet An mbuf containing a packet that has been checksummed by 970 the hardware. 971 @param checksumFamily A value that specifies the checksum family. 972 @param resultMask A mask of all checksums that were checked or computed. 973 Setting a bit implies that the driver is able to report the result of 974 the checksum computation, by asserting the validity of the checksum, 975 or by returning a partial checksum value. 976 @param validMask A mask of all checksums are were computed and verified 977 by the hardware as valid. Certain types of checksum performed by the 978 hardware are inheritely incomplete, and therefore should never be marked 979 as valid. A checksum cannot be marked valid unless it has also been 980 checked. 981 @param param0 Optional parameter 0, defaults to 0. 982 @param param1 Optional parameter 1, defaults to 0. 983 @result Returns true if the checksum family is valid and the packet has been 984 encoded with the checksum result provided, false otherwise. 985*/ 986 987 virtual bool setChecksumResult( mbuf_t packet, 988 UInt32 checksumFamily, 989 UInt32 resultMask, 990 UInt32 validMask, 991 UInt32 param0 = 0, 992 UInt32 param1 = 0 ); 993 994/*! @function getChecksumDemand 995 @abstract Fetches the demand for hardware checksum computation and insertion 996 for the given packet before it is transmitted on the network. 997 @discussion A network controller that can insert a checksum for output 998 packets must call this method to obtain the set of checksums that it must 999 compute, and insert into the appropriate fields in the given output packet. 1000 @param packet An mbuf containing a packet that may be missing one or more 1001 checksums in the specified checksum family. 1002 @param checksumFamily A value that specifies the checksum family. 1003 @param demandMask A mask of all checksums that the hardware must compute 1004 and insert into the appropriate checksum fields in the packet. 1005 @param param0 Optional parameter 0, defaults to 0. 1006 @param param1 Optional parameter 1, defaults to 0. 1007*/ 1008 1009 virtual void getChecksumDemand( const mbuf_t packet, 1010 UInt32 checksumFamily, 1011 UInt32 * demandMask, 1012 void * param0 = 0, 1013 void * param1 = 0 ); 1014 1015/*! @function publishMediumDictionary 1016 @abstract Publishes a dictionary of IONetworkMedium objects to 1017 advertise the media selection supported by the network controller. 1018 @discussion Called by drivers to publish their medium dictionary. 1019 Each entry in the dictionary is an IONetworkMedium object that 1020 represents a single medium that is supported by the controller. 1021 This method will make a copy of the dictionary provided, then add 1022 the copy to the driver's property table. The dictionary provided 1023 can be released by the caller upon returning from this method. 1024 It is permissible to call this method multiple times, which may be 1025 necessary if the hardware's media capability changes dynamically. 1026 However, if the capability is static, which is often the case, 1027 then a driver will typically call this method only once from 1028 its start() method. 1029 1030 Several methods depend on the presence of a medium dictionary. 1031 They should be called after the medium dictionary has been 1032 published. Those methods are: 1033 setSelectedMedium() 1034 getSelectedMedium() 1035 getMediumDictionary() 1036 copyMediumDictionary() 1037 1038 @param mediumDict A dictionary of IONetworkMedium objects. 1039 @result Returns true if the dictionary is valid, and was successfully 1040 exported to the property table, false otherwise. 1041*/ 1042 1043 virtual bool publishMediumDictionary(const OSDictionary * mediumDict); 1044 1045/*! @function setSelectedMedium 1046 @abstract Designates an entry in the published medium dictionary as 1047 the current selected medium. 1048 @discussion After the driver has configured the hardware to select 1049 one of its supported media types, it must call this method to inform 1050 its parent about the change that has occurred. IONetworkController 1051 will update a property in the registry to reflect the current selection. 1052 @param medium A medium object representing the current selection. 1053 @result Returns true if the property table update was successful, 1054 false if the update failed, or if the medium provided does not match 1055 any entry from the published medium dictionary. 1056*/ 1057 1058 virtual bool setSelectedMedium(const IONetworkMedium * medium); 1059 bool setCurrentMedium(const IONetworkMedium * medium); 1060 1061/*! @function setLinkStatus 1062 @abstract Reports the link status and the active medium. 1063 @discussion Drivers must call this method when a link change is 1064 detected. IONetworkController will update the link status properties 1065 in the registry, and generate an event to inform the upper layers 1066 about the change. 1067 @param status Link status bits. 1068 See IONetworkMedium for the definition of the link status bits. 1069 @param activeMedium An object in the published medium dictionary 1070 that represents the active medium. This may not be the same as 1071 the selected medium. Set this to 0 if the link is inactive. 1072 @param speed Link speed in units of bits per second. If zero, then 1073 the link speed is taken from the medium object provided. 1074 @param data An OSData containing any additional link parameter that 1075 the driver wishes to publish to the registry. 1076 @result Returns true if all link properties were successfully updated, 1077 false otherwise. 1078*/ 1079 1080 virtual bool setLinkStatus( 1081 UInt32 status, 1082 const IONetworkMedium * activeMedium = 0, 1083 UInt64 speed = 0, 1084 OSData * data = 0); 1085 1086/*! @function systemWillShutdown 1087 @abstract Handles system shutdown and restart notifications. 1088 @discussion Overrides <code>IOService::systemWillShutdown</code> in order 1089 to notify network clients that the power-managed controller should be disabled. 1090 As a result, drivers can expect their <code>disable</code> method to be called 1091 before system shutdown or restart. This implementation is synchronous and can 1092 block before calling <code>IOService::systemWillShutdown</code> and return. 1093 @param specifier 1094 <code>kIOMessageSystemWillPowerOff</code> or <code>kIOMessageSystemWillRestart</code>. 1095 @see //apple_ref/cpp/instm/IOService/systemWillShutdown/void/(IOOptionBits) IOService::systemWillShutdown 1096*/ 1097 1098 virtual void systemWillShutdown( IOOptionBits specifier ); 1099 1100 /* Override IOService::setAggressiveness() */ 1101 1102 virtual IOReturn setAggressiveness( 1103 unsigned long type, unsigned long newLevel ); 1104 1105protected: 1106 1107/*! @function free 1108 @abstract Frees the IONetworkController object. 1109 @discussion Frees the IONetworkController object by releasing all 1110 allocated resources, followed by a call to super::free(). 1111*/ 1112 1113 virtual void free(); 1114 1115/*! @function registerWithPolicyMaker 1116 @abstract Implemented by controller drivers to register with 1117 the power management policy-maker. 1118 @discussion Drivers that are able to power manage their hardware 1119 should override this method and register with the policy-maker 1120 provided by calling IOService::registerPowerDriver(). 1121 IONetworkController will call this method before the initial 1122 attempt is made to attach a client. 1123 @param policyMaker The policy-maker chosen to manage power for 1124 this network controller. 1125 @result Returns kIOReturnSuccess on success, kIOReturnUnsupported if the 1126 driver does not support power management, or an appropriate error 1127 return code. The default return is kIOReturnUnsupported. */ 1128 1129 virtual IOReturn registerWithPolicyMaker(IOService * policyMaker); 1130 1131/*! @function createWorkLoop 1132 @abstract Method called by IONetworkController prior to the initial 1133 getWorkLoop() call. 1134 @discussion Before IONetworkController calls getWorkLoop() in its 1135 start() method, it will call createWorkLoop() to make sure that a 1136 subclass that wants to create a workloop, will do so before its 1137 first use. 1138 @result Returns true to indicate success, false otherwise. Returning false 1139 will fail IONetworkController::start(). 1140*/ 1141 1142 virtual bool createWorkLoop(); 1143 1144/*! @function prepare 1145 @abstract Prepares the controller before an IOService is created and 1146 attached as a client. 1147 @discussion This method is called by attachInterface() or 1148 attachDebuggerClient() to prepare the controller before the new client 1149 object is attached. This method will call publishProperties() to publish 1150 controller capabilities and properties that may be used by client objects. 1151 However, publishProperties() will be called only once, even if prepare() 1152 is called multiple times. This method call is synchronized by the 1153 workloop's gate. 1154 @result Returns kIOReturnSuccess on success, or an error code otherwise. 1155 Returning an error will fail the client attach. 1156*/ 1157 1158 virtual IOReturn prepare(); 1159 1160/*! @function publishProperties 1161 @abstract Publishes controller properties and capabilities. 1162 @discussion Called by IONetworkController to discover controller 1163 properties, and publish them to the property table in the I/O Kit 1164 Registry. This method is called once by prepare(). 1165 @result Returns true if all properties were discovered and published 1166 successfully, false otherwise. Returning false will prevent client 1167 objects from attaching to the controller, since a property that 1168 a client relies upon may be missing. */ 1169 1170 virtual bool publishProperties(); 1171 1172/*! @function getCommandClient 1173 @abstract Gets the command client object. 1174 @discussion Methods called on the workloop context to service a 1175 client request can call this method to get the client object that 1176 initiated the command. 1177 @result Returns the command client. If the caller is not running on the 1178 workloop thread, or if the thread does not have the workloop's gate 1179 closed, then 0 is returned. 1180*/ 1181 1182 virtual OSObject * getCommandClient() const; 1183 1184/*! @function handleOpen 1185 @abstract Handles a client open. 1186 @discussion This method handles a client open on the controller object. IOService 1187 calls this method with the arbitration lock held. Subclasses 1188 should not override this method. 1189 @param client The client that is attempting to open the controller. 1190 @param options Not used. See IOService. 1191 @param argument Not used. See IOService. 1192 @result Returns true to accept the client open, false to refuse it. 1193*/ 1194 1195 virtual bool handleOpen(IOService * client, 1196 IOOptionBits options, 1197 void * argument); 1198 1199/*! @function handleClose 1200 @abstract Handles a client close. 1201 @discussion This method handles a close from one of the client objects. IOService 1202 calls this method with the arbitration lock held. Subclasses 1203 should not override this method. 1204 @param client The client that is closing the controller. 1205 @param options Not used. See IOService. 1206*/ 1207 1208 virtual void handleClose(IOService * client, IOOptionBits options); 1209 1210/*! @function handleIsOpen 1211 @abstract Queries whether a client has an open on the controller. 1212 @discussion This method is always called by IOService with the 1213 arbitration lock held. Subclasses should not override this method. 1214 @result Returns true if the specified client, or any client if none (0) is 1215 specified, presently has an open on this object. 1216*/ 1217 1218 virtual bool handleIsOpen(const IOService * client) const; 1219 1220/*! @function enable 1221 @abstract A request from an interface client to enable the controller. 1222 @discussion This method is called by an interface client to enable the controller. 1223 Upon receiving this command, the controller driver must bring up the 1224 hardware and become ready to transmit and receive packets. A driver 1225 should also delay the allocation of most runtime resources until this 1226 method is called in order to conserve system resources. This method call 1227 is synchronized by the workloop's gate. 1228 @param interface The interface client object that requested the enable. 1229 @result Returns kIOReturnUnsupported. Drivers that override this method must 1230 return kIOReturnSuccess on success, or an error code otherwise. 1231*/ 1232 1233 virtual IOReturn enable(IONetworkInterface * interface); 1234 1235/*! @function disable 1236 @abstract A request from an interface client to disable the controller. 1237 @discussion This method is called by an interface client to disable the controller. 1238 This method should stop the hardware and disable hardware interrupt 1239 sources. Any resources allocated by enable() should also be deallocated. 1240 This method call is synchronized by the workloop's gate. 1241 @param interface The interface object that requested the disable. 1242 @result kIOReturnUnsupported. Drivers that override this method must 1243 return Returns kIOReturnSuccess on success, or an error code otherwise. 1244*/ 1245 1246 virtual IOReturn disable(IONetworkInterface * interface); 1247 1248/*! @function attachInterface 1249 @abstract Attaches a new network interface client object. 1250 @discussion This method creates a new network interface object and attaches 1251 it as a client of the controller. The <code>createInterface()</code> method 1252 is used to allocate and to initialize the interface, followed by a call to 1253 <code>configureInterface()</code> to configure the interface. Subclasses 1254 may override those two methods to customize the new interface object. 1255 Before this method returns, <code>registerService()</code> is called on the 1256 interface to start matching, which will ultimately attach the interface 1257 to the networking stack. 1258 Drivers will typically call this method from their <code>start()</code> 1259 method after they are ready to process interface requests. This has the 1260 desirable effect of preventing the <code>busyState</code> at the IOService 1261 root from becoming zero before the interface object has completed matching, 1262 which then holds off the user process that is waiting for I/O Kit to become 1263 quiet before assigning BSD names to all interfaces. Drivers that are unable 1264 to trigger interface matching synchronously from their <code>start()</code> 1265 method should instead call <code>adjustBusy</code> to manually increment 1266 the <code>busyState</code>, then followed by a <code>busyState</code> 1267 decrement after attaching and registering the interface, or after a 1268 reasonable timeout. 1269 @param interface Upon success (return value is <code>true</code>), the 1270 pointer to the interface object will be written to the argument provided. 1271 @param doRegister If true, start interface matching before returning. 1272 Drivers can pass <code>false</code> to postpone interface matching, then 1273 register the interface when ready. 1274 @result Returns <code>true</code> on success, <code>false</code> otherwise. 1275*/ 1276 1277 virtual bool attachInterface(IONetworkInterface ** interface, 1278 bool doRegister = true); 1279 1280/*! @function detachInterface 1281 @abstract Detaches an interface client object. 1282 @discussion This method will verify that the object provided is indeed 1283 an IONetworkInterface instance, and then call its terminate() method. 1284 Note that an interface object will close and detach from its 1285 controller after the data link layer has removed all references to 1286 all data structures exposed by the interface. The interface object 1287 should be released following this call. 1288 @param interface An interface object to be detached and terminated. 1289 @param sync If true, the interface is terminated synchronously. 1290 This may cause this method to block for an indeterminate 1291 amount of time. */ 1292 1293 virtual void detachInterface(IONetworkInterface * interface, 1294 bool sync = false); 1295 1296/*! @function createInterface 1297 @abstract Creates a new network interface object. 1298 @discussion This method is called by attachInterface() to perform 1299 allocation and initialization of a new interface object. A subclass of 1300 IONetworkController must implement this method and return a matching 1301 interface object. For example, IOEthernetController's implementation 1302 will return an IOEthernetInterface object when createInterface() is 1303 called. 1304 @result Returns a newly allocated and initialized interface object. 1305*/ 1306 1307 virtual IONetworkInterface * createInterface() = 0; 1308 1309/*! @function configureInterface 1310 @abstract Configures a newly created network interface object. 1311 @discussion This method configures an interface object that was created by 1312 createInterface(). Subclasses can override this method to customize 1313 and examine the interface object that will be attached to the 1314 controller as a client. 1315 @param interface The interface object to be configured. 1316 @result Returns true if the operation was successful, false otherwise 1317 (this will cause attachInterface() to fail and return 0). 1318*/ 1319 1320 virtual bool configureInterface(IONetworkInterface * interface); 1321 1322/*! @function createOutputQueue 1323 @abstract Creates an IOOutputQueue to handle output packet queueing, 1324 and also to resolve contention for the controller's transmitter from 1325 multiple client threads. 1326 @discussion This method is called by start() to create an IOOutputQueue object to 1327 handle output packet queueing. The default implementation will always 1328 return 0, hence no output queue will be created. A driver may override 1329 this method and return a subclass of IOOutputQueue. IONetworkController 1330 will keep a reference to the queue created, and will release this 1331 object when IONetworkController is freed. Also see getOutputQueue(). 1332 @result Returns a newly allocated and initialized IOOutputQueue object. 1333*/ 1334 1335 virtual IOOutputQueue * createOutputQueue(); 1336 1337/*! @function enable 1338 @abstract An enable request from an IOKernelDebugger client. 1339 @discussion Drivers that provide debugging support may either override 1340 this method and set up the hardware to support the polled-mode send and 1341 receive methods, receivePacket() and sendPacket(), or override the base 1342 enable() and disable() methods that take an IOService argument. 1343 @param debugger The IOKernelDebugger client requesting the enable. 1344 @result Returns kIOReturnSuccess. Drivers must return kIOReturnSuccess 1345 on success, or an error otherwise. 1346*/ 1347 1348 virtual IOReturn enable(IOKernelDebugger * debugger); 1349 1350/*! @function disable 1351 @abstract A disable request from an IOKernelDebugger client. 1352 @discussion Drivers that provide debugging support may either override 1353 this method to disable support for the polled-mode send and receive 1354 methods, or override the base enable() and disable() methods that 1355 take an IOService argument. 1356 @param debugger The IOKernelDebugger client requesting the disable. 1357 @result Returns kIOReturnSuccess. Drivers must return kIOReturnSuccess 1358 on success, or an error otherwise. 1359*/ 1360 1361 virtual IOReturn disable(IOKernelDebugger * debugger); 1362 1363/*! @function attachDebuggerClient 1364 @abstract Attaches a new IOKernelDebugger client object. 1365 @discussion This method allocates an IOKernelDebugger object and attaches it as 1366 a client. Having a debugger client implies that the controller 1367 supports kernel debugging, and therefore must implement the two 1368 polled-mode methods that are called by the debugger client. See 1369 sendPacket() and receivePacket(). Only a single debugger client 1370 should be attached to each controller. 1371 @param debuggerP A handle that will return the new 1372 IOKernelDebugger object created. 1373 @result Returns true on success, false otherwise. 1374*/ 1375 1376 virtual bool attachDebuggerClient(IOKernelDebugger ** debuggerP); 1377 1378/*! @function detachDebuggerClient 1379 @abstract Detaches an IOKernelDebugger client object. 1380 @discussion This method detaches and terminates the IOKernelDebugger client object 1381 provided. A synchronous termination is issued, and this method will 1382 return after the debugger client has been terminated. The debugger 1383 client should be released following this call. 1384 @param debugger The IOKernelDebugger object to be detached and 1385 terminated. If the argument provided is NULL or is not an 1386 IOKernelDebugger, this method will return immediately. 1387*/ 1388 1389 virtual void detachDebuggerClient(IOKernelDebugger * debugger); 1390 1391/*! @function reserveDebuggerLock 1392 @abstract Takes the global debugger lock. 1393 @discussion This method should not be used. Instead, call the 1394 lock() method provided by IOKernelDebugger. 1395*/ 1396 1397 void reserveDebuggerLock(); 1398 1399/*! @function releaseDebuggerLock 1400 @abstract Releases the global debugger lock. 1401 @discussion This method should not be used. Instead, call the 1402 unlock() method provided by IOKernelDebugger. 1403*/ 1404 1405 void releaseDebuggerLock(); 1406 1407/*! @function receivePacket 1408 @abstract Debugger polled-mode receive handler. 1409 @discussion This method must be implemented by a driver that supports 1410 kernel debugging. After a debugger client has been attached through 1411 attachDebuggerClient(), this method will be called by the debugger 1412 client to poll for an incoming packet when the kernel debugger is active. 1413 This method may be called from the primary interrupt context, and the 1414 implementation must avoid any memory allocation, and must never block. 1415 The receivePacket() method in IONetworkController is used as a placeholder, 1416 it performs no useful action, and should not be called. A driver that 1417 attaches a debugger client must override this method. 1418 @param pkt Address of a receive buffer where the received packet should 1419 be stored. This buffer has room for 1518 bytes. 1420 @param pktSize Address where the number of bytes received must be 1421 recorded. Set this to zero if no packets were received during 1422 the timeout interval. 1423 @param timeout The maximum amount of time in milliseconds to poll for 1424 a packet to arrive before this method must return. 1425*/ 1426 1427 virtual void receivePacket(void * pkt, UInt32 * pktSize, UInt32 timeout); 1428 1429/*! @function sendPacket 1430 @abstract Debugger polled-mode transmit handler. 1431 @discussion This method must be implemented by a driver that supports 1432 kernel debugging. After a debugger client has been attached through 1433 attachDebuggerClient(), this method will be called by the debugger 1434 to send an outbound packet only when the kernel debugger is active. 1435 This method may be called from the primary interrupt context, and the 1436 implementation must avoid any memory allocation, and must never block. 1437 The sendPacket() method in IONetworkController is used as a placeholder, 1438 it performs no useful action, and should not be called. A driver that 1439 attaches a debugger client must override this method. 1440 @param pkt Pointer to a transmit buffer containing the packet to be 1441 sent on the network. 1442 @param pktSize The size of the transmit buffer in bytes. 1443*/ 1444 1445 virtual void sendPacket(void * pkt, UInt32 pktSize); 1446 1447/*! @function getDebuggerLinkStatus 1448 @abstract Debugger polled-mode link status handler. 1449 @discussion This method should be implemented by a driver that wishes to support 1450 early availability kernel debugging. After a debugger client has been attached through 1451 attachDebuggerClient(), this method will be called by the debugger 1452 to poll for link status availability only when the kernel debugger is active. 1453 This method may be called from the primary interrupt context. As a result, the 1454 implementation must avoid any memory allocation, not use spinlocks, and 1455 never block. 1456 1457 The getDebuggerLinkStatus() method in IONetworkController is used as a placeholder 1458 and always reports that the link is up. A driver that attaches a debugger client 1459 should override this method. The driver should do any setup required to make 1460 sure the link is available for use. Prior to sending or receiving data, KDP will call this 1461 function repeatedly until it indicates that the link is both valid and active 1462 (kIONetworkLinkValid | kIONetworkLinkActive). 1463 1464 @result Link status bits. See IONetworkMedium for the definition of the link status bits. 1465*/ 1466 virtual UInt32 getDebuggerLinkStatus(void); 1467 1468/*! @function setDebuggerMode 1469 @abstract Set debugger mode for network drivers. 1470 @discussion This method should be implemented by a driver that wishes to be notified when 1471 entering or leaving KDP. After a debugger client has been attached through 1472 attachDebuggerClient(), this method will be called by the debugger 1473 to inform the driver that the kernel debugger is going active or inactive. 1474 This method may be called from the primary interrupt context. As a result, the 1475 implementation must avoid any memory allocation, not use spinlocks, and 1476 never block. 1477 1478 The setDebuggerMode() method in IONetworkController is used as a placeholder 1479 and doesn't do anything. If a driver wishes to perform specific actions based upon whether 1480 or not the debugger is active or not, it should override this method. For example, drivers 1481 may wish to alter power management settings or perform other chipset reconfigurations based 1482 upon the active debugger state. 1483 1484 @param active Set to true if entering KDP and false if leaving KDP. 1485 @result Returns true on success and false otherwise. 1486*/ 1487 virtual bool setDebuggerMode(bool active); 1488 1489 // Virtual function padding 1490 OSMetaClassDeclareReservedUsed( IONetworkController, 0); // getDebuggerLinkStatus 1491 OSMetaClassDeclareReservedUsed( IONetworkController, 1); // setDebuggerMode 1492 1493#ifdef __PRIVATE_SPI__ 1494public: 1495 1496/*! @function getMbufServiceClass 1497 @discussion Get the service class of an mbuf packet. 1498 @param mbuf The mbuf to get the service class of. 1499 @result The service class 1500*/ 1501 static IOMbufServiceClass getMbufServiceClass( mbuf_t mbuf ); 1502 1503/*! @function attachAuxiliaryDataToPacket 1504 @abstract Attach family or driver specific data to a mbuf packet. 1505 @discussion Memory is allocated for the auxiliary data and attached to 1506 the packet. The data provided is then copied to the allocated memory. 1507 Attaching auxiliary data to a packet which already has auxiliary data 1508 attached will fail. The existing auxiliary data must be detached from the 1509 packet and freed using <code>removeAuxiliaryDataFromPacket</code> before 1510 attaching new data. Freeing the packet will also free any memory allocated 1511 for auxiliary data. 1512 @param packet The mbuf packet to attach the auxiliary data to. The packet 1513 must point to a header mbuf with <code>MBUF_PKTHDR</code> flag set. 1514 @param data Pointer to the auxiliary data provided by the caller. 1515 This cannot be NULL. 1516 @param length The length of the auxiliary data in bytes. 1517 This must be greater than zero. 1518 @param family The interface family defined in net/kpi_interface.h. 1519 @param subFamily Reserved for future use. 1520 @result <code>kIOReturnSuccess</code> upon success, or an error code 1521 otherwise. 1522*/ 1523 static IOReturn attachAuxiliaryDataToPacket( 1524 mbuf_t packet, 1525 const void * data, 1526 IOByteCount length, 1527 uint32_t family = 0, 1528 uint32_t subFamily = 0 ); 1529 1530/*! @function removeAuxiliaryDataFromPacket 1531 @discussion Remove and free any driver auxiliary data associated with 1532 the packet. 1533 @param packet The mbuf packet to remove the auxiliary data from. 1534*/ 1535 static void removeAuxiliaryDataFromPacket( 1536 mbuf_t packet ); 1537 1538/*! @function outputStart 1539 @abstract An indication to the driver to dequeue and transmit packets 1540 waiting in the interface output queue. 1541 @discussion A driver that supports the pull output model must override this 1542 method, which will be called by a per-interface output thread when a packet 1543 is added to the interface output queue. In response, driver must verify that 1544 free transmit resources are available, then dequeue one or more packets by 1545 calling <code>IONetworkInterface::dequeueOutputPackets()</code>. Packets 1546 removed from the queue are owned by the driver, and should be immediately 1547 prepared for transmission. Additional software queueing at the driver layer 1548 to store the dequeued packets for delayed transmission is highly discouraged 1549 unless absolutely necessary. If transmit resources are exhausted, the driver 1550 should quickly return <code>kIOReturnNoResources</code> to force the output 1551 thread to retry later, otherwise the output thread will continue to call 1552 this method until the output queue is empty. When driver creates a single 1553 network interface, this method will execute in a single threaded context. 1554 However, it is the driver's responsibility to protect transmit resources 1555 that are shared with other driver threads. To simplify drivers that wish to 1556 process output packets on their work loop context, the family provides an 1557 option to force the output thread to always call this method through a 1558 <code>runAction()</code>. However this can have negative performance 1559 implications due to extra locking and serializing the output thread against 1560 other work loop events. Another option that drivers can deploy to 1561 synchronize against the output thread is to issue a thread stop before 1562 touching any shared resources. But this should be used sparingly on the 1563 data path since stopping the output thread can block. 1564 @param interface The network interface with packet(s) to transmit. 1565 @param options Always zero. 1566 @result <code>kIOReturnSuccess</code> on success, output thread will 1567 continue calling the driver until the output queue is empty. 1568 <code>kIOReturnNoResources</code> when there is a temporary driver resource 1569 shortage. 1570*/ 1571 virtual IOReturn outputStart( 1572 IONetworkInterface * interface, 1573 IOOptionBits options ); 1574 1575 OSMetaClassDeclareReservedUsed( IONetworkController, 2); 1576 1577/*! @function setInputPacketPollingEnable 1578 @abstract Informs the driver when input polling is enabled or disabled. 1579 @discussion A driver that supports input polling should override this 1580 method to handle the transition from the default push-model, where a 1581 hardware interrupt causes the driver to push input packets to the network 1582 stack, to the pull-model where a poller thread will periodically poll the 1583 driver for input packets. When polling is enabled, receive interrupt should 1584 be masked OFF. This method is always called on driver's work loop context. 1585 @param interface The interface that has enabled or disabled input polling. 1586 @param enabled <code>true</code> if input polling is enabled, 1587 <code>false</code> if input polling is disabled. 1588 @result Driver should return <code>kIOReturnSuccess</code> if the transition 1589 to/from polled-mode was successful, or an error code otherwise. 1590*/ 1591 virtual IOReturn setInputPacketPollingEnable( 1592 IONetworkInterface * interface, 1593 bool enabled ); 1594 1595 OSMetaClassDeclareReservedUsed( IONetworkController, 3); 1596 1597/*! @function pollInputPackets 1598 @abstract Called by the interface poller thread to retrieve input packets 1599 from the driver. 1600 @discussion A driver that supports input polling must override this method 1601 and pass any input packets to the network interface. For each input packet, 1602 driver must call <code>IONetworkInterface::enqueueInputPacket</code> and 1603 pass the <code>pollQueue</code> argument to add the packet to the polling 1604 queue. This should continue until the maximum packet count is reached, or 1605 the driver runs out of input packets. The poller can be configured to call 1606 this method on the driver's work loop context. 1607 @param interface The interface that is polling packets from the driver. 1608 @param maxCount The maximum number of packets that the poller can accept. 1609 @param pollQueue The polling queue that should be passed to 1610 <code>IONetworkInterface::enqueueInputPacket</code>. Do not cache or use 1611 this pointer after the method returns. 1612 @param context The family will always pass zero. This can be used by the 1613 driver for calls originating from the driver. E.g. A driver may choose to 1614 unify polled-mode and interrupt-mode input packet handling and call this 1615 method from its receive interrupt handler and pass a non-zero context to 1616 distinguish the calling context. 1617*/ 1618 virtual void pollInputPackets( 1619 IONetworkInterface * interface, 1620 uint32_t maxCount, 1621 IOMbufQueue * pollQueue, 1622 void * context ); 1623 1624 OSMetaClassDeclareReservedUsed( IONetworkController, 4); 1625 1626/*! @function networkInterfaceNotification 1627 @abstract Receives notification from an attached network interface. 1628 @discussion An attached network interface invokes this method to notify 1629 the driver about an interface state change or an event from the networking 1630 stack. The family does not synchronize the call using the driver's work 1631 loop. 1632 @param interface The interface that issued the notification. 1633 @param type The type of notification. 1634 @param argument Optional data associated with the notification. Can be 1635 NULL if the notification does not provide in-band data. 1636 @result Default implementation returns <code>kIOReturnUnsupported</code>. 1637 Driver should return <code>kIOReturnSuccess</code> if the notification 1638 was handled. 1639*/ 1640 virtual IOReturn networkInterfaceNotification( 1641 IONetworkInterface * interface, 1642 uint32_t type, 1643 void * argument ); 1644 1645 OSMetaClassDeclareReservedUsed( IONetworkController, 5); 1646#else /* !__PRIVATE_SPI__ */ 1647 OSMetaClassDeclareReservedUnused( IONetworkController, 2); 1648 OSMetaClassDeclareReservedUnused( IONetworkController, 3); 1649 OSMetaClassDeclareReservedUnused( IONetworkController, 4); 1650 OSMetaClassDeclareReservedUnused( IONetworkController, 5); 1651#endif /* !__PRIVATE_SPI__ */ 1652 OSMetaClassDeclareReservedUnused( IONetworkController, 6); 1653 OSMetaClassDeclareReservedUnused( IONetworkController, 7); 1654 OSMetaClassDeclareReservedUnused( IONetworkController, 8); 1655 OSMetaClassDeclareReservedUnused( IONetworkController, 9); 1656 OSMetaClassDeclareReservedUnused( IONetworkController, 10); 1657 OSMetaClassDeclareReservedUnused( IONetworkController, 11); 1658 OSMetaClassDeclareReservedUnused( IONetworkController, 12); 1659 OSMetaClassDeclareReservedUnused( IONetworkController, 13); 1660 OSMetaClassDeclareReservedUnused( IONetworkController, 14); 1661 OSMetaClassDeclareReservedUnused( IONetworkController, 15); 1662 OSMetaClassDeclareReservedUnused( IONetworkController, 16); 1663 OSMetaClassDeclareReservedUnused( IONetworkController, 17); 1664 OSMetaClassDeclareReservedUnused( IONetworkController, 18); 1665 OSMetaClassDeclareReservedUnused( IONetworkController, 19); 1666 OSMetaClassDeclareReservedUnused( IONetworkController, 20); 1667 OSMetaClassDeclareReservedUnused( IONetworkController, 21); 1668 OSMetaClassDeclareReservedUnused( IONetworkController, 22); 1669 OSMetaClassDeclareReservedUnused( IONetworkController, 23); 1670 OSMetaClassDeclareReservedUnused( IONetworkController, 24); 1671 OSMetaClassDeclareReservedUnused( IONetworkController, 25); 1672 OSMetaClassDeclareReservedUnused( IONetworkController, 26); 1673 OSMetaClassDeclareReservedUnused( IONetworkController, 27); 1674 OSMetaClassDeclareReservedUnused( IONetworkController, 28); 1675 OSMetaClassDeclareReservedUnused( IONetworkController, 29); 1676 OSMetaClassDeclareReservedUnused( IONetworkController, 30); 1677 OSMetaClassDeclareReservedUnused( IONetworkController, 31); 1678}; 1679 1680#endif /* __cplusplus */ 1681#endif /* KERNEL */ 1682#endif /* !_IONETWORKCONTROLLER_H */ 1683