iokit/IOKit/network/IOEthernetInterface.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  * IOEthernetInterface.h
  26  *
  27  * HISTORY
  28  * 8-Jan-1999       Joe Liu (jliu) created.
  29  */
  30
  31 #ifndef _IOETHERNETINTERFACE_H
  32 #define _IOETHERNETINTERFACE_H
  33
  34 /*! @defined kIOEthernetInterfaceClass
  35     @abstract kIOEthernetInterfaceClass is the name of the
  36         IOEthernetInterface class. */
  37
  38 #define kIOEthernetInterfaceClass     "IOEthernetInterface"
  39
  40 /*! @defined kIOActivePacketFilters
  41     @abstract kIOActivePacketFilters is a property of IOEthernetInterface
  42         objects. It has an OSDictionary value.
  43     @discussion The kIOActivePacketFilters property describes the current
  44         set of packet filters that have been successfully activated. Each
  45         entry in the dictionary is a key/value pair consisting of the filter
  46         group name, and an OSNumber describing the set of active filters for
  47         that group. Entries in this dictionary will mirror those in
  48         kIORequiredPacketFilters if the controller has reported success for
  49         all filter change requests from the IOEthernetInterface object. */
  50
  51 #define kIOActivePacketFilters        "IOActivePacketFilters"
  52
  53 /*! @defined kIORequiredPacketFilters
  54     @abstract kIORequiredPacketFilters is a property of IOEthernetInterface
  55         objects. It has an OSDictionary value.
  56     @discussion The kIORequiredPacketFilters property describes the current
  57         set of required packet filters. Each entry in the dictionary is a
  58         key/value pair consisting of the filter group name, and an OSNumber
  59         describing the set of required filters for that group. */
  60
  61 #define kIORequiredPacketFilters      "IORequiredPacketFilters"
  62
  63 /*! @defined kIOMulticastAddressList
  64     @abstract kIOMulticastAddressList is a property of IOEthernetInterface
  65         objects. It is an OSData object.
  66     @discussion The kIOMulticastAddressList property describes the
  67         list of multicast addresses that are being used by the
  68         controller to match against the destination address of an
  69         incoming frame. */
  70
  71 #define kIOMulticastAddressList       "IOMulticastAddressList"
  72 #define kIOMulticastFilterData        kIOMulticastAddressList
  73
  74 /*
  75  * Kernel
  76  */
  77 #if defined(KERNEL) && defined(__cplusplus)
  78
  79 #include <IOKit/network/IONetworkInterface.h>
  80 #include <IOKit/network/IOEthernetController.h>
  81 #include <IOKit/network/IOEthernetStats.h>
  82
  83 /*! @class IOEthernetInterface : public IONetworkInterface
  84     @abstract The Ethernet interface object. An Ethernet controller driver,
  85     that is a subclass of IOEthernetController, will instantiate an object
  86     of this class when the driver calls the attachInterface() method.
  87     This interface object will then vend an Ethernet interface to DLIL,
  88     and manage the connection between the controller driver and the upper
  89     networking layers. Drivers will seldom need to subclass
  90     IOEthernetInterface. */
  91
  92 class IOEthernetInterface : public IONetworkInterface
  93 {
  94     OSDeclareDefaultStructors( IOEthernetInterface )
  95
  96 private:
  97     struct arpcom *  _arpcom;               // Arpcom struct allocated
  98     UInt32           _mcAddrCount;          // # of multicast addresses
  99     bool             _ctrEnabled;           // Is controller enabled?
 100     OSDictionary *   _supportedFilters;     // Controller's supported filters
 101     OSDictionary *   _requiredFilters;      // The required filters
 102     OSDictionary *   _activeFilters;        // Currently active filters
 103     bool             _controllerLostPower;  // true if controller is unusable
 104
 105     struct ExpansionData { };
 106     /*! @var reserved
 107         Reserved for future use.  (Internal use only)  */
 108     ExpansionData *  _reserved;
 109
 110
 111     IOReturn enableController(IONetworkController * ctr);
 112     IOReturn setupMulticastFilter(IONetworkController * ctr);
 113
 114     UInt32 getFilters(const OSDictionary * dict,
 115                       const OSSymbol *     group);
 116
 117     bool setFilters(OSDictionary *   dict,
 118                     const OSSymbol * group,
 119                     UInt32           filters);
 120
 121     IOReturn disableFilter(IONetworkController * ctr,
 122                            const OSSymbol *      group,
 123                            UInt32                filter,
 124                            IOOptionBits          options = 0);
 125
 126     IOReturn enableFilter(IONetworkController * ctr,
 127                           const OSSymbol *      group,
 128                           UInt32                filter,
 129                           IOOptionBits          options = 0);
 130
 131     int syncSIOCSIFFLAGS(IONetworkController * ctr);
 132     int syncSIOCSIFADDR(IONetworkController * ctr);
 133     int syncSIOCADDMULTI(IONetworkController * ctr);
 134     int syncSIOCDELMULTI(IONetworkController * ctr);
 135
 136     static int performGatedCommand(void *, void *, void *, void *, void *);
 137
 138 public:
 139
 140 /*! @function init
 141     @abstract Initialize an IOEthernetInterface instance.
 142     @discussion Instance variables are initialized, and an arpcom
 143     structure is allocated.
 144     @param controller A network controller object that will service
 145     the interface object being initialized.
 146     @result true on success, false otherwise. */
 147
 148     virtual bool init( IONetworkController * controller );
 149
 150 /*! @function getNamePrefix
 151     @abstract Return a string containing the prefix to use when
 152     creating a BSD name for this interface.
 153     @discussion The BSD name for each interface object is created by
 154     concatenating a string returned by this method, with an unique
 155     unit number assigned by IONetworkStack.
 156     @result A pointer to a constant C string "en". Therefore, Ethernet
 157     interfaces will be registered with BSD as en0, en1, etc. */
 158
 159     virtual const char * getNamePrefix() const;
 160
 161 protected:
 162
 163 /*! @function free
 164     @abstract Free the IOEthernetInterface instance.
 165     @discussion The memory allocated for the arpcom structure is released,
 166     followed by a call to super::free(). */
 167
 168     virtual void free();
 169
 170 /*! @function performCommand
 171     @abstract Handle an ioctl command sent to the Ethernet interface.
 172     @discussion This method handles socket ioctl commands sent to the Ethernet
 173     interface from DLIL. Commands recognized and processed by this method are
 174     SIOCSIFADDR, SIOCSIFFLAGS, SIOCADDMULTI, and SIOCDELMULTI. Other commands
 175     are passed to the superclass.
 176     @param controller The controller object.
 177     @param cmd  The ioctl command code.
 178     @param arg0 Command argument 0. Generally a pointer to an ifnet structure
 179         associated with the interface.
 180     @param arg1 Command argument 1.
 181     @result A BSD return value defined in bsd/sys/errno.h. */
 182
 183     virtual SInt32 performCommand(IONetworkController * controller,
 184                                   UInt32                cmd,
 185                                   void *                arg0,
 186                                   void *                arg1);
 187
 188 /*! @function controllerDidOpen
 189     @abstract A notification that the interface has opened the network
 190     controller.
 191     @discussion This method will be called by IONetworkInterface after a
 192     network controller has accepted an open from this interface object.
 193     IOEthernetInterface will first call the implementation in its
 194     superclass, then inspect the controller through properties published
 195     in the registry. This method is called with the arbitration lock held.
 196     @param controller The controller object that was opened.
 197     @result true on success, false otherwise. Returning false will
 198     cause the controller to be closed, and any pending client opens to be
 199     rejected. */
 200
 201     virtual bool controllerDidOpen(IONetworkController * controller);
 202
 203 /*! @function controllerWillClose
 204     @abstract A notification that the interface will close the network
 205     controller.
 206     @discussion This method will simply call super to propagate the method
 207     call. This method is called with the arbitration lock held.
 208     @param controller The controller that is about to be closed. */
 209
 210     virtual void controllerWillClose(IONetworkController * controller);
 211
 212 /*! @function initIfnet
 213     @abstract Initialize the ifnet structure given.
 214     @discussion IOEthernetInterface will initialize this structure in a manner
 215     that is appropriate for Ethernet interfaces, then call super::initIfnet()
 216     to allow the superclass to perform generic interface initialization.
 217     @param ifp Pointer to an ifnet structure obtained earlier through
 218                the getIfnet() method call.
 219     @result true on success, false otherwise. */
 220
 221     virtual bool initIfnet(struct ifnet * ifp);
 222
 223 /*! @function getIfnet
 224     @abstract Get the ifnet structure allocated by the interface object.
 225     @discussion This method returns a pointer to an ifnet structure
 226     that was allocated by a concrete subclass of IONetworkInterface.
 227     IOEthernetInterface will allocate an arpcom structure during init(),
 228     and returns a pointer to that structure when this method is called.
 229     @result Pointer to an ifnet structure. */
 230
 231     virtual struct ifnet * getIfnet() const;
 232
 233 /*! @function controllerWillChangePowerState
 234     @abstract Handle a notification that the network controller which is
 235     servicing this interface object is about to transition to a new power state.
 236     @discussion If the controller is about to transition to an unusable state,
 237     and it is currently enabled, then the disable() method on the controller is
 238     called.
 239     @param controller The network controller object.
 240     @param flags Flags that describe the capability of the controller in the new
 241     power state.
 242     @param stateNumber An index to a state in the network controller's
 243     power state array that the controller is switching to.
 244     @param policyMaker A reference to the network controller's policy-maker,
 245     and is also the originator of this notification.
 246     @result The return value is always kIOReturnSuccess. */
 247
 248     virtual IOReturn controllerWillChangePowerState(
 249                                IONetworkController * controller,
 250                                IOPMPowerFlags        flags,
 251                                UInt32                stateNumber,
 252                                IOService *           policyMaker);
 253
 254 /*! @function controllerDidChangePowerState
 255     @abstract Handle a notification that the network controller which is servicing
 256     this interface object has transitioned to a new power state.
 257     @discussion If the controller did transition to a usable state, and it was
 258     previously disabled due to a previous power change, then it is re-enabled.
 259     @param controller The network controller object.
 260     @param flags Flags that describe the capability of the controller in the new
 261     power state.
 262     @param stateNumber An index to a state in the network controller's
 263     power state array that the controller has switched to.
 264     @param policyMaker A reference to the network controller's policy-maker,
 265     and is also the originator of this notification.
 266     @result The return value is always kIOReturnSuccess. */
 267
 268     virtual IOReturn controllerDidChangePowerState(
 269                                IONetworkController * controller,
 270                                IOPMPowerFlags        flags,
 271                                UInt32                stateNumber,
 272                                IOService *           policyMaker);
 273
 274
 275     // Virtual function padding
 276     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  0);
 277     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  1);
 278     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  2);
 279     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  3);
 280     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  4);
 281     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  5);
 282     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  6);
 283     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  7);
 284     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  8);
 285     OSMetaClassDeclareReservedUnused( IOEthernetInterface,  9);
 286     OSMetaClassDeclareReservedUnused( IOEthernetInterface, 10);
 287     OSMetaClassDeclareReservedUnused( IOEthernetInterface, 11);
 288     OSMetaClassDeclareReservedUnused( IOEthernetInterface, 12);
 289     OSMetaClassDeclareReservedUnused( IOEthernetInterface, 13);
 290     OSMetaClassDeclareReservedUnused( IOEthernetInterface, 14);
 291     OSMetaClassDeclareReservedUnused( IOEthernetInterface, 15);
 292 };
 293
 294 #endif /* defined(KERNEL) && defined(__cplusplus) */
 295
 296 #endif /* !_IOETHERNETINTERFACE_H */