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 _IONETWORKINTERFACE_H 24#define _IONETWORKINTERFACE_H 25 26/*! @defined kIONetworkInterfaceClass 27 @abstract The name of the IONetworkInterface class. 28*/ 29 30#define kIONetworkInterfaceClass "IONetworkInterface" 31 32/*! @defined kIONetworkData 33 @abstract A property of IONetworkInterface objects. 34 @discussion The kIONetworkData property has an OSDictionary value and is a 35 container for the set of IONetworkData objects managed by the interface. 36 Each entry in the dictionary is a key/value pair consisting of 37 the network data name, and an OSDictionary describing the 38 contents of the network data. 39*/ 40 41#define kIONetworkData "IONetworkData" 42 43/*! @defined kIOInterfaceType 44 @abstract A property of IONetworkInterface objects. 45 @discussion The kIOInterfaceType property has an OSNumber value that 46 specifies the type of network interface that this interface represents. 47 The type constants are defined in bsd/net/if_types.h. 48*/ 49 50#define kIOInterfaceType "IOInterfaceType" 51 52/*! @defined kIOMaxTransferUnit 53 @abstract A property of IONetworkInterface objects. 54 @discussion The kIOMaxTransferUnit property has an OSNumber value that 55 specifies the maximum transfer unit for the interface in bytes. 56*/ 57 58#define kIOMaxTransferUnit "IOMaxTransferUnit" 59 60/*! @defined kIOMediaAddressLength 61 @abstract A property of IONetworkInterface objects. 62 @discussion The kIOMediaAddressLength property has an OSNumber value that 63 specifies the size of the media address in bytes. 64*/ 65 66#define kIOMediaAddressLength "IOMediaAddressLength" 67 68/*! @defined kIOMediaHeaderLength 69 @abstract A property of IONetworkInterface objects. 70 @discussion The kIOMediaHeaderLength property has an OSNumber value that 71 specifies the size of the media header in bytes. 72*/ 73 74#define kIOMediaHeaderLength "IOMediaHeaderLength" 75 76/*! @defined kIOInterfaceFlags 77 @abstract A property of IONetworkInterface objects. 78 @discussion The kIOInterfaceFlags property has an OSNumber value that 79 specifies the current value of the interface flags. The flag constants 80 are defined in bsd/net/if.h. 81*/ 82 83#define kIOInterfaceFlags "IOInterfaceFlags" 84 85/*! @defined kIOInterfaceExtraFlags 86 @abstract A property of IONetworkInterface objects. 87 @discussion The kIOInterfaceExtraFlags property has an OSNumber value that 88 specifies the current value of the interface eflags. The eflag constants 89 are defined in bsd/net/if.h. 90*/ 91 92#define kIOInterfaceExtraFlags "IOInterfaceExtraFlags" 93 94/*! @defined kIOInterfaceUnit 95 @abstract A property of IONetworkInterface objects. 96 @discussion The kIOInterfaceUnit property has an OSNumber value that 97 describes the unit number assigned to the interface object. 98*/ 99 100#define kIOInterfaceUnit "IOInterfaceUnit" 101 102/*! @defined kIOInterfaceState 103 @abstract A property of IONetworkInterface objects. 104 @discussion The kIOInterfaceState property has an OSNumber value that 105 describes the current state of the interface object. This property is 106 not exported to BSD via the ifnet structure. 107*/ 108 109#define kIOInterfaceState "IOInterfaceState" 110 111/*! @defined kIOInterfaceNamePrefix 112 @abstract A property of IONetworkInterface objects. 113 @discussion The kIOInterfaceNamePrefix property has an OSString value that 114 describes the string prefix for the BSD name assigned to the interface. 115*/ 116 117#define kIOInterfaceNamePrefix "IOInterfaceNamePrefix" 118 119/*! @defined kIOPrimaryInterface 120 @abstract A property of IONetworkInterface objects. 121 @discussion The kIOInterfaceNamePrefix property has an OSBoolean value that 122 describes whether the interface is the primary or the built-in network 123 interface. 124*/ 125 126#define kIOPrimaryInterface "IOPrimaryInterface" 127 128/*! @defined kIOBuiltin 129 @abstract kIOBuiltin is a property of IONetworkInterface 130 objects. It has an OSBoolean value. 131 @discussion The kIOBuiltin property describes whether the 132 interface is built-in. 133*/ 134 135#define kIOBuiltin "IOBuiltin" 136 137/*! @defined kIOLocation 138 @abstract kIOLocation is a property of IONetworkInterface 139 objects. It has an OSString value. 140 @discussion The kIOLocation property describes the physical 141 location of built-in interfaces. 142*/ 143 144#define kIOLocation "IOLocation" 145 146/*! @defined kIONetworkNoBSDAttachKey 147 @abstract kIONetworkNoBSDAttachKey is a property of IONetworkInterface 148 objects. It has an OSBoolean value. 149 @discussion Adding a property with this key and the value kOSBooleanTrue 150 before the interface is published will hold off the BSD attach. 151 When the interface is ready to attach to BSD, remove the property 152 and then re-publish the interface by calling registerService(). 153*/ 154 155#define kIONetworkNoBSDAttachKey "IONetworkNoBSDAttach" 156 157/*! @enum InterfaceObjectStates 158 @discussion Constants used to encode the state of the interface object. 159 @constant kIONetworkInterfaceRegisteredState The interface object has 160 registered with the data link layer. 161 @constant kIONetworkInterfaceOpenedState One or more clients have an 162 open on the interface object. 163 @constant kIONetworkInterfaceDisabledState The interface is temporarily 164 unable to service its clients. This will occur when the network 165 controller that is servicing the interface has entered a low power 166 state that renders it unusable. 167*/ 168 169enum { 170 kIONetworkInterfaceRegisteredState = 0x1, 171 kIONetworkInterfaceOpenedState = 0x2, 172 kIONetworkInterfaceDisabledState = 0x4 173}; 174 175#ifdef KERNEL 176#ifdef __cplusplus 177 178#include <IOKit/IOService.h> 179#include <IOKit/network/IONetworkData.h> 180#include <IOKit/network/IONetworkStats.h> 181#include <IOKit/network/IONetworkMedium.h> 182#include <net/kpi_interface.h> 183 184class IONetworkController; 185class IONetworkStack; 186class IOCommandGate; 187struct IOMbufQueue; 188 189/*! @typedef IOOutputAction 190 @discussion Prototype for an output packet handler that will process 191 all outbound packets sent to the interface from the data link layer. 192 An output handler is registered with the interface by calling 193 registerOutputHandler(). 194 @param mbuf_t A packet mbuf. 195 @param param A parameter for the output request. */ 196 197typedef UInt32 (OSObject::*IOOutputAction)(mbuf_t, void * param); 198 199/*! @typedef BPF_FUNC 200 @discussion Prototype for the BPF tap handler. This will disappear 201 when the correct DLIL header file is included. */ 202 203typedef int (*BPF_FUNC)(struct ifnet *, struct mbuf *); 204 205// Network event types recognized by inputEvent(). 206// 207enum { 208 /* DLIL defined event, argument must be a pointer to a 209 kern_event_msg structure. */ 210 kIONetworkEventTypeDLIL = 0xff000001, 211 212 /* Link up event, no argument */ 213 kIONetworkEventTypeLinkUp = 0xff000002, 214 215 /* Link down event, no argument */ 216 kIONetworkEventTypeLinkDown = 0xff000003, 217 218 /* Wake on LAN support changed, no argument */ 219 kIONetworkEventWakeOnLANSupportChanged = 0xff000004, 220 221 /* Link speed changed */ 222 kIONetworkEventTypeLinkSpeedChange = 0xff000005 223}; 224 225#ifdef __PRIVATE_SPI__ 226enum { 227 kIONetworkWorkLoopSynchronous = 0x00000001 228}; 229 230/*! @enum IOMbufServiceClass 231 @discussion Service class of a mbuf packet. 232 @constant kIOMbufServiceClassBKSYS Background System-Initiated. 233 @constant kIOMbufServiceClassBK Background. 234 @constant kIOMbufServiceClassBE Best Effort. 235 @constant kIOMbufServiceClassRD Responsive Data. 236 @constant kIOMbufServiceClassOAM Operations, Administration, and Management. 237 @constant kIOMbufServiceClassAV Multimedia Audio/Video Streaming. 238 @constant kIOMbufServiceClassRV Responsive Multimedia Audio/Video. 239 @constant kIOMbufServiceClassVI Interactive Video. 240 @constant kIOMbufServiceClassVO Interactive Voice. 241 @constant kIOMbufServiceClassCTL Network Control. 242*/ 243enum IOMbufServiceClass { 244 kIOMbufServiceClassBKSYS = 100, 245 kIOMbufServiceClassBK = 200, 246 kIOMbufServiceClassBE = 0, 247 kIOMbufServiceClassRD = 300, 248 kIOMbufServiceClassOAM = 400, 249 kIOMbufServiceClassAV = 500, 250 kIOMbufServiceClassRV = 600, 251 kIOMbufServiceClassVI = 700, 252 kIOMbufServiceClassVO = 800, 253 kIOMbufServiceClassCTL = 900 254}; 255 256/*! @enum IONetworkTransmitStatus 257 @discussion Constants for packet transmit status. 258 @constant kIONetworkTransmitStatusSuccess Packet sent across link. 259 @constant kIONetworkTransmitStatusFailed Failed to send packet across link. 260 @constant kIONetworkTransmitStatusAborted Send aborted, peer was asleep. 261 @constant kIONetworkTransmitStatusQueueFull Driver send queue was full. 262*/ 263enum { 264 kIONetworkTransmitStatusSuccess = 0, 265 kIONetworkTransmitStatusFailed = 1, 266 kIONetworkTransmitStatusAborted = 2, 267 kIONetworkTransmitStatusQueueFull = 3 268}; 269 270typedef uint32_t IONetworkTransmitStatus; 271 272/*! @typedef IONetworkPacketPollingParameters 273 @discussion Mirrors the definition of <code>ifnet_poll_params()</code>. 274 @field maxPacketCount The maximum number of packets to be dequeued each 275 time the driver's <code>pollInputPackets</code> is invoked. A zero value 276 indicates the use of default maximum defined by the system. 277 @field lowThresholdPackets Low watermark packets threshold. 278 @field highThresholdPackets High watermark packets threshold. 279 @field lowThresholdBytes Low watermark bytes threshold. 280 @field highThresholdBytes High watermark bytes threshold. 281 @field pollIntervalTime The interval time between each invocation of 282 the driver's <code>pollInputPackets</code> in nanoseconds. 283*/ 284struct IONetworkPacketPollingParameters { 285 uint32_t maxPacketCount; 286 uint32_t lowThresholdPackets; 287 uint32_t highThresholdPackets; 288 uint32_t lowThresholdBytes; 289 uint32_t highThresholdBytes; 290 uint64_t pollIntervalTime; 291 uint64_t reserved[4]; 292}; 293#endif /* __PRIVATE_SPI__ */ 294 295/*! @class IONetworkInterface 296 @abstract Abstract class that manages the connection between an 297 IONetworkController and the data link interface layer. 298 @discussion An IONetworkInterface object manages the connection between 299 an IONetworkController and the data link interface layer (DLIL). 300 All interactions between the controller and DLIL must go through an 301 interface object. Any data structures that are required by DLIL for a 302 particular interface type shall be allocated and mantained by the 303 interface object. IONetworkInterface is an abstract class that must be 304 extended by a concrete subclass to specialize for a particular network 305 type. 306 307 Although most drivers will allocate a single interface object, 308 it is possible for multiple interfaces to be attached to a single 309 controller. This controller driver will be responsible for arbitrating 310 access among its multiple interface clients. 311 312 IONetworkInterface also maintains a dictionary of IONetworkData 313 objects containing statistics structures. Controller drivers can 314 ask for a particular data object by name and update the 315 statistics counters within directly. This dictionary is added to 316 the interface's property table and is visible outside of the kernel. 317*/ 318 319class IONetworkInterface : public IOService 320{ 321 OSDeclareAbstractStructors( IONetworkInterface ) 322 323 friend class IONetworkStack; 324 325#ifdef __PRIVATE_SPI__ 326public: 327/*! @typedef OutputPreEnqueueHandler 328 @param target Reference supplied when the handler was installed. 329 @param refCon Reference supplied when the handler was installed. 330 @param packet The output packet; may be the head of a chain of packets. 331 Call <code>enqueueOutputPacket()</code> for each packet in the chain to 332 enqueue the packet before returning. The handler executes on the thread 333 context of the sending client. 334*/ 335 typedef errno_t (*OutputPreEnqueueHandler)( 336 void * target, void * refCon, mbuf_t packet ); 337 338 static IOReturn errnoToIOReturn( errno_t error ); 339#endif /* __PRIVATE_SPI__ */ 340 341private: 342 IONetworkController * _driver; 343 ifnet_t _backingIfnet; 344 IOLock * _privateLock; 345 OSSet * _clientSet; 346 OSNumber * _stateBits; 347 bpf_packet_func _inputFilterFunc; 348 bpf_packet_func _outputFilterFunc; 349 OSObject * _outTarget; 350 IOOutputAction _outAction; 351 UInt32 _clientVar[4]; 352 OSDictionary * _dataDict; 353 IOMbufQueue * _inputPushQueue; 354 void * _unused1; 355 UInt32 _unused2; 356 357 struct ExpansionData { 358 int unit; 359 int type; 360 int mtu; 361 int flags; 362 int eflags; 363 int addrlen; 364 int hdrlen; 365 int32_t loggingLevel; 366 uint32_t outputQueueModel; 367 IONetworkStats driverStats; 368 IONetworkStats lastDriverStats; 369 ifnet_stat_increment_param inputDeltas; 370 IORecursiveLock * publicLock; 371 char * remote_NMI_pattern; 372 unsigned int remote_NMI_len; 373 IONetworkController * controller; 374 uint32_t configFlags; 375 uint32_t txRingSize; 376 uint32_t txPullOptions; 377 uint32_t txQueueSize; 378 uint32_t txSchedulingModel; 379 uint32_t txThreadState; 380 volatile UInt32 txThreadFlags; 381 uint32_t txThreadSignal; 382 uint32_t txThreadSignalLast; 383 thread_t txStartThread; 384 void * txStartAction; 385 IOWorkLoop * txWorkLoop; 386 uint32_t rxRingSize; 387 uint32_t rxPollOptions; 388 uint32_t rxPollModel; 389 void * rxPollAction; 390 void * rxCtlAction; 391 uint64_t rxPollEmpty; 392 uint64_t rxPollTotal; 393#ifdef __PRIVATE_SPI__ 394 OutputPreEnqueueHandler peqHandler; 395 void * peqTarget; 396 void * peqRefcon; 397 uint32_t subType; 398#endif 399 }; 400 401 ExpansionData * _reserved; 402 403 bool _syncNetworkDataDict(); 404 SInt32 syncSIOCSIFMEDIA(IONetworkController * ctr, struct ifreq * ifr); 405 SInt32 syncSIOCGIFMEDIA(IONetworkController * ctr, struct ifreq * ifr, 406 unsigned long cmd); 407 SInt32 syncSIOCSIFMTU(IONetworkController * ctr, struct ifreq * ifr); 408 void drainOutputQueue(ifnet_t ifp, IONetworkController * driver); 409 IOReturn haltOutputThread(uint32_t stateBit); 410#ifdef __PRIVATE_SPI__ 411 void actionInputCtl(IONetworkController * driver, 412 ifnet_ctl_cmd_t cmd, uint32_t arglen, void * arg ); 413#endif 414 void pushInputQueue( IOMbufQueue * queue ); 415 void pushInputPacket( mbuf_t packet, uint32_t length ); 416 int if_start_precheck( ifnet_t ifp ); 417 static int performGatedCommand(void *, void *, void *, void *, void *); 418 static void powerChangeHandler(void *, void *, void *); 419 static errno_t if_ioctl(ifnet_t ifp, unsigned long cmd, void * data); 420 static int if_output(ifnet_t ifp, mbuf_t); 421 static errno_t if_set_bpf_tap(ifnet_t ifp, bpf_tap_mode, bpf_packet_func); 422 static void if_detach(ifnet_t ifp); 423 static void if_start(ifnet_t ifp); 424 static void if_start_gated(ifnet_t ifp); 425 static void if_input_poll(ifnet_t ifp, uint32_t flags, 426 uint32_t max_count, 427 mbuf_t * first_packet, mbuf_t * last_packet, 428 uint32_t * cnt, uint32_t * len); 429 static void if_input_poll_gated(ifnet_t ifp, uint32_t flags, 430 uint32_t max_count, 431 mbuf_t * first_packet, mbuf_t * last_packet, 432 uint32_t * cnt, uint32_t * len); 433#ifdef __PRIVATE_SPI__ 434 static errno_t if_input_ctl(ifnet_t ifp, ifnet_ctl_cmd_t cmd, 435 uint32_t arglen, void * arg); 436 static errno_t if_output_pre_enqueue(ifnet_t ifp, mbuf_t packet); 437 static errno_t if_output_ctl(ifnet_t ifp, ifnet_ctl_cmd_t cmd, 438 u_int32_t arglen, void *arg); 439#endif 440 void notifyDriver( uint32_t type, void * data ); 441 442public: 443 444/*! @function isPrimaryInterface 445 @abstract Queries whether the interface is the primary network interface 446 on the system. 447 @discussion The definition of a primary interface and its discovery is 448 platform specific. 449 @result Returns true if the interface is the primary interface, 450 false otherwise. 451*/ 452 virtual bool isPrimaryInterface( void ) const; 453 454/*! @function init 455 @abstract Initializes the <code>IONetworkInterface</code> object. 456 @discussion Resources are allocated, but an <code>ifnet_t</code> will not 457 be allocated until the interface is assigned a BSD name and attached to the 458 network stack. 459 @param controller A network controller object that will service the 460 the interface. 461 @result Returns true on success, false otherwise. 462*/ 463 virtual bool init( IONetworkController * controller ); 464 465/*! @function isRegistered 466 @abstract Queries if the interface has attached to the BSD network stack. 467 @discussion Once attached a <code>kIOBSDNameKey</code> property is added 468 to the interface object with the assigned BSD name. 469 @result Returns true if interface is registered and attached to the network 470 stack, false otherwise. 471*/ 472 virtual bool isRegistered( void ) const; 473 474/*! @function getInterfaceState 475 @abstract Reports the current state of the interface object. 476 @result Returns the current interface state flags. 477*/ 478 virtual UInt32 getInterfaceState( void ) const; 479 480/*! @function getController 481 @abstract Gets the <code>IONetworkController</code> object that created 482 this interface. 483 @discussion The controller object passed to init() will be retained until 484 the interface closes the controller. Subclasses can safely call this method 485 before the controller is closed. 486 @result Returns the parent <code>IONetworkController</code> object. 487*/ 488 virtual IONetworkController * getController( void ) const; 489 490/*! @function inputPacket 491 @abstract For drivers to submit a received packet to the network stack. 492 @discussion The packet provided to this method may be added to an input 493 queue managed by the interface object, which the driver can use to postpone 494 the packet handoff to the network stack, until all received packets have been 495 added to the input queue. A subsequent call to <code>flushInputQueue()</code>, 496 will transfer the entire contents of the input queue to the network stack. 497 This input queue is not protected by a lock. Drivers that leverage this 498 input queue must either access the queue from a single thread, or enforce 499 serialized access. 500 @param mbuf_t The mbuf containing the received packet. 501 @param length Specify the size of the received packet in the mbuf. 502 The mbuf length fields are updated with this value. If zero, then the mbuf 503 length fields are not updated. 504 @param options Pass <code>kInputOptionQueuePacket</code> to enqueue the 505 input packet. Pass zero to bypass the input queue, and immediately submit 506 the packet to the network stack. 507 @param param A parameter provided by the driver. Not used. 508 @result Returns the number of packets that were submitted to the network 509 stack, or zero if the packet was enqueued. 510*/ 511 virtual UInt32 inputPacket( 512 mbuf_t packet, 513 UInt32 length = 0, 514 IOOptionBits options = 0, 515 void * param = 0 ); 516 517/*! @enum InputOptionQueuePacket 518 @discussion Options for <code>inputPacket()</code>. 519 @constant kInputOptionQueuePacket Enqueue the input packet provided to the 520 input packet queue. Calls to <code>inputPacket()</code> must be serialized. 521*/ 522 enum { 523 kInputOptionQueuePacket = 0x1 524 }; 525 526/*! @function flushInputQueue 527 @abstract Submit all packets held in the input queue to the network stack. 528 @discussion Allow drivers to remove all packets from the input queue and 529 submit them to the network stack. This method should be used in concert 530 with the <code>inputPacket()</code> method, to flush the input queue after 531 queueing a number of received packets. 532 @result Returns the number of packets that were submitted to the network 533 stack. Returns zero if the queue was empty. 534*/ 535 virtual UInt32 flushInputQueue( void ); 536 537/*! @function clearInputQueue 538 @abstract Discards all packets in the input queue. 539 @discussion This method removes all packets from the input queue and 540 releases them back to the free mbuf pool. It is unusual for a driver to 541 call this method. 542 @result Returns the number of packets freed. 543*/ 544 virtual UInt32 clearInputQueue( void ); 545 546/*! @function inputEvent 547 @abstract Sends an event to the network stack. 548 @discussion This method can be used by the driver to send an event to the 549 network stack. 550 @param type A constant describing the event type. 551 @param data An optional data associated with the event. 552 @result Returns true if the event was delivered, false if the event type 553 specified is invalid, or if the event delivery failed. 554*/ 555 virtual bool inputEvent( UInt32 type, void * data ); 556 557/*! @function registerOutputHandler 558 @abstract Registers a target/action to handle outbound packets. 559 @discussion The interface object will forward all output packets sent from 560 the network stack to the target and action registered using this method. 561 The registration must occur before the interface is registered and opened 562 by <code>IONetworkStack</code>, otherwise the default handler will be used. 563 The default target and action is set by <code>init()</code> as the 564 controller, and the handler returned by the controller's 565 <code>getOutputHandler()</code> method. 566 @param target Object that implements the output handler. 567 @param action The function that will handle output packets. 568 @result Returns true if the target/action provided was accepted, 569 false otherwise. 570*/ 571 virtual bool registerOutputHandler( 572 OSObject * target, 573 IOOutputAction action ); 574 575/*! @function getNamePrefix 576 @abstract Returns the BSD name prefix as a C-string. 577 @discussion The BSD name for each interface object is generated by 578 concatenating the string returned by this method, along with an unit number 579 assigned by <code>IONetworkStack</code>. A concrete interface subclass must 580 implement this method and return a distinct name prefix for its instances. 581 @result Returns a pointer to a constant C-string. 582*/ 583 virtual const char * getNamePrefix() const = 0; 584 585/*! @function getInterfaceType 586 @abstract Gets the interface type. 587 @discussion This method returns the interface type previously set by 588 <code>setInterfaceType</code>. 589 @result Returns a constant defined in <code>bsd/net/if_types.h</code> 590 that describes the interface type. 591*/ 592 virtual UInt8 getInterfaceType( void ) const; 593 594/*! @function getMaxTransferUnit 595 @abstract Gets the maximum transfer unit for this interface. 596 @discussion This method calls <code>ifnet_mtu</code> and returns the 597 maximum transfer unit. 598 @result Returns the interface MTU size in bytes. 599*/ 600 virtual UInt32 getMaxTransferUnit( void ) const; 601 602/*! @function getFlags 603 @abstract Gets the current interface flags. 604 @discussion This method calls <code>ifnet_flags</code> and returns the 605 current interface flags. 606 @result Returns the interface flags. 607*/ 608 virtual UInt16 getFlags( void ) const; 609 610/*! @function getExtraFlags 611 @abstract Gets the current interface eflags. 612 @discussion This method calls <code>ifnet_eflags</code> and returns the 613 current interface eflags. 614 @result Returns the value of the interface eflags. 615*/ 616 virtual UInt32 getExtraFlags( void ) const; 617 618/*! @function getMediaAddressLength 619 @abstract Gets the size of the media (MAC-layer) address. 620 @discussion This method calls <code>ifnet_addrlen</code> and returns the 621 media address length. 622 @result Returns the size of the media address in bytes. 623*/ 624 virtual UInt8 getMediaAddressLength( void ) const; 625 626/*! @function getMediaHeaderLength 627 @abstract Gets the size of the media header. 628 @discussion This method calls <code>ifnet_hdrlen</code> and returns the 629 media header length. 630 @result Returns the size of the media header in bytes. 631*/ 632 virtual UInt8 getMediaHeaderLength( void ) const; 633 634/*! @function getUnitNumber 635 @abstract Gets the unit number assigned to this interface object. 636 @discussion This method calls <code>ifnet_unit</code> and returns the 637 unit number assigned by <code>IONetworkStack</code>. 638 @result Returns the assigned interface unit number. 639*/ 640 virtual UInt16 getUnitNumber( void ) const; 641 642/*! @function addNetworkData 643 @abstract Adds an <code>IONetworkData</code> object to the interface. 644 @discussion The <code>IONetworkData</code> object is added to a 645 collection using the key from <code>IONetworkData::getKey()<code>. 646 The object provided is retained. 647 @param aData The <code>IONetworkData</code> object. 648 @result Returns true if the object was added, false otherwise. 649*/ 650 virtual bool addNetworkData( IONetworkData * aData ); 651 652/*! @function removeNetworkData 653 @abstract Removes an <code>IONetworkData</code> object from the interface. 654 @discussion This method removes an <code>IONetworkData</code> object from 655 the collection managed by the interface. The object removed is released. 656 @param aKey An OSSymbol identifying the object to be removed. 657 @result Returns true if the object was found and removed, false otherwise. 658*/ 659 virtual bool removeNetworkData( const OSSymbol * aKey ); 660 661/*! @function removeNetworkData 662 @abstract Removes an <code>IONetworkData</code> object from the interface. 663 @discussion This method removes an <code>IONetworkData</code> object from 664 the collection managed by the interface. The object removed is released. 665 @param aKey A C-string identifying the object to be removed. 666 @result Returns true if the object was found and removed, false otherwise. 667*/ 668 virtual bool removeNetworkData( const char * aKey ); 669 670/*! @function getNetworkData 671 @abstract Gets an <code>IONetworkData</code> object from the interface. 672 @discussion Returns a reference to an <code>IONetworkData</code> object 673 that was previously added to the interface, and is associated with the 674 provided key. 675 @param aKey A C-string identifying the object. 676 @result Returns a reference to the matching <code>IONetworkData</code> 677 object, or NULL if no match was found. 678*/ 679 virtual IONetworkData * getNetworkData( const char * aKey ) const; 680 681/*! @function getNetworkData 682 @abstract Gets an <code>IONetworkData</code> object from the interface. 683 @discussion Returns a reference to an <code>IONetworkData</code> object 684 that was previously added to the interface, and is associated with the 685 provided key. 686 @param aKey An OSSymbol identifying the object. 687 @result Returns a reference to the matching <code>IONetworkData</code> 688 object, or NULL if no match was found. 689*/ 690 virtual IONetworkData * getNetworkData(const OSSymbol * aKey) const; 691 692 /* Compatibility methods */ 693 IONetworkData * getParameter(const char * aKey) const; 694 bool setExtendedFlags(UInt32 flags, UInt32 clear = 0); 695 696 /* Override IOService::message() */ 697 virtual IOReturn message( UInt32 type, IOService * provider, void * argument ); 698 699/*! @function debuggerRegistered 700 @abstract Tells the <code>IONetworkData</code> that this interface will be 701 used by the debugger. 702*/ 703 void debuggerRegistered( void ); 704 705protected: 706/*! @function setInterfaceType 707 @abstract Sets the interface type. 708 @discussion Sets the interface type before the interface is attached to 709 the network stack. See <code>bsd/net/if_types.h</code> for defined types. 710 The <code>kIOInterfaceType</code> is also updated using the provided type. 711 @param type A constant defined in <code>bsd/net/if_types.h</code> that 712 describes the interface type. 713 @result Returns true to indicate success if the interface has not yet 714 attached to the network stack, otherwise returns false. 715*/ 716 virtual bool setInterfaceType( UInt8 type ); 717 718/*! @function setMaxTransferUnit 719 @abstract Sets the maximum transfer unit for this interface. 720 @discussion Calls <code>ifnet_set_mtu</code> if the interface is attached 721 to the network stack, and updates the <code>kIOMaxTransferUnit</code> 722 property using the provided value. 723 @param mtu The interface MTU size in bytes. 724 @result Always returns true. 725*/ 726 virtual bool setMaxTransferUnit( UInt32 mtu ); 727 728/*! @function setFlags 729 @abstract Performs a read-modify-write operation on the current 730 interface flags value. 731 @discussion Calls <code>ifnet_set_flags</code> if the interface is attached 732 to the network stack, and updates the <code>kIOInterfaceFlags</code> 733 property using the provided value. See <code>bsd/net/if.h</code> header 734 file for the flag constants. 735 @param flags The bits that should be set. 736 @param clear The bits that should be cleared. If zero, then non 737 of the flags are cleared and the result is formed by OR'ing the 738 original flags value with the new flags. 739 @result Always returns true. 740*/ 741 virtual bool setFlags( UInt16 flags, UInt16 clear = 0 ); 742 743 /* Deprecated. No replacement. */ 744 virtual bool setExtraFlags( UInt32 flags, UInt32 clear = 0 ); 745 746/*! @function setMediaAddressLength 747 @abstract Sets the size of the media (MAC-layer) address. 748 @discussion Calls <code>ifnet_set_addrlen</code> if interface is attached 749 to the network stack, and updates the <code>kIOMediaAddressLength</code> 750 property using the provided value. 751 @param length The size of the media address in bytes. 752 @result Always returns true. 753*/ 754 virtual bool setMediaAddressLength( UInt8 length ); 755 756/*! @function setMediaHeaderLength 757 @abstract Sets the size of the media header. 758 @discussion Calls <code>ifnet_set_hdrlen</code> if interface is attached 759 to the network stack, and updates the <code>kIOMediaHeaderLength</code> 760 property using the provided value. 761 @param length The size of the media header in bytes. 762 @result Always returns true. 763*/ 764 virtual bool setMediaHeaderLength( UInt8 length ); 765 766/*! @function setUnitNumber 767 @abstract Assigns an unique unit number to this interface. 768 @discussion This method is called internally before the interface is 769 attached to the network stack, to assign an unique unit number to the 770 interface object. The <code>kIOInterfaceUnit</code> property is also 771 updated using the provided value. 772 @param unit The unit number assigned to this interface object. 773 @result Returns true to indicate success if the interface has not yet 774 attached to the network stack, otherwise returns false. 775*/ 776 virtual bool setUnitNumber( UInt16 unit ); 777 778/*! @function free 779 @abstract Frees the <code>IONetworkInterface</code> object. 780 @discussion Resource allocated by init() are released, and 781 clearInputQueue() is called to ensure that the input queue is empty. 782 The interface should have already detached from the network stack. 783*/ 784 virtual void free( void ); 785 786 /* Override IOService::handleOpen() */ 787 virtual bool handleOpen( IOService * client, 788 IOOptionBits options, 789 void * argument ); 790 791 /* Override IOService::handleClose() */ 792 virtual void handleClose( IOService * client, IOOptionBits options ); 793 794 /* Override IOService::handleIsOpen() */ 795 virtual bool handleIsOpen( const IOService * client ) const; 796 797/*! @function lock 798 @abstract Acquires a recursive lock owned by the interface. 799 @discussion A recursive lock is allocated and initialized in 800 <code>init()</code>. This lock is otherwise not used by the 801 <code>IONetworkInterface</code> class. This method call acquires 802 the lock and must be balanced with an <code>unlock()</code>. 803*/ 804 virtual void lock( void ); 805 806/*! @function unlock 807 @abstract Releases the recursive lock owned by the interface. 808 @discussion A recursive lock is allocated and initialized in 809 <code>init()</code>. This lock is otherwise not used by the 810 <code>IONetworkInterface</code> class. This method call releases 811 the lock to balance a prior <code>lock()</code>. 812*/ 813 virtual void unlock( void ); 814 815/*! @function controllerDidOpen 816 @abstract Sends a notification that the interface has opened the network 817 controller. 818 @discussion This method is called by <code>handleOpen()</code> to notify 819 subclasses that the controller was opened. The open on the controller 820 occurs when the interface receives the initial open request from a client. 821 Subclasses can override this method and inspect the controller before 822 allowing the client open. This method is called with the arbitration lock 823 held, hence issuing I/O to the controller must be avoided to eliminate the 824 possibility of a deadlock. 825 @param controller The controller that was opened. 826 @result Must return true in order for handleOpen() to accept the client 827 open. If the return is false, then the controller will be closed and the 828 client open will fail. 829*/ 830 virtual bool controllerDidOpen( IONetworkController * controller ); 831 832/*! @function controllerWillClose 833 @abstract Sends a notification that the interface will close the network 834 controller. 835 @discussion This method is called by <code>handleClose()</code> after 836 receiving a close from the last interface client, and just before the 837 controller is closed. Subclasses can override this method to perform any 838 cleanup action before the controller is closed. This method is called with 839 the arbitration lock held, hence issuing I/O to the controller should be 840 avoided to eliminate the possibility of a deadlock. 841 @param controller The controller that is about to be closed. 842*/ 843 virtual void controllerWillClose( IONetworkController * controller ); 844 845/*! @function performCommand 846 @abstract Handles an ioctl command sent to the network interface. 847 @discussion This method handles socket ioctl commands sent to the 848 network interface from DLIL. 849 IONetworkInterface handles commands that are common for all network 850 interface types. A subclass of IONetworkInterface may override this 851 method to override the command handling in IONetworkInterface, or 852 to extend the command processing to handle additional commands. 853 The ioctl commands handled by IONetworkInterface are 854 <code>SIOCGIFMTU</code> (Get interface MTU size), 855 <code>SIOCSIFMTU</code> (Set interface MTU size), 856 <code>SIOCSIFMEDIA</code> (Set media), and 857 <code>SIOCGIFMEDIA</code> (Get media and link status). 858 @param controller The controller object. 859 @param cmd The ioctl command code. 860 @param arg0 Command argument 0. Generally a pointer to an ifnet structure 861 associated with the interface. 862 @param arg1 Command argument 1. 863 @result Returns a BSD return value defined in <code>bsd/sys/errno.h</code>. 864*/ 865 virtual SInt32 performCommand( 866 IONetworkController * controller, 867 unsigned long cmd, 868 void * arg0, 869 void * arg1 ); 870 871public: 872 873/*! @function getIfnet 874 @abstract Returns the <code>ifnet_t</code> allocated by the interface object. 875 @discussion Gets the interface's <code>ifnet_t</code>, which is managed 876 primarily by <code>IONetworkInterface</code>, however subclasses or drivers 877 can use this method to obtain a reference to the <code>ifnet_t</code> for 878 interface KPI calls. 879 @result Returns the <code>ifnet_t</code> after the interface has attached 880 to the network stack and before the interface is detached, otherwise returns 881 NULL. 882*/ 883 virtual ifnet_t getIfnet( void ) const; 884 885protected: 886 887 /* Deprecated. Use <code>initIfnetParams</code> instead. */ 888 virtual bool initIfnet( struct ifnet * ifp ); 889 890/*! @function handleClientOpen 891 @abstract Handles a client open on the interface. 892 @discussion This method is called by <code>handleOpen()</code> to allow a 893 subclass to handle a client close. The arbitration lock is held. 894 @param client The client object requesting the open. 895 @param options Options passed to <code>handleOpen()</code>. 896 @param argument Argument passed to <code>handleOpen()</code>. 897 @result Returns true to accept the client open, false to reject the open. 898*/ 899 virtual bool handleClientOpen( IOService * client, 900 IOOptionBits options, 901 void * argument ); 902 903/*! @function handleClientClose 904 @abstract Handles a client close on the interface. 905 @discussion This method is called by <code>handleClose()</code> to allow a 906 subclass to handle a client close. The arbitration lock is held. 907 @param client The client object requesting the close. 908 @param options Options same options passed to <code>handleClose()</code>. 909*/ 910 virtual void handleClientClose( IOService * client, 911 IOOptionBits options ); 912 913 /* Override IOService::newUserClient() */ 914 virtual IOReturn newUserClient( task_t owningTask, 915 void * security_id, 916 UInt32 type, 917 IOUserClient ** handler ); 918 919/*! @function setInterfaceState 920 @abstract Updates the interface object state flags. 921 @discussion The flags reflect the current state of the interface, and is 922 also published through the <code>kIOInterfaceState</code> property. 923 @param set The flags that should be set. 924 @param clear The flags that should be cleared. 925 @result Returns the new interface state flags. 926*/ 927 virtual UInt32 setInterfaceState( UInt32 set, UInt32 clear = 0 ); 928 929/*! @function powerStateWillChangeTo 930 @abstract Handles a pre-change power interest notification from the 931 network controller. 932 @discussion The <code>controllerWillChangePowerState()</code> method is 933 called by this handler. Subclasses are not expected to override this method. 934 @param flags Flags that describe the capability of the controller in the 935 new power state. 936 @param stateNumber An index to a state in the network controller's 937 power state array that the controller is switching to. 938 @param policyMaker A reference to the network controller's policy-maker, 939 and is also the originator of this notification. 940 @result Returns <code>IOPMAckImplied</code> to indicate synchronous completion. 941*/ 942 virtual IOReturn powerStateWillChangeTo( 943 IOPMPowerFlags flags, 944 unsigned long stateNumber, 945 IOService * policyMaker ); 946 947/*! @function powerStateDidChangeTo 948 @abstract Handles a post-change power interest notification from the 949 network controller. 950 @discussion The <code>controllerDidChangePowerState()</code> method is 951 called by this handler. Subclasses are not expected to override this method. 952 @param flags Flags that describe the capability of the controller in the 953 new power state. 954 @param stateNumber An index to a state in the network controller's 955 power state array that the controller has switched to. 956 @param policyMaker A reference to the network controller's policy-maker, 957 and is also the originator of this notification. 958 @result Returns <code>IOPMAckImplied</code> to indicate synchronous completion. 959*/ 960 virtual IOReturn powerStateDidChangeTo( 961 IOPMPowerFlags flags, 962 unsigned long stateNumber, 963 IOService * policyMaker ); 964 965/*! @function controllerWillChangePowerState 966 @abstract Handles a notification that the network controller servicing 967 this interface object will transition to a new power state. 968 @param controller The network controller object. 969 @param flags Flags that describe the capability of the controller in the 970 new power state. 971 @param stateNumber An index to a state in the network controller's 972 power state array that the controller is switching to. 973 @param policyMaker A reference to the network controller's policy-maker, 974 and is also the originator of this notification. 975 @result The return value is always <code>kIOReturnSuccess</code>. 976*/ 977 virtual IOReturn controllerWillChangePowerState( 978 IONetworkController * controller, 979 IOPMPowerFlags flags, 980 UInt32 stateNumber, 981 IOService * policyMaker ); 982 983/*! @function controllerDidChangePowerState 984 @abstract Handles a notification that the network controller servicing 985 this interface object has transitioned to a new power state. 986 @param controller The network controller object. 987 @param flags Flags that describe the capability of the controller in the 988 new power state. 989 @param stateNumber An index to a state in the network controller's 990 power state array that the controller has switched to. 991 @param policyMaker A reference to the network controller's policy-maker, 992 and is also the originator of this notification. 993 @result The return value is always <code>kIOReturnSuccess</code>. 994*/ 995 virtual IOReturn controllerDidChangePowerState( 996 IONetworkController * controller, 997 IOPMPowerFlags flags, 998 UInt32 stateNumber, 999 IOService * policyMaker ); 1000 1001public: 1002 /* Override IOService::willTerminate() */ 1003 virtual bool willTerminate( 1004 IOService * provider, 1005 IOOptionBits options ); 1006 1007 /* Override IOService::requestTerminate() */ 1008 virtual bool requestTerminate( 1009 IOService * provider, IOOptionBits options ); 1010 1011 /* Override IOService::serializeProperties() */ 1012 virtual bool serializeProperties( OSSerialize * s ) const; 1013 1014/*! @function attachToDataLinkLayer 1015 @abstract Attach the network interface to the BSD data link layer. 1016 @discussion This method is called internally to attach the network 1017 interface to the BSD data link layer, after an unit number has been 1018 assigned. The calling context is not synchronized against the driver's 1019 work loop. Subclasses may override this method to perform additional 1020 setup before the network stack attach. The <code>getIfnet()</code> method 1021 will return the BSD interface being attached. 1022 @param options Options for the attach call. None are currently defined. 1023 @param parameter Parameter for the attach call. Not currently used. 1024 @result Returns <code>kIOReturnSuccess</code> on success. 1025*/ 1026 virtual IOReturn attachToDataLinkLayer( IOOptionBits options, 1027 void * parameter ); 1028 1029 OSMetaClassDeclareReservedUsed(IONetworkInterface, 0); 1030 1031/*! @function detachFromDataLinkLayer 1032 @abstract Detach the network interface from the BSD data link layer. 1033 @discussion This method is called internally to detach the network 1034 interface from the BSD data link layer, after the interface has been 1035 terminated and before the last client close. This method will block until 1036 the detach operation is complete. The calling context is not synchronized 1037 against the driver's work loop. Subclasses may override this method to 1038 perform additional cleanup before or after detaching from the network 1039 stack. The <code>getIfnet()</code> method will return NULL after detach. 1040 @param options Options for the detach call. None are currently defined. 1041 @param parameter Parameter for the detach call. Not currently used. 1042*/ 1043 virtual void detachFromDataLinkLayer( IOOptionBits options, 1044 void * parameter ); 1045 1046 OSMetaClassDeclareReservedUsed(IONetworkInterface, 1); 1047 1048protected: 1049/*! @function feedPacketInputTap 1050 @abstract Feed received packets to the BPF 1051 @discussion This function is called internally to send input packets to 1052 the BPF input tap when it is enabled. Subclasses are not expected to 1053 override this method. 1054 @param mbuf_t Pointer to the input packet. 1055*/ 1056 virtual void feedPacketInputTap( mbuf_t ); 1057 1058 OSMetaClassDeclareReservedUsed(IONetworkInterface, 2); 1059 1060/*! @function feedPacketOutputTap 1061 @abstract Feed output packets to the BPF 1062 @discussion This function is called internally to send output packets to 1063 the BPF output tap when it is enabled. Subclasses are not expected to 1064 override this method. 1065 @param mbuf_t Pointer to the output packet. 1066*/ 1067 virtual void feedPacketOutputTap( mbuf_t ); 1068 1069 OSMetaClassDeclareReservedUsed(IONetworkInterface, 3); 1070 1071/*! @function initIfnetParams 1072 @abstract Allows a subclass to provide ifnet initialization parameters 1073 specific to an interface type. 1074 @discussion This method initializes the parameters that are common to all 1075 network interfaces. An interface subclass is expected to override this 1076 method, call the superclass implementation first, then initialize the 1077 parameters specific to that interface type. This method is called after 1078 an unit number has been assigned to the interface, and just before the 1079 interface is attached to BSD. 1080 @param params Pointer to an <code>ifnet_init_params</code> allocated by 1081 the caller. 1082 @result Returns <code>true</code> on success, <code>false</code> otherwise. 1083*/ 1084 virtual bool initIfnetParams( struct ifnet_init_params * params ); 1085 1086 OSMetaClassDeclareReservedUsed(IONetworkInterface, 4); 1087 1088public: 1089#ifdef __PRIVATE_SPI__ 1090/*! @function setInterfaceSubType 1091 @abstract Sets the interface sub-type. 1092 @discussion The sub-type must be set before the interface is attached to 1093 the networking stack. The driver's <code>configureInterface()</code> 1094 or <code>attachToDataLinkLayer</code> in a subclass are valid call sites. 1095 @param subType A constant defined in <code>IONetworkTypesPrivate.h</code>. 1096 @result Returns <code>true</code> on success, <code>false</code> otherwise. 1097*/ 1098 bool setInterfaceSubType( uint32_t subType ); 1099 1100/*! @function isBPFTapEnabled 1101 @abstract Query if the BPF tap is enabled. 1102 @abstract Allows a driver to poll the BPF tap state after receiving a 1103 <code>kIONetworkNotificationBPFTapStateChange</code> notification. 1104 @param options No options are currently defined, always pass zero. 1105 @result Returns <code>true</code> if BPF tap is enabled, 1106 <code>false</code> otherwise. 1107*/ 1108 bool isBPFTapEnabled( IOOptionBits options = 0 ) const; 1109 1110/*! @function getLoggingLevel 1111 @abstract Query the logging level for the interface. 1112 @abstract Allows a driver to poll the logging level after receiving a 1113 <code>kIONetworkNotificationLoggingLevelChange</code> notification. 1114 @param options No options are currently defined, always pass zero. 1115 @result Returns the current logging level. 1116*/ 1117 int32_t getLoggingLevel( IOOptionBits options = 0 ) const; 1118 1119/*! @enum OutputPacketSchedulingModel 1120 @discussion Output packet scheduling models. 1121 @constant kOutputPacketSchedulingModelNormal 1122 The default output packet scheduling model where the driver or media does 1123 not require strict scheduling strategy, and that the networking stack is 1124 free to choose the most appropriate scheduling and queueing algorithm, 1125 including shaping traffics. 1126 @constant kOutputPacketSchedulingModelDriverManaged 1127 The alternative output packet scheduling model where the driver or media 1128 requires strict scheduling strategy (e.g. 802.11 WMM), and that the 1129 networking stack is only responsible for creating multiple queues for the 1130 corresponding service classes. 1131*/ 1132 enum { 1133 kOutputPacketSchedulingModelNormal = 0, 1134 kOutputPacketSchedulingModelDriverManaged = 1 1135 }; 1136 1137/*! @function configureOutputPullModel 1138 @abstract Configure and use the pull-model to transmit packets. 1139 @discussion A driver that supports the pull-model to transmit packets must 1140 call this method from <code>configureInterface()</code> to configure the 1141 model, and to transition the interface to use the pull-model exclusively. 1142 In the pull-model, the interface will manage an output queue that a driver 1143 can pull packets from. An output thread will notify the driver through 1144 <code>outputStart()</code> when packets are added to the output queue. 1145 @param driverQueueSize The number of packets that the driver's transmit 1146 queue or ring can hold. 1147 @param options <code>kIONetworkWorkLoopSynchronous</code> forces the output 1148 thread to call <code>outputStart()</code> on the driver's work loop context. 1149 @param outputQueueSize The size of the interface output queue. Unless the 1150 driver has special requirements, it is advisable to pass zero to let the 1151 networking stack choose the output queue size. 1152 @param outputSchedulingModel An output packet scheduling model. 1153 Pass zero or <code>kOutputPacketSchedulingModelNormal</code> for the default 1154 model which lets the network stacking choose the most appropriate scheduling 1155 and queueing algorithm. 1156 @result <code>kIOReturnSuccess</code> if interface was successfully 1157 configured to use the pull-model for outbound packets. 1158*/ 1159 virtual IOReturn configureOutputPullModel( 1160 uint32_t driverQueueSize, 1161 IOOptionBits options = 0, 1162 uint32_t outputQueueSize = 0, 1163 uint32_t outputSchedulingModel = 0 ); 1164 1165 OSMetaClassDeclareReservedUsed(IONetworkInterface, 5); 1166 1167/*! @function configureInputPacketPolling 1168 @abstract Configure and enable polling of input packets. 1169 @discussion A driver that supports polled-mode processing of input packets 1170 must call this method from <code>configureInterface()</code> to configure 1171 input polling. Once configured, the network stack is allowed to dynamically 1172 transition the input model from the default push-model where packets are 1173 pushed by the driver to the network stack, to the pull-model where a poller 1174 thread will periodically pull packets (if any) from the driver. 1175 @param driverQueueSize The number of packets that the driver's receive 1176 queue or ring can hold when completely full. 1177 @param options <code>kIONetworkWorkLoopSynchronous</code> forces the 1178 poller thread to call <code>pollInputPackets()</code> on the driver's 1179 work loop context. The <code>setInputPacketPollingEnable()</code> 1180 method call is always synchronized against the driver's work loop. 1181 @result <code>kIOReturnSuccess</code> if input polling was successfully 1182 configured. 1183*/ 1184 virtual IOReturn configureInputPacketPolling( 1185 uint32_t driverQueueSize, 1186 IOOptionBits options = 0 ); 1187 1188 OSMetaClassDeclareReservedUsed(IONetworkInterface, 6); 1189 1190/*! @function reportDataTransferRates 1191 @abstract For drivers to report the current data transfer rates. 1192 @discussion The rates reported by this method will supersede the single 1193 link speed reported by <code>IONetworkController::setLinkStatus</code>. 1194 This method allows the driver to report asymmetric input and output data 1195 rates, and also the effective data rates when available. 1196 @param outputRateMax The maximum output data rate in bit/s. 1197 @param inputRateMax The maximum input data rate in bit/s. 1198 @param outputRateEffective The effective output data rate in bit/s. 1199 If zero, the outputRateMax value is passed to the network stack. 1200 @param inputRateEffective The effective input data rate in bit/s. 1201 If zero, the inputRateMax value is passed to the network stack. 1202*/ 1203 virtual void reportDataTransferRates( 1204 uint64_t outputRateMax, 1205 uint64_t inputRateMax, 1206 uint64_t outputRateEffective = 0, 1207 uint64_t inputRateEffective = 0 ); 1208 1209 OSMetaClassDeclareReservedUsed(IONetworkInterface, 7); 1210 1211/*! @function stopOutputThread 1212 @abstract Called by drivers to stop the output thread. 1213 @discussion Only drivers that support the pull output model should call 1214 this method. In the stop state, the output thread will not invoke the 1215 driver's <code>outputStart()</code> method, even when new packets are 1216 added to the output queue. This method is synchronous with respect to 1217 any <code>outputStart()</code> invocation, so upon returning from this 1218 method it is guaranteed that the output thread has stopped executing 1219 driver code. The network interface will internally stop the output 1220 thread before detaching from the network stack, and also before system 1221 shutdown and restart. 1222 @param options No options are currently defined, always pass zero. 1223 @result <code>kIOReturnSuccess</code> if the thread was stopped, 1224 <code>kIOReturnTimeout</code> if the wait for output thread to exit 1225 <code>outputStart()</code> timed out. 1226*/ 1227 IOReturn stopOutputThread( IOOptionBits options = 0 ); 1228 1229/*! @function startOutputThread 1230 @abstract Called by drivers to start the output thread. 1231 @discussion The output thread is initially in a stop state, and it must 1232 be started before it can invoke the driver's <code>outputStart()</code> 1233 method. Drivers may also issue start to release a previous stop request. 1234 After starting the output thread, if the output queue is not empty, or 1235 after a new packet is added to the output queue, the output thread will 1236 wakeup and invoke the driver's <code>outputStart()</code> method. 1237 @param options No options are currently defined, always pass zero. 1238 @result <code>kIOReturnSuccess</code> if start was successful, 1239 <code>kIOReturnNotAttached</code> if the network interface has detached 1240 from the network stack. 1241*/ 1242 IOReturn startOutputThread( IOOptionBits options = 0 ); 1243 1244/*! @function signalOutputThread 1245 @abstract Informs the output thread that driver has completed packet 1246 transmission. 1247 @discussion A driver that supports the pull output model must call this 1248 method after packet transmission is complete, and driver resources are 1249 available to <code>outputStart()</code> to handle additional packets. 1250 It is recommended to batch this call when retiring a group of output 1251 packets. This method will wake up the output thread if the output queue 1252 is not empty, and the output thread is not stopped. 1253 @param options No options are currently defined, always pass zero. 1254*/ 1255 void signalOutputThread( IOOptionBits options = 0 ); 1256 1257/*! @function flushOutputQueue 1258 @abstract Flush all packets in the interface output queue. 1259 @discussion A driver that supports the pull output model can use this 1260 method to free all packets currently held in the interface output queue. 1261 @param options No options are currently defined, always pass zero. 1262*/ 1263 void flushOutputQueue( IOOptionBits options = 0 ); 1264 1265/*! @function dequeueOutputPackets 1266 @abstract Dequeue packets from the interface output queue. 1267 @discussion A driver that supports the output pull-model will typically 1268 call this method from <code>outputStart()</code> after it has calculated 1269 the maximum number of packets that can be dequeued based on available 1270 resources. Drivers should not dequeue more packets than they can accept 1271 since there is no facility to insert a packet to the head of the queue. 1272 The only recourse is to drop the packet, or store the packet on a driver 1273 managed queue which is not recommended. This method can dequeue a single 1274 packet as a mbuf chain, or multiple packets using a linked list of mbuf 1275 chains. It is also possible for the queue to not return any packet to the 1276 driver in order to throttle the transmit rate. Although typically called 1277 from <code>outputStart()</code>, this is not a mandatory requirement. E.g. 1278 a driver may choose to dequeue in the transmit completion path to quickly 1279 fill an available transmit slot. 1280 @param maxCount The maximum number of packets to dequeue. This value must 1281 be greater than zero. 1282 @param packetHead Pointer to the first packet that was dequeued. 1283 @param packetTail Optional pointer to the last packet that was dequeued. 1284 @param packetCount Optional pointer to store the number of packets that 1285 was dequeued. 1286 @param packetBytes Optional pointer to store the total length of packets 1287 that was dequeued. The length of each packet is given by 1288 <code>mbuf_pkthdr_len()</code>. 1289 @result <code>kIOReturnSuccess</code> if at least one packet was dequeued, 1290 <code>kIOReturnBadArgument</code> if an argument was invalid, 1291 <code>kIOReturnNoFrames</code> if the queue is empty, or the queue is 1292 limiting the transmit rate. 1293*/ 1294 virtual IOReturn dequeueOutputPackets( 1295 uint32_t maxCount, 1296 mbuf_t * packetHead, 1297 mbuf_t * packetTail = 0, 1298 uint32_t * packetCount = 0, 1299 uint64_t * packetBytes = 0 ); 1300 1301 OSMetaClassDeclareReservedUsed(IONetworkInterface, 8); 1302 1303/*! @function dequeueOutputPacketsWithServiceClass 1304 @abstract Dequeue packets of a particular service class from the interface 1305 output queue. 1306 @discussion See <code>dequeueOutputPackets</code>. 1307 @param maxCount The maximum number of packets to dequeue. This value must 1308 be greater than zero. 1309 @param serviceClass A service class specification provided by the caller. 1310 Only packets belonging to the specified service class will be dequeued. 1311 @param packetHead Pointer to the first packet that was dequeued. 1312 @param packetTail Optional pointer to the last packet that was dequeued. 1313 @param packetCount Optional pointer to store the number of packets that 1314 was dequeued. 1315 @param packetBytes Optional pointer to store the total length of packets 1316 that was dequeued. The length of each packet is given by 1317 <code>mbuf_pkthdr_len()</code>. 1318 @result <code>kIOReturnSuccess</code> if at least one packet was dequeued, 1319 <code>kIOReturnBadArgument</code> if an argument was invalid, 1320 <code>kIOReturnNoFrames</code> if the queue is empty, no packet belongs to 1321 the service class or the queue is limiting the transmit rate. 1322*/ 1323 virtual IOReturn dequeueOutputPacketsWithServiceClass( 1324 uint32_t maxCount, 1325 IOMbufServiceClass serviceClass, 1326 mbuf_t * packetHead, 1327 mbuf_t * packetTail = 0, 1328 uint32_t * packetCount = 0, 1329 uint64_t * packetBytes = 0 ); 1330 1331 OSMetaClassDeclareReservedUsed(IONetworkInterface, 9); 1332 1333/* @function installOutputPreEnqueueHandler 1334 @abstract Install a handler to intercept all output packets before they 1335 are added to the output queue. 1336 @discussion A single handler can be installed before the interface is 1337 attached to the networking stack. The handler will not be invoked unless 1338 the driver configures the interface to utilize the new output pull-model. 1339 @param handler A C-function handler. 1340 @target A reference passed to the handler. 1341 @refCon A reference constant passed to the handler. 1342 @result <code>kIOReturnSuccess</code> if the handler was successfully 1343 installed, <code>kIOReturnBadArgument</code> if the handler provided was 1344 NULL, or <code>kIOReturnError</code> if the call was made after the 1345 interface has already attached to the networking stack. 1346*/ 1347 IOReturn installOutputPreEnqueueHandler( 1348 OutputPreEnqueueHandler handler, 1349 void * target, 1350 void * refCon ); 1351 1352/* @function enqueueOutputPacket 1353 @abstract Enqueue a packet to the output queue. 1354 @discussion Wrapper for the private <code>ifnet_enqueue()</code>. 1355 @param packet The packet being enqueued; only one packet is allowed 1356 to be enqueued at a time. 1357 @param options No options are currently defined, always pass zero. 1358 @result The value returned by <code>ifnet_enqueue()</code>. 1359*/ 1360 errno_t enqueueOutputPacket( 1361 mbuf_t packet, 1362 IOOptionBits options = 0 ); 1363 1364/*! @function enqueueInputPacket 1365 @abstract Queue a packet received by the driver before forwarding it to 1366 the networking stack. 1367 @discussion When input polling is not enabled, drivers should call this 1368 method to queue each received packet on the interface input queue, then 1369 flush the input queue at the end of the driver receive loop. When this 1370 method is called as a result of input polling, driver must specify the 1371 polling queue by passing the queue provided by the poller. Access to the 1372 interface input queue is unsynchronized, since input packet handling is 1373 expected to be single-threaded. The input packet must point to a header 1374 mbuf with <code>MBUF_PKTHDR</code> flag set, with any additional mbufs 1375 linked by the next chain. The length in the packet header, including the 1376 data length for every mbuf in the chain must be set. If FCS is included 1377 in the packet data, then the <code>MBUF_HASFCS</code> mbuf flag must be 1378 set. This is the preferred interface to queue and submit an input packet, 1379 and is functionally equivalent to calling <code>inputPacket</code> with 1380 the <code>kInputOptionQueuePacket</code> option. Submitting a chain of 1381 packets is not supported. 1382 @param packet The input packet. Caller ceases ownership of the packet 1383 regardless of the return value. 1384 @param queue Defaults to zero which specifies the interface input queue. 1385 To handoff a packet during input polling, pass the queue provided by the 1386 poller. 1387 @param options No options are currently defined, always pass zero. 1388 @result <code>kIOReturnSuccess</code> if packet was added to the queue, 1389 or an error code otherwise. 1390*/ 1391 virtual IOReturn enqueueInputPacket( 1392 mbuf_t packet, 1393 IOMbufQueue * queue = 0, 1394 IOOptionBits options = 0 ); 1395 1396 OSMetaClassDeclareReservedUsed(IONetworkInterface, 10); 1397 1398/*! @function reportTransmitCompletionStatus 1399 @abstract Report the transmit completion status for an outgoing packet. 1400 @discussion Invoked by drivers that are capable of reporting when a packet 1401 has been transmitted across the link layer. Besides reporting the packet 1402 transmit status using this method, driver must also publish the 1403 <code>kIONetworkFeatureTransmitCompletionStatus</code> feature. 1404 @param packet The packet that was transmitted. 1405 @param status The transmit status. 1406 @param param1 Always pass zero. 1407 @param param2 Always pass zero. 1408 @param No options are currently defined, always pass zero. 1409 @result <code>kIOReturnSuccess</code> if the transmit status was valid 1410 and accepted, otherwise <code>kIOReturnBadArgument</code> for bad status, 1411 or <code>kIOReturnError</code> if an error occurred when passing the status 1412 to the networking stack. 1413*/ 1414 IOReturn reportTransmitCompletionStatus( 1415 mbuf_t packet, 1416 IOReturn status, 1417 uint32_t param1 = 0, 1418 uint32_t param2 = 0, 1419 IOOptionBits options = 0 ); 1420 1421/*! @function reportDatapathIssue 1422 @abstract Used by kernel network driver or family to inform userspace 1423 of a datapath issue. 1424 @discussion An issue report will be sent to any userspace applications 1425 or daemons that have registered for datapath issues notifications from 1426 this network interface. 1427 @param issue Subsystem specific error code. 1428 @param data Reserved for future use. 1429 @param length Reserved for future use. 1430 @result Returns <code>kIOReturnSuccess</code> if successful, 1431 otherwise an appropriate error code. 1432*/ 1433 IOReturn reportDatapathIssue( 1434 IOReturn issue, 1435 void * data = 0, 1436 IOByteCount length = 0 ); 1437 1438/*! @function setPacketPollingParameters 1439 @abstract Modify the input polling parameters. 1440 @discussion Invokes <code>ifnet_set_poll_params()</code> using the 1441 parameters provided. 1442 @param params Polling parameters. 1443 @param options No options are currently defined, always pass zero. 1444 @result Returns <code>kIOReturnSuccess</code> if successful, 1445 otherwise an appropriate error code. 1446*/ 1447 IOReturn setPacketPollingParameters( 1448 const IONetworkPacketPollingParameters * params, 1449 IOOptionBits options = 0 ); 1450#else /* !__PRIVATE_SPI__ */ 1451 OSMetaClassDeclareReservedUnused( IONetworkInterface, 5); 1452 OSMetaClassDeclareReservedUnused( IONetworkInterface, 6); 1453 OSMetaClassDeclareReservedUnused( IONetworkInterface, 7); 1454 OSMetaClassDeclareReservedUnused( IONetworkInterface, 8); 1455 OSMetaClassDeclareReservedUnused( IONetworkInterface, 9); 1456 OSMetaClassDeclareReservedUnused( IONetworkInterface, 10); 1457#endif /* !__PRIVATE_SPI__ */ 1458 OSMetaClassDeclareReservedUnused( IONetworkInterface, 11); 1459 OSMetaClassDeclareReservedUnused( IONetworkInterface, 12); 1460 OSMetaClassDeclareReservedUnused( IONetworkInterface, 13); 1461 OSMetaClassDeclareReservedUnused( IONetworkInterface, 14); 1462 OSMetaClassDeclareReservedUnused( IONetworkInterface, 15); 1463}; 1464 1465#endif /* __cplusplus */ 1466#endif /* KERNEL */ 1467#endif /* !_IONETWORKINTERFACE_H */ 1468