iokit/IOKit/network/IONetworkInterface.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  24  *
  25  * IONetworkInterface.h
  26  *
  27  * HISTORY
  28  * 8-Jan-1999       Joe Liu (jliu) created.
  29  */
  30
  31 #ifndef _IONETWORKINTERFACE_H
  32 #define _IONETWORKINTERFACE_H
  33
  34 /*! @defined kIONetworkInterfaceClass
  35     @abstract kIONetworkInterfaceClass is the name of the
  36         IONetworkInterface class. */
  37
  38 #define kIONetworkInterfaceClass     "IONetworkInterface"
  39
  40 /*! @defined kIONetworkData
  41     @abstract kIONetworkData is a property of IONetworkInterface
  42         objects. It has an OSDictionary value.
  43     @discussion The kIONetworkData property is a container for the
  44         set of IONetworkData objects managed by the interface.
  45         Each entry in the dictionary is a key/value pair consisting of
  46         the network data name, and an OSDictionary describing the
  47         contents of the network data. */
  48
  49 #define kIONetworkData            "IONetworkData"
  50
  51 /*! @defined kIOInterfaceType
  52     @abstract kIOInterfaceType is a property of IONetworkInterface objects.
  53         It has an OSNumber value.
  54     @discussion The kIOInterfaceType property specifies the type of
  55         network interface that this interface represents. The type
  56         constants are defined in bsd/net/if_types.h. */
  57
  58 #define kIOInterfaceType          "IOInterfaceType"
  59
  60 /*! @defined kIOMaxTransferUnit
  61     @abstract kIOMaxTransferUnit is a property of IONetworkInterface objects.
  62         It has an OSNumber value.
  63     @discussion The kIOMaxTransferUnit property specifies the maximum
  64         transfer unit for the interface in bytes. */
  65
  66 #define kIOMaxTransferUnit        "IOMaxTransferUnit"
  67
  68 /*! @defined kIOMediaAddressLength
  69     @abstract kIOMediaAddressLength is a property of IONetworkInterface objects.
  70         It has an OSNumber value.
  71     @discussion The kIOMediaAddressLength property specifies the size of the
  72         media address in bytes. */
  73
  74 #define kIOMediaAddressLength     "IOMediaAddressLength"
  75
  76 /*! @defined kIOMediaHeaderLength
  77     @abstract kIOMediaHeaderLength is a property of IONetworkInterface objects.
  78         It has an OSNumber value.
  79     @discussion The kIOMediaHeaderLength property specifies the size of the
  80         media header in bytes. */
  81
  82 #define kIOMediaHeaderLength      "IOMediaHeaderLength"
  83
  84 /*! @defined kIOInterfaceFlags
  85     @abstract kIOInterfaceFlags is a property of IONetworkInterface objects.
  86         It has an OSNumber value.
  87     @discussion The kIOInterfaceFlags property specifies the current value
  88         of the interface flags. The flag constants are defined in
  89         bsd/net/if.h. */
  90
  91 #define kIOInterfaceFlags         "IOInterfaceFlags"
  92
  93 /*! @defined kIOInterfaceExtraFlags
  94     @abstract kIOInterfaceExtraFlags is a property of IONetworkInterface
  95         objects. It has an OSNumber value.
  96     @discussion The kIOInterfaceExtraFlags property specifies the current
  97         value of the interface extra flags. The extra flag constants are
  98         defined in bsd/net/if.h. */
  99
 100 #define kIOInterfaceExtraFlags    "IOInterfaceExtraFlags"
 101
 102 /*! @defined kIOInterfaceUnit
 103     @abstract kIOInterfaceUnit is a property of IONetworkInterface
 104         objects. It has an OSNumber value.
 105     @discussion The kIOInterfaceUnit property describes the unit number
 106         assigned to the interface object. */
 107
 108 #define kIOInterfaceUnit          "IOInterfaceUnit"
 109
 110 /*! @defined kIOInterfaceState
 111     @abstract kIOInterfaceState is a property of IONetworkInterface
 112         objects. It has an OSNumber value.
 113     @discussion The kIOInterfaceState property describes the current state
 114         of the interface object. This property is not exported to BSD via
 115         the ifnet structure. */
 116
 117 #define kIOInterfaceState         "IOInterfaceState"
 118
 119 /*! @defined kIOInterfaceNamePrefix
 120     @abstract kIOInterfaceNamePrefix is a property of IONetworkInterface
 121         objects. It has an OSString value.
 122     @discussion The kIOInterfaceNamePrefix property describes the string
 123         prefix for the BSD name assigned to the interface. */
 124
 125 #define kIOInterfaceNamePrefix    "IOInterfaceNamePrefix"
 126
 127 /*! @defined kIOPrimaryInterface
 128     @abstract kIOPrimaryInterface is a property of IONetworkInterface
 129         objects. It has an OSBoolean value.
 130     @discussion The kIOInterfaceNamePrefix property describes whether the
 131         interface is the primary or the built-in network interface. */
 132
 133 #define kIOPrimaryInterface       "IOPrimaryInterface"
 134
 135 /*! @enum Interface state flags.
 136     @discussion An enumeration of the constants that are used to encode the
 137         state of the interface object.
 138     @constant kIONetworkInterfaceRegisteredState The interface object has
 139         registered with the data link layer.
 140     @constant kIONetworkInterfaceOpenedState One or more clients have an
 141         open on the interface object.
 142     @constant kIONetworkInterfaceDisabledState The interface is temporarily
 143         unable to service its clients. This will occur when the network
 144         controller that is servicing the interface has entered a low power
 145         state that renders it unusable. */
 146
 147 enum {
 148     kIONetworkInterfaceRegisteredState  = 0x1,
 149     kIONetworkInterfaceOpenedState      = 0x2,
 150     kIONetworkInterfaceDisabledState    = 0x4
 151 };
 152
 153 /*
 154  * Kernel
 155  */
 156 #if defined(KERNEL) && defined(__cplusplus)
 157
 158 #include <IOKit/IOService.h>
 159 #include <IOKit/network/IONetworkData.h>
 160 #include <IOKit/network/IONetworkStats.h>
 161 #include <IOKit/network/IONetworkMedium.h>
 162
 163 struct mbuf;                // forward declarations.
 164 struct ifnet;
 165 class  IONetworkController;
 166 class  IONetworkStack;
 167 class  IOCommandGate;
 168
 169 /*! @typedef IOOutputAction
 170     @discussion Prototype for an output packet handler that will process
 171     all outbound packets sent to the interface from the data link layer.
 172     An output handler is registered with the interface by calling
 173     registerOutputHandler().
 174     @param m A packet mbuf.
 175     @param param A parameter for the output request. */
 176
 177 typedef UInt32 (OSObject::*IOOutputAction)(struct mbuf * m, void * param);
 178
 179 /*! @typedef BPF_FUNC
 180     @discussion Prototype for the BPF tap handler. This will disappear
 181     when the correct DLIL header file is included. */
 182
 183 typedef int (*BPF_FUNC)(struct ifnet *, struct mbuf *);
 184
 185 // Network event types recognized by inputEvent().
 186 //
 187 enum {
 188     /* DLIL defined event, argument must be a pointer to a
 189        kern_event_msg structure. */
 190     kIONetworkEventTypeDLIL      = 0xff000001,
 191
 192     /* Link up event, no argument */
 193     kIONetworkEventTypeLinkUp    = 0xff000002,
 194
 195     /* Link down event, no argument */
 196     kIONetworkEventTypeLinkDown  = 0xff000003
 197 };
 198
 199 /*! @class IONetworkInterface : public IOService
 200     @abstract An IONetworkInterface object manages the connection between
 201     an IONetworkController and the data link interface layer (DLIL).
 202     All interactions between the controller and DLIL must go through an
 203     interface object. Any data structures that are required by DLIL for a
 204     particular interface type shall be allocated and mantained by the
 205     interface object. IONetworkInterface is an abstract class that must be
 206     extended by a concrete subclass to specialize for a particular network
 207     type.
 208
 209     Although most drivers will allocate a single interface object.
 210     It is possible for multiple interfaces to be attached to a single
 211     controller. This controller driver will be responsible for arbitrating
 212     access among its multiple interface clients.
 213
 214     IONetworkInterface also maintains a dictionary of IONetworkData
 215     objects containing statistics structures. Controller drivers can
 216     ask for a particular data object by name and update the
 217     statistics counters within directly. This dictionary is added to
 218     the interface's property table and is visible outside of the kernel. */
 219
 220 class IONetworkInterface : public IOService
 221 {
 222     OSDeclareAbstractStructors( IONetworkInterface )
 223
 224     friend class IONetworkStack;
 225
 226 private:
 227     IONetworkController *    _controller;
 228     struct ifnet *           _ifp;
 229     IORecursiveLock *        _ifLock;
 230     OSSet *                  _clientSet;
 231     OSNumber *               _stateBits;
 232     BPF_FUNC                 _inputFilterFunc;
 233     BPF_FUNC                 _outputFilterFunc;
 234     OSObject *               _outTarget;
 235     IOOutputAction           _outAction;
 236         UInt32                   _clientVar[4];
 237     OSDictionary *           _dataDict;
 238     struct mbuf *            _inputQHead;
 239     struct mbuf *            _inputQTail;
 240     UInt32                   _inputQCount;
 241
 242     struct ExpansionData { };
 243     /*! @var reserved
 244         Reserved for future use.  (Internal use only)  */
 245     ExpansionData *          _reserved;
 246
 247     bool _syncNetworkDataDict();
 248     bool _setInterfaceProperty(UInt32   value,
 249                                UInt32   mask,
 250                                UInt32   bytes,
 251                                void *   addr,
 252                                char *   name);
 253
 254     SInt32 syncSIOCSIFMEDIA(IONetworkController * ctlr, struct ifreq * ifr);
 255     SInt32 syncSIOCGIFMEDIA(IONetworkController * ctlr, struct ifreq * ifr);
 256     SInt32 syncSIOCSIFMTU(IONetworkController * ctlr, struct ifreq * ifr);
 257
 258     static int  performGatedCommand(void *, void *, void *, void *, void *);
 259     static int  ioctl_shim(struct ifnet * ifp, u_long cmd, caddr_t data);
 260     static int  set_bpf_tap_shim(struct ifnet * ifp, int mode, BPF_FUNC func);
 261     static int  free_shim(struct ifnet * ifp);
 262     static int  output_shim(struct ifnet * ifp, struct mbuf *m);
 263     static void null_shim(struct ifnet * ifp);
 264
 265     static IOReturn sControllerWillChangePowerState( IONetworkInterface *,
 266                                                      void *, void *,
 267                                                      void *, void *);
 268
 269     static IOReturn sControllerDidChangePowerState( IONetworkInterface *,
 270                                                     void *, void *,
 271                                                     void *, void *);
 272
 273 public:
 274
 275 /*! @function isPrimaryInterface
 276     @abstract Query whether the interface object provided represents
 277     the "primary" network interface for the system.
 278     @result true if the interface provided is the primary inteface,
 279     false otherwise. */
 280
 281     virtual bool isPrimaryInterface() const;
 282
 283 /*! @function init
 284     @abstract Initialize an IONetworkInterface object.
 285     @discussion Initialize instance variables, and allocate resources.
 286     Call getIfnet() to get the ifnet structure allocated by a concrete
 287     subclass, then call initIfnet() to initialize this ifnet structure.
 288     @param controller A network controller object that will service
 289     the interface object being initialized.
 290     @result true on success, false otherwise. */
 291
 292     virtual bool init( IONetworkController * controller );
 293
 294 /*! @function isRegistered
 295     @abstract Returns true if the interface has been registered with
 296     the data link layer.
 297     @discussion Once registered, the interface will be assigned a
 298     BSD name (such as en0), and a kIOBSDNameKey property is added to the
 299     property table containing this name. Calling this method performs
 300     the same function as checking for the kIONetworkInterfaceRegisteredState
 301     bit in the value returned by getInterfaceState().
 302     @result True if interface is registered. False if the data link layer
 303     has no references to this network interface, which implies that either the
 304     interface has yet to attach to the data link layer, or the interface has
 305     been detached. */
 306
 307     virtual bool isRegistered() const;
 308
 309 /*! @function getInterfaceState
 310     @abstract Report the current state of the interface object by returning
 311     the interface state flags.
 312     @result Returns the interface state flags. */
 313
 314     virtual UInt32 getInterfaceState() const;
 315
 316 /*! @function matchPropertyTable
 317     @abstract Override the implementation in IOService in order to
 318     implement family specific matching.
 319     @discussion When the gIOLocationMatchKey property is present in the
 320     dictionary provided, then fail the match unless the kIOBSDNameKey property
 321     is found. This is to prevent a premature match when hunting for a root
 322     device for BSD. The presence of the kIOBSDNameKey property indicates that
 323     the interface has registered with BSD, and is a valid candidate for
 324     matching against the gIOLocationMatchKey property. If the
 325     gIOLocationMatchKey property is absent, then this method will always
 326     return true.
 327     @param table The dictionary of properties to match against.
 328     @param score Pointer to the current driver's probe score, not used.
 329     @result Returns true for a positive match, false otherwise. */
 330
 331     virtual bool matchPropertyTable( OSDictionary *     table,
 332                                      SInt32       *     score );
 333
 334 /*! @function getController
 335     @abstract Return the provider, an IONetworkController object, that
 336     is servicing this interface object.
 337     @discussion This is the same controller object that was supplied as
 338     an argument to the init() method.
 339     @result The IONetworkController object that is providing service to
 340     this interface object. */
 341
 342     virtual IONetworkController * getController() const;
 343
 344 /*! @function inputPacket
 345     @abstract Called by the network controller to submit a single packet
 346     received from the network to the data link layer.
 347     @discussion The packet received by this method may be added to an input
 348     queue on the interface object, which the controller can use to postpone
 349     the packet handoff to the upper layers, until all received packets have
 350     been transferred to the input queue. A subsequent call to flushInputQueue(),
 351     will transfer the entire contents of the queue to the data link layer,
 352     by making a single call to dlil_input(). Other methods that can be used
 353     to manage the input queue are flushInputQueue() and clearInputQueue().
 354     This input queue is not protected by a lock. Access to the queue by the
 355     controller must be serialized, otherwise its use must be avoided.
 356     @param m The mbuf containing the received packet.
 357     @param length Specify the size of the received packet in the mbuf.
 358            The mbuf length fields are updated with this value. If zero,
 359            then the mbuf length fields are not updated.
 360     @param options Options defined by inputPacket() that the caller
 361            can use to specify this method call.
 362     @param param A parameter provided by the caller. Not used by
 363            IONetworkInterface.
 364     @result The number of packets that were submitted to the data link layer,
 365             or 0 if the packet was queued. */
 366
 367     virtual UInt32 inputPacket(struct mbuf * m,
 368                                UInt32        length  = 0,
 369                                IOOptionBits  options = 0,
 370                                void *        param   = 0);
 371
 372 /*! @enum Options for the inputPacket() method.
 373     @discussion An enumeration of the option bits that can be specified
 374     in the options argument when calling inputPacket().
 375     @constant kInputOptionQueuePacket Keep the packet provided in the
 376     input packet queue. No packets are sent to the data link layers,
 377     and the caller's thread will not venture outside the interface
 378     object. Calls to inputPacket() must be serialized. */
 379
 380     enum {
 381         kInputOptionQueuePacket = 0x1
 382     };
 383
 384 /*! @function flushInputQueue
 385     @abstract Send all packets held in the input queue to the data
 386     link layer.
 387     @discussion Remove all packets from the input queue and
 388     send them to the data link layer by calling dlil_input(). This
 389     method should be used in connection with the inputPacket() method,
 390     to flush the input queue after inputPacket() was used to queue up
 391     some number of received packets. See inputPacket() and clearInputQueue().
 392     @result The number of packets that were submitted to the data link layer.
 393             May be zero if the queue was empty. */
 394
 395     virtual UInt32 flushInputQueue();
 396
 397 /*! @function clearInputQueue
 398     @abstract Remove and discard all packets in the input queue.
 399     @discussion Remove all packets from the input queue and
 400     release them back to the free mbuf pool. Also see flushInputQueue().
 401     @result The number of packets freed. */
 402
 403     virtual UInt32 clearInputQueue();
 404
 405 /*! @function inputEvent
 406     @abstract Send an event to the data link layer.
 407     @discussion This method can be used by the network controller to
 408     send an event to the data link layer.
 409     @param type A constant describing the event type.
 410     @param data Data associated with the event.
 411     @result true if the event was delivered, false if the event type
 412     specified is invalid, or if the event delivery was unsuccesful. */
 413
 414     virtual bool inputEvent(UInt32 type, void * data);
 415
 416 /*! @function registerOutputHandler
 417     @abstract Register a target/action to handle output packets.
 418     @discussion The interface object will forward all output packets,
 419     received from the data link layer, to the output handler registered
 420     through this method. The default target and action are set by the init()
 421     method to the controller, and the handler returned by the controller's
 422     getOutputHandler() method. Once the interface becomes registered with
 423     the data link layer, this method will return false and will reject any
 424     further changes.
 425     @param target Target object that implements the output handler.
 426     @param action The function that will process output packets.
 427     @result true if the target/action provided was accepted,
 428     false otherwise. */
 429
 430     virtual bool registerOutputHandler(OSObject *      target,
 431                                        IOOutputAction  action);
 432
 433 /*! @function getNamePrefix
 434     @abstract Return a string containing the prefix to use when
 435     creating a BSD name for this interface.
 436     @discussion The BSD name for each interface object is generated by
 437     concatenating a string returned by this method, with an unique
 438     unit number assigned by IONetworkStack.
 439     A concrete subclass of IONetworkInterface must implement this method
 440     and enforce a consistent name for all of its instances.
 441     @result A pointer to a constant C string. */
 442
 443     virtual const char * getNamePrefix() const = 0;
 444
 445 /*! @function getInterfaceType
 446     @abstract Get the interface type.
 447     @discussion Return the value in the if_type field in the ifnet structure.
 448     @result A constant defined in bsd/net/if_types.h header file
 449     that describes the interface type. */
 450
 451     virtual UInt8  getInterfaceType() const;
 452
 453 /*! @function getMaxTransferUnit
 454     @abstract Get the maximum transfer unit for this interface.
 455     @discussion Return the value in the if_mtu field in the ifnet structure.
 456     @result The interface MTU size in bytes. */
 457
 458     virtual UInt32 getMaxTransferUnit() const;
 459
 460 /*! @function getFlags
 461     @abstract Get the value of the interface flags.
 462     @discussion Return the value in the if_flags field in the ifnet structure.
 463     @result The value of the interface flags. */
 464
 465     virtual UInt16 getFlags() const;
 466
 467 /*! @function getExtraFlags
 468     @abstract Get the value of the interface extra flags.
 469     @discussion Return the value in the if_eflags field in the ifnet structure.
 470     @result The value of the interface extra flags. */
 471
 472     virtual UInt32 getExtraFlags() const;
 473
 474 /*! @function getMediaAddressLength
 475     @abstract Get the size of the media (MAC-layer) address.
 476     @discussion Return the value in the if_addrlen field in the ifnet structure.
 477     @result The size of the media address in bytes. */
 478
 479     virtual UInt8  getMediaAddressLength() const;
 480
 481 /*! @function getMediaHeaderLength
 482     @abstract Get the size of the media header.
 483     @discussion Return the value in the if_hdrlen field in the ifnet structure.
 484     @result The size of the media header in bytes. */
 485
 486     virtual UInt8  getMediaHeaderLength() const;
 487
 488 /*! @function getUnitNumber
 489     @abstract Get the unit number assigned to this interface object.
 490     @discussion Return the value in the if_unit field in the ifnet structure.
 491     @result The assigned interface unit number. */
 492
 493     virtual UInt16 getUnitNumber() const;
 494
 495 /*! @function addNetworkData
 496     @abstract Add an IONetworkData object to a dictionary managed by
 497     the interface.
 498     @param aData An IONetworkData object to be added to a dictionary
 499     managed by the interface. This object is retained by the dictionary.
 500     @result true if the operation was successful, false otherwise. */
 501
 502     virtual bool addNetworkData(IONetworkData * aData);
 503
 504 /*! @function removeNetworkData
 505     @abstract Remove an entry from the IONetworkData dictionary
 506     managed by the interface. The removed object is released.
 507     @param aKey A unique OSSymbol identifying the IONetworkData object
 508            to be removed from the dictionary.
 509     @result true if the operation was successful, false otherwise. */
 510
 511     virtual bool removeNetworkData(const OSSymbol * aKey);
 512
 513 /*! @function removeNetworkData
 514     @abstract Remove an entry from the IONetworkData dictionary
 515     managed by the interface. The removed object is released.
 516     @param aKey A unique string identifying the IONetworkData object
 517            to be removed from the dictionary.
 518     @result true if the operation was successful, false otherwise. */
 519
 520     virtual bool removeNetworkData(const char * aKey);
 521
 522 /*! @function getNetworkData
 523     @abstract Get an IONetworkData object from the interface that is
 524     associated with the given key.
 525     @param aKey The unique string identifying the IONetworkData object to be
 526     returned to caller.
 527     @result Returns a reference to the matching IONetworkData object,
 528     or 0 if no match was found. */
 529
 530     virtual IONetworkData * getNetworkData(const char * aKey) const;
 531
 532 /*! @function getNetworkData
 533     @abstract Get an IONetworkData object from the interface that is
 534     associated with the given key.
 535     @param aKey The unique OSSymbol identifying the IONetworkData object to be
 536     returned to caller.
 537     @result Returns a reference to the matching IONetworkData object,
 538     or 0 if no match was found. */
 539
 540     virtual IONetworkData * getNetworkData(const OSSymbol * aKey) const;
 541
 542     // FIXME - Compatibility methods (to be removed)
 543     inline IONetworkData * getParameter(const char * aKey) const
 544     { return getNetworkData(aKey); }
 545
 546     inline bool setExtendedFlags(UInt32 flags, UInt32 clear = 0)
 547     { return true; }
 548
 549 protected:
 550
 551 /*! @function setInterfaceType
 552     @abstract Set the interface type.
 553     @discussion Both the if_type field in the ifnet structure, and the
 554     kIOInterfaceType property are updated with the value provided.
 555     @param type A constant defined in bsd/net/if_types.h header file
 556     that describes the interface type.
 557     @result true if the update was successful, false otherwise. */
 558
 559     virtual bool setInterfaceType(UInt8 type);
 560
 561 /*! @function setMaxTransferUnit
 562     @abstract Set the maximum transfer unit for this interface.
 563     @discussion Both the if_mtu field in the ifnet structure, and the
 564     kIOMaxTransferUnit property are updated with the value provided.
 565     @param mtu The interface MTU size in bytes.
 566     @result true if the update was successful, false otherwise. */
 567
 568     virtual bool setMaxTransferUnit(UInt32 mtu);
 569
 570 /*! @function setFlags
 571     @abstract Perform a read-modify-write operation on the current
 572     interface flags value.
 573     @discussion See bsd/net/if.h header file for the definition of the
 574     flag constants. Both the if_flags field in the ifnet structure, and
 575     the kIOInterfaceFlags property are updated with the value provided.
 576     @param flags The bits that should be set.
 577     @param clear The bits that should be cleared. If 0, then non
 578     of the flags are cleared and the result is formed by OR'ing the
 579     original flags value with the new flags.
 580     @result true if the update was successful, false otherwise. */
 581
 582     virtual bool setFlags(UInt16 flags, UInt16 clear = 0);
 583
 584 /*! @function setExtraFlags
 585     @abstract Perform a read-modify-write operation on the current
 586     interface extra flags value.
 587     @discussion See bsd/net/if.h header file for the definition of the
 588     extra flag constants. Both the if_eflags field in the ifnet structure,
 589     and the kIOInterfaceExtraFlags property are updated with the value
 590     provided.
 591     @param flags The bits that should be set.
 592     @param flags The bits that should be set.
 593     @param clear The bits that should be cleared. If 0, then non
 594     of the flags are cleared and the result is formed by OR'ing the
 595     original flags with the new flags.
 596     @result true if the update was successful, false otherwise. */
 597
 598     virtual bool setExtraFlags(UInt32 flags, UInt32 clear = 0);
 599
 600 /*! @function setMediaAddressLength
 601     @abstract Set the size of the media (MAC-layer) address.
 602     @discussion Both the if_addrlen field in the ifnet structure, and the
 603     kIOMediaAddressLength property are updated with the value provided.
 604     @param length The size of the media address in bytes.
 605     @result true if the update was successful, false otherwise. */
 606
 607     virtual bool setMediaAddressLength(UInt8 length);
 608
 609 /*! @function setMediaHeaderLength
 610     @abstract Set the size of the media header.
 611     @discussion Both the if_hdrlen field in the ifnet structure, and the
 612     kIOMediaHeaderLength property are updated with the value provided.
 613     @param length The size of the media header in bytes.
 614     @result true if the update was successful, false otherwise. */
 615
 616     virtual bool setMediaHeaderLength(UInt8 length);
 617
 618 /*! @function setUnitNumber
 619     @abstract Assign an unique unit number to this interface.
 620     @discussion This method is called by IONetworkStack before the
 621     interface is registered with the data link layer, to assign an
 622     unique unit number to the interface object. Both the if_unit field
 623     in the ifnet structure, and the kIOInterfaceUnit property are updated
 624     with the value provided.
 625     @param unit The unit number assigned to this interface object.
 626     @result true if the update was successful, false otherwise. */
 627
 628     virtual bool setUnitNumber(UInt16 unit);
 629
 630 /*! @function free
 631     @abstract Free the IONetworkInterface object.
 632     @discussion Resource allocated by init() are released, and
 633     clearInputQueue() is called to ensure that the input queue is empty. */
 634
 635     virtual void free();
 636
 637 /*! @function handleOpen
 638     @abstract Handle a client open on the interface.
 639     @discussion This method is called by IOService::open() with the
 640     arbitration lock held, and must return true to accept the client open.
 641     This method will in turn call handleClientOpen() to qualify the client
 642     requesting the open. Since the controller is opened by the interface
 643     in a lazy fashion, the interface may also perform an open on the
 644     controller before this method returns. If the controller was opened,
 645     then controllerDidOpen() is called to notify interested subclasses.
 646     Subclasses should not override this method.
 647     @param client The client object that requested the open.
 648     @param options Options passed to IOService::open().
 649     @param argument Argument passed to IOService::open().
 650     @result true to accept the client open, false otherwise. */
 651
 652     virtual bool handleOpen(IOService *  client,
 653                             IOOptionBits options,
 654                             void *       argument);
 655
 656 /*! @function handleClose
 657     @abstract Handle a client close on the interface.
 658     @discussion This method is called by IOService::close() with the
 659     arbitration lock held. This method will in turn call handleClientClose()
 660     to notify interested subclasses about the client close. If this represents
 661     the last close, then the interface will also close the controller before
 662     this method returns. The controllerWillClose() method will be called before
 663     closing the controller. Subclasses should not override this method.
 664     @param client The client object that requested the close.
 665     @param options Options passed to IOService::close(). */
 666
 667     virtual void handleClose(IOService * client, IOOptionBits options);
 668
 669 /*! @function handleIsOpen
 670     @abstract Query whether a client has an open on the interface.
 671     @discussion This method is always called by IOService with the
 672     arbitration lock held. Subclasses should not override this method.
 673     @result true if the specified client, or any client if none (0) is
 674     specified, presently has an open on this object. */
 675
 676     virtual bool handleIsOpen(const IOService * client) const;
 677
 678 /*! @function lock
 679     @abstract Take the network interface lock.
 680     @discussion Take the recursive lock that protects the interface
 681     state. All updates to the interface state and to the ifnet structure
 682     must be performed while holding this lock. This call must be balanced
 683     by a subsequent call to unlock(). */
 684
 685     virtual void lock();
 686
 687 /*! @function unlock
 688     @abstract Release the network interface lock.
 689     @discussion Release the recursive lock that protects the interface
 690     state to balance a previous lock() call. */
 691
 692     virtual void unlock();
 693
 694 /*! @function controllerDidOpen
 695     @abstract A notification that the interface has opened the network
 696     controller.
 697     @discussion Called by handleOpen() to notify subclasses that the
 698     controller has been opened. The open on the controller is done when
 699     the interface receives the initial open request from a client.
 700     Subclasses can override this method and inspect the controller before
 701     allowing the client open. The implementation in the subclass must first
 702     call the method in super and check the return value. This method is
 703     called with our arbitration lock held, hence issuing I/O to the
 704     controller must be avoided to eliminate the possibility of a
 705     deadlock.
 706     @param controller The controller that was opened.
 707     @result Must return true in order for handleOpen() to accept
 708     the client open. If the return is false, then the controller will be
 709     closed and the client open will be refused. */
 710
 711     virtual bool controllerDidOpen(IONetworkController * controller);
 712
 713 /*! @function controllerWillClose
 714     @abstract A notification that the interface will close the network
 715     controller.
 716     @discussion Called by handleClose() after receiving a close from the
 717     last client, and just before the controller is closed. Subclasses
 718     can override this method to perform any cleanup action before the
 719     controller is closed. This method is called with our arbitration lock
 720     held, hence issuing I/O to the controller must be avoided to eliminate
 721     the possibility of a deadlock.
 722     @param controller The controller that is about to be closed. */
 723
 724     virtual void controllerWillClose(IONetworkController * controller);
 725
 726 /*! @function performCommand
 727     @abstract Handle an ioctl command sent to the network interface.
 728     @discussion This method handles socket ioctl commands sent to the
 729     network interface from DLIL.
 730     IONetworkInterface handles commands that are common for all network
 731     interface types. A subclass of IONetworkInterface may override this
 732     method to override the command handling in IONetworkInterface, or
 733     to extend the command processing to handle additional commands,
 734     and then call super for any commands not handled in the subclass.
 735     The ioctl commands handled by IONetworkInterface are
 736         SIOCGIFMTU (Get interface MTU size),
 737         SIOCSIFMTU (Set interface MTU size),
 738         SIOCSIFMEDIA (Set media), and
 739         SIOCGIFMEDIA (Get media and link status).
 740     @param controller The controller object.
 741     @param cmd The ioctl command code.
 742     @param arg0 Command argument 0. Generally a pointer to an ifnet structure
 743         associated with the interface.
 744     @param arg1 Command argument 1.
 745     @result A BSD return value defined in bsd/sys/errno.h. */
 746
 747     virtual SInt32 performCommand(IONetworkController * controller,
 748                                   UInt32                cmd,
 749                                   void *                arg0,
 750                                   void *                arg1);
 751
 752 /*! @function getIfnet
 753     @abstract Get the ifnet structure allocated by the interface object.
 754     @discussion Request an interface to reveal its ifnet structure.
 755     A concrete subclass must allocate an ifnet structure when the
 756     object is initialized, and return a pointer to the ifnet structure
 757     when this method is called.
 758     @result Pointer to an ifnet structure allocated by a concrete
 759     interface subclass. */
 760
 761     virtual struct ifnet * getIfnet() const = 0;
 762
 763 /*! @function initIfnet
 764     @abstract Initialize the ifnet structure given.
 765     @discussion A concrete subclass must override this method and initialize
 766     the ifnet structure given. The implementation in the subclass must call
 767     super before it returns, to allow IONetworkInterface to complete the
 768     initialization, and to insert the BSD shim functions implemented in
 769     IONetworkInterface to the appropriate function pointer fields in the
 770     ifnet structure. IONetworkInterface will call this method during its
 771     init() method. Subclasses are encouraged to use the ifnet accessor
 772     methods to update the ifnet structure when possible, since this will
 773     ensure that properties in the registry will also be updated to reflect
 774     any changes made.
 775     @param ifp Pointer to an ifnet structure obtained earlier through
 776                the getIfnet() method call.
 777     @result true on success, false otherwise. */
 778
 779     virtual bool initIfnet(struct ifnet * ifp);
 780
 781 /*! @function handleClientOpen
 782     @abstract Handle a client open on the interface.
 783     @discussion Called by handleOpen() to handle an open from a client object.
 784     Unlike handleOpen(), subclasses may override this method to catch an open
 785     request from a client. This method is called with the arbitration lock held.
 786     @param client The client object requesting the open.
 787     @param options Options passed to IONetworkInterface::handleOpen().
 788     @param argument Argument passed to IONetworkInterface::handleOpen().
 789     @result true to accept the client open, false to refuse it. */
 790
 791     virtual bool handleClientOpen(IOService *  client,
 792                                   IOOptionBits options,
 793                                   void *       argument);
 794
 795 /*! @function handleClientClose
 796     @abstract Handle a client close on the interface.
 797     @discussion Called by handleClose() to handle a close from a client object.
 798     Unlike handleClose(), subclasses may override this method to catch a close
 799     reuqest from a client. This method is called with the arbitration lock held.
 800     @param client The client object requesting the close.
 801     @param options Options passed to IONetworkInterface::handleClose(). */
 802
 803     virtual void handleClientClose(IOService *  client,
 804                                    IOOptionBits options);
 805
 806 /*! @function newUserClient
 807     @abstract A request to create a connection for a non kernel client.
 808     @discussion Create a new IOUserClient to service a connection to a
 809     non kernel client.
 810     @param owningTask The mach task requesting the connection.
 811     @param security_id A token representing the access level for the task.
 812     @param type A constant specifying the type of connection to be created.
 813     An IONetworkUserClient object is created if the type specified is
 814     kIONetworkUserClientTypeID.
 815     @param handler The IOUserClient object returned.
 816     @result kIOReturnSuccess if an IONetworkUserClient was created,
 817     kIOReturnNoMemory for a memory allocation error, or
 818     kIOReturnBadArgument if the type specified is unknown. */
 819
 820     virtual IOReturn newUserClient(task_t           owningTask,
 821                                    void *           security_id,
 822                                    UInt32           type,
 823                                    IOUserClient **  handler);
 824
 825 /*! @function setInterfaceState
 826     @abstract Update the interface object state flags.
 827     @discussion The kIOInterfaceState property is updated with the value
 828     provided.
 829     @param flags The bits that should be set.
 830     @param clear The bits that should be cleared.
 831     @result The resulting interface state flags following any changes
 832     made by this method. */
 833
 834     virtual UInt32 setInterfaceState( UInt32 set, UInt32 clear = 0 );
 835
 836 /*! @function powerStateWillChangeTo
 837     @abstract Handle a notification that the network controller which is servicing
 838     this interface object is about to transition to a new power state.
 839     @discussion This method will call the controllerWillChangePowerState() method
 840     on the controller's work loop context to prepare for the power state change.
 841     Subclasses should not override this method.
 842     @param flags Flags that describe the capability of the controller in the new
 843     power state.
 844     @param stateNumber An index to a state in the network controller's
 845     power state array that the controller is switching to.
 846     @param policyMaker A reference to the network controller's policy-maker,
 847     and is also the originator of this notification.
 848     @result The return will always be IOPMAckImplied to indicate that the
 849     preparation for the power change has already completed when this method
 850     returns. */
 851
 852     virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags  flags,
 853                                              UInt32          stateNumber,
 854                                              IOService *     policyMaker );
 855
 856 /*! @function powerStateDidChangeTo
 857     @abstract Handle a notification that the network controller which is servicing
 858     this interface object has transitioned to a new power state.
 859     @discussion This method will call the controllerDidChangePowerState() method
 860     on the controller's work loop context to prepare for the power state change.
 861     Subclasses should not override this method.
 862     @param flags Flags that describe the capability of the controller in the new
 863     power state.
 864     @param stateNumber An index to a state in the network controller's
 865     power state array that the controller has switched to.
 866     @param policyMaker A reference to the network controller's policy-maker,
 867     and is also the originator of this notification.
 868     @result The return will always be IOPMAckImplied to indicate that the
 869     preparation for the power change has already completed when this method
 870     returns. */
 871
 872     virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags  flags,
 873                                             UInt32          stateNumber,
 874                                             IOService *     policyMaker );
 875
 876 /*! @function controllerWillChangePowerState
 877     @abstract Handle a notification that the network controller which is servicing
 878     this interface object is about to transition to a new power state.
 879     @param controller The network controller object.
 880     @param flags Flags that describe the capability of the controller in the new
 881     power state.
 882     @param stateNumber An index to a state in the network controller's
 883     power state array that the controller is switching to.
 884     @param policyMaker A reference to the network controller's policy-maker,
 885     and is also the originator of this notification.
 886     @result The return value is always kIOReturnSuccess. */
 887
 888     virtual IOReturn controllerWillChangePowerState(
 889                                IONetworkController * controller,
 890                                IOPMPowerFlags        flags,
 891                                UInt32                stateNumber,
 892                                IOService *           policyMaker);
 893
 894 /*! @function controllerDidChangePowerState
 895     @abstract Handle a notification that the network controller which is servicing
 896     this interface object has transitioned to a new power state.
 897     @param controller The network controller object.
 898     @param flags Flags that describe the capability of the controller in the new
 899     power state.
 900     @param stateNumber An index to a state in the network controller's
 901     power state array that the controller has switched to.
 902     @param policyMaker A reference to the network controller's policy-maker,
 903     and is also the originator of this notification.
 904     @result The return value is always kIOReturnSuccess. */
 905
 906     virtual IOReturn controllerDidChangePowerState(
 907                                IONetworkController * controller,
 908                                IOPMPowerFlags        flags,
 909                                UInt32                stateNumber,
 910                                IOService *           policyMaker);
 911
 912     // Virtual function padding
 913     OSMetaClassDeclareReservedUnused( IONetworkInterface,  0);
 914     OSMetaClassDeclareReservedUnused( IONetworkInterface,  1);
 915     OSMetaClassDeclareReservedUnused( IONetworkInterface,  2);
 916     OSMetaClassDeclareReservedUnused( IONetworkInterface,  3);
 917     OSMetaClassDeclareReservedUnused( IONetworkInterface,  4);
 918     OSMetaClassDeclareReservedUnused( IONetworkInterface,  5);
 919     OSMetaClassDeclareReservedUnused( IONetworkInterface,  6);
 920     OSMetaClassDeclareReservedUnused( IONetworkInterface,  7);
 921     OSMetaClassDeclareReservedUnused( IONetworkInterface,  8);
 922     OSMetaClassDeclareReservedUnused( IONetworkInterface,  9);
 923     OSMetaClassDeclareReservedUnused( IONetworkInterface, 10);
 924     OSMetaClassDeclareReservedUnused( IONetworkInterface, 11);
 925     OSMetaClassDeclareReservedUnused( IONetworkInterface, 12);
 926     OSMetaClassDeclareReservedUnused( IONetworkInterface, 13);
 927     OSMetaClassDeclareReservedUnused( IONetworkInterface, 14);
 928     OSMetaClassDeclareReservedUnused( IONetworkInterface, 15);
 929 };
 930
 931 #endif /* defined(KERNEL) && defined(__cplusplus) */
 932
 933 #endif /* !_IONETWORKINTERFACE_H */