Root/
| Source at commit 2862 created 7 years 22 days ago. By ifabio, Tag 2.3 release, bump svn to 2.4 | |
|---|---|
| 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␊ |
| 34 | objects. ␊ |
| 35 | @discussion The kIONetworkData property has an OSDictionary value and is a container for the␊ |
| 36 | set of IONetworkData objects managed by the interface.␊ |
| 37 | Each entry in the dictionary is a key/value pair consisting of␊ |
| 38 | the network data name, and an OSDictionary describing the␊ |
| 39 | contents of the network data. ␊ |
| 40 | */␊ |
| 41 | ␊ |
| 42 | #define kIONetworkData "IONetworkData"␊ |
| 43 | ␊ |
| 44 | /*! @defined kIOInterfaceType␊ |
| 45 | @abstract A property of IONetworkInterface objects.␊ |
| 46 | @discussion The kIOInterfaceType property has an OSNumber value that specifies the type of␊ |
| 47 | network interface that this interface represents. The type␊ |
| 48 | constants are defined in bsd/net/if_types.h. ␊ |
| 49 | */␊ |
| 50 | ␊ |
| 51 | #define kIOInterfaceType "IOInterfaceType"␊ |
| 52 | ␊ |
| 53 | /*! @defined kIOMaxTransferUnit␊ |
| 54 | @abstract A property of IONetworkInterface objects.␊ |
| 55 | @discussion The kIOMaxTransferUnit property has an OSNumber value that specifies the maximum␊ |
| 56 | transfer unit for the interface in bytes.␊ |
| 57 | */␊ |
| 58 | ␊ |
| 59 | #define kIOMaxTransferUnit "IOMaxTransferUnit"␊ |
| 60 | ␊ |
| 61 | /*! @defined kIOMediaAddressLength␊ |
| 62 | @abstract A property of IONetworkInterface objects.␊ |
| 63 | @discussion The kIOMediaAddressLength property has an OSNumber value that specifies the size of the␊ |
| 64 | media address in bytes. ␊ |
| 65 | */␊ |
| 66 | ␊ |
| 67 | #define kIOMediaAddressLength "IOMediaAddressLength"␊ |
| 68 | ␊ |
| 69 | /*! @defined kIOMediaHeaderLength␊ |
| 70 | @abstract A property of IONetworkInterface objects.␊ |
| 71 | @discussion The kIOMediaHeaderLength property has an OSNumber value that specifies the size of the␊ |
| 72 | media header in bytes. ␊ |
| 73 | */␊ |
| 74 | ␊ |
| 75 | #define kIOMediaHeaderLength "IOMediaHeaderLength"␊ |
| 76 | ␊ |
| 77 | /*! @defined kIOInterfaceFlags␊ |
| 78 | @abstract A property of IONetworkInterface objects.␊ |
| 79 | @discussion The kIOInterfaceFlags property has an OSNumber value that specifies the current value␊ |
| 80 | of the interface flags. The flag constants are defined in␊ |
| 81 | bsd/net/if.h. ␊ |
| 82 | */␊ |
| 83 | ␊ |
| 84 | #define kIOInterfaceFlags "IOInterfaceFlags"␊ |
| 85 | ␊ |
| 86 | /*! @defined kIOInterfaceExtraFlags␊ |
| 87 | @abstract A property of IONetworkInterface objects.␊ |
| 88 | @discussion The kIOInterfaceExtraFlags property has an OSNumber value that specifies the current␊ |
| 89 | value of the interface extra flags. The extra flag constants are␊ |
| 90 | defined in bsd/net/if.h. ␊ |
| 91 | */␊ |
| 92 | ␊ |
| 93 | #define kIOInterfaceExtraFlags "IOInterfaceExtraFlags"␊ |
| 94 | ␊ |
| 95 | /*! @defined kIOInterfaceUnit␊ |
| 96 | @abstract A property of IONetworkInterface objects.␊ |
| 97 | @discussion The kIOInterfaceUnit property has an OSNumber value that describes the unit number␊ |
| 98 | assigned to the interface object. ␊ |
| 99 | */␊ |
| 100 | ␊ |
| 101 | #define kIOInterfaceUnit "IOInterfaceUnit"␊ |
| 102 | ␊ |
| 103 | /*! @defined kIOInterfaceState␊ |
| 104 | @abstract A property of IONetworkInterface objects.␊ |
| 105 | @discussion The kIOInterfaceState property has an OSNumber value that describes the current state␊ |
| 106 | of the interface object. This property is not exported to BSD via␊ |
| 107 | the ifnet structure. ␊ |
| 108 | */␊ |
| 109 | ␊ |
| 110 | #define kIOInterfaceState "IOInterfaceState"␊ |
| 111 | ␊ |
| 112 | /*! @defined kIOInterfaceNamePrefix␊ |
| 113 | @abstract A property of IONetworkInterface objects.␊ |
| 114 | @discussion The kIOInterfaceNamePrefix property has an OSString value that describes the string␊ |
| 115 | prefix for the BSD name assigned to the interface. ␊ |
| 116 | */␊ |
| 117 | ␊ |
| 118 | #define kIOInterfaceNamePrefix "IOInterfaceNamePrefix"␊ |
| 119 | ␊ |
| 120 | /*! @defined kIOPrimaryInterface␊ |
| 121 | @abstract A property of IONetworkInterface objects.␊ |
| 122 | @discussion The kIOInterfaceNamePrefix property has an OSBoolean value that describes whether the␊ |
| 123 | interface is the primary or the built-in network 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 | /*! @enum InterfaceObjectStates␊ |
| 147 | @discussion Constants used to encode the state of the interface object.␊ |
| 148 | @constant kIONetworkInterfaceRegisteredState The interface object has␊ |
| 149 | registered with the data link layer.␊ |
| 150 | @constant kIONetworkInterfaceOpenedState One or more clients have an␊ |
| 151 | open on the interface object.␊ |
| 152 | @constant kIONetworkInterfaceDisabledState The interface is temporarily␊ |
| 153 | unable to service its clients. This will occur when the network␊ |
| 154 | controller that is servicing the interface has entered a low power␊ |
| 155 | state that renders it unusable. ␊ |
| 156 | */␊ |
| 157 | ␊ |
| 158 | enum {␊ |
| 159 | kIONetworkInterfaceRegisteredState = 0x1,␊ |
| 160 | kIONetworkInterfaceOpenedState = 0x2,␊ |
| 161 | kIONetworkInterfaceDisabledState = 0x4␊ |
| 162 | };␊ |
| 163 | ␊ |
| 164 | /*␊ |
| 165 | * Kernel␊ |
| 166 | */␊ |
| 167 | #if defined(KERNEL) && defined(__cplusplus)␊ |
| 168 | ␊ |
| 169 | #include <IOKit/IOService.h>␊ |
| 170 | #include <IOKit/network/IONetworkData.h>␊ |
| 171 | #include <IOKit/network/IONetworkStats.h>␊ |
| 172 | #include <IOKit/network/IONetworkMedium.h>␊ |
| 173 | #include <net/kpi_interface.h>␊ |
| 174 | ␊ |
| 175 | class IONetworkController;␊ |
| 176 | class IONetworkStack;␊ |
| 177 | class IOCommandGate;␊ |
| 178 | ␊ |
| 179 | /*! @typedef IOOutputAction␊ |
| 180 | @discussion Prototype for an output packet handler that will process␊ |
| 181 | all outbound packets sent to the interface from the data link layer.␊ |
| 182 | An output handler is registered with the interface by calling␊ |
| 183 | registerOutputHandler().␊ |
| 184 | @param m A packet mbuf.␊ |
| 185 | @param param A parameter for the output request. */␊ |
| 186 | ␊ |
| 187 | typedef UInt32 (OSObject::*IOOutputAction)(mbuf_t, void * param);␊ |
| 188 | ␊ |
| 189 | /*! @typedef BPF_FUNC␊ |
| 190 | @discussion Prototype for the BPF tap handler. This will disappear␊ |
| 191 | when the correct DLIL header file is included. */␊ |
| 192 | ␊ |
| 193 | typedef int (*BPF_FUNC)(struct ifnet *, struct mbuf *);␊ |
| 194 | ␊ |
| 195 | // Network event types recognized by inputEvent().␊ |
| 196 | //␊ |
| 197 | enum {␊ |
| 198 | /* DLIL defined event, argument must be a pointer to a␊ |
| 199 | kern_event_msg structure. */␊ |
| 200 | kIONetworkEventTypeDLIL = 0xff000001,␊ |
| 201 | ␊ |
| 202 | /* Link up event, no argument */␊ |
| 203 | kIONetworkEventTypeLinkUp = 0xff000002,␊ |
| 204 | ␊ |
| 205 | /* Link down event, no argument */␊ |
| 206 | kIONetworkEventTypeLinkDown = 0xff000003,␊ |
| 207 | ␊ |
| 208 | /* Wake on LAN support changed, no argument */␊ |
| 209 | kIONetworkEventWakeOnLANSupportChanged = 0xff000004␊ |
| 210 | };␊ |
| 211 | ␊ |
| 212 | /*! @class IONetworkInterface␊ |
| 213 | @abstract Abstract class that manages the connection between an IONetworkController and the data link interface layer.␊ |
| 214 | @discussion An IONetworkInterface object manages the connection between␊ |
| 215 | an IONetworkController and the data link interface layer (DLIL).␊ |
| 216 | All interactions between the controller and DLIL must go through an␊ |
| 217 | interface object. Any data structures that are required by DLIL for a␊ |
| 218 | particular interface type shall be allocated and mantained by the␊ |
| 219 | interface object. IONetworkInterface is an abstract class that must be␊ |
| 220 | extended by a concrete subclass to specialize for a particular network␊ |
| 221 | type.␊ |
| 222 | ␊ |
| 223 | Although most drivers will allocate a single interface object,␊ |
| 224 | it is possible for multiple interfaces to be attached to a single␊ |
| 225 | controller. This controller driver will be responsible for arbitrating␊ |
| 226 | access among its multiple interface clients.␊ |
| 227 | ␊ |
| 228 | IONetworkInterface also maintains a dictionary of IONetworkData␊ |
| 229 | objects containing statistics structures. Controller drivers can␊ |
| 230 | ask for a particular data object by name and update the␊ |
| 231 | statistics counters within directly. This dictionary is added to␊ |
| 232 | the interface's property table and is visible outside of the kernel. ␊ |
| 233 | */␊ |
| 234 | ␊ |
| 235 | class IONetworkInterface : public IOService␊ |
| 236 | {␊ |
| 237 | OSDeclareAbstractStructors( IONetworkInterface )␊ |
| 238 | ␊ |
| 239 | friend class IONetworkStack;␊ |
| 240 | ␊ |
| 241 | private:␊ |
| 242 | IONetworkController * _controller;␊ |
| 243 | ifnet_t _backingIfnet;␊ |
| 244 | IORecursiveLock * _ifLock;␊ |
| 245 | OSSet * _clientSet;␊ |
| 246 | OSNumber * _stateBits;␊ |
| 247 | ␉bpf_packet_func _inputFilterFunc;␊ |
| 248 | bpf_packet_func _outputFilterFunc;␊ |
| 249 | ␉OSObject * _outTarget;␊ |
| 250 | IOOutputAction _outAction;␊ |
| 251 | UInt32 _clientVar[4];␊ |
| 252 | OSDictionary * _dataDict;␊ |
| 253 | mbuf_t _inputQHead;␊ |
| 254 | mbuf_t _inputQTail;␊ |
| 255 | UInt32 _inputQCount;␊ |
| 256 | ␊ |
| 257 | struct ExpansionData {␊ |
| 258 | ␉␉int␉␉␉␉unit;␊ |
| 259 | ␉␉int␉␉␉␉type;␊ |
| 260 | ␉␉int␉␉␉␉mtu;␊ |
| 261 | ␉␉int␉␉␉␉flags;␊ |
| 262 | ␉␉int␉␉␉␉eflags;␊ |
| 263 | ␉␉int␉␉␉␉addrlen;␊ |
| 264 | ␉␉int␉␉␉␉hdrlen;␊ |
| 265 | ␉␉IONetworkStats driverStats;␊ |
| 266 | ␉␉IONetworkStats lastDriverStats;␊ |
| 267 | ␉␉struct ifnet_stat_increment_param inputDeltas;␊ |
| 268 | ␉␉IOLock␉␉␉*detachLock;␊ |
| 269 | char *remote_NMI_pattern;␊ |
| 270 | unsigned int remote_NMI_len;␊ |
| 271 | };␊ |
| 272 | ␊ |
| 273 | ExpansionData * _reserved;␊ |
| 274 | ␊ |
| 275 | ␉void _syncFromBackingIfnet() const;␊ |
| 276 | ␉void _syncToBackingIfnet();␊ |
| 277 | ␊ |
| 278 | bool _syncNetworkDataDict();␊ |
| 279 | bool _setInterfaceProperty(UInt32 value,␊ |
| 280 | UInt32 mask,␊ |
| 281 | UInt32 bytes,␊ |
| 282 | void * addr,␊ |
| 283 | char * name);␊ |
| 284 | ␊ |
| 285 | SInt32 syncSIOCSIFMEDIA(IONetworkController * ctlr, struct ifreq * ifr);␊ |
| 286 | SInt32 syncSIOCGIFMEDIA(IONetworkController * ctlr, struct ifreq * ifr, unsigned long cmd);␊ |
| 287 | SInt32 syncSIOCSIFMTU(IONetworkController * ctlr, struct ifreq * ifr);␊ |
| 288 | ␉␊ |
| 289 | static int performGatedCommand(void *, void *, void *, void *, void *);␊ |
| 290 | static errno_t ioctl_shim(ifnet_t ifp, unsigned long cmd, void * data);␊ |
| 291 | static errno_t set_bpf_tap_shim(ifnet_t ifn, bpf_tap_mode mode, bpf_packet_func func);␊ |
| 292 | static int output_shim(ifnet_t ifp, mbuf_t);␊ |
| 293 | ␉void DLIL_INPUT(mbuf_t m_head);␊ |
| 294 | ␉static void detach_shim(ifnet_t ifp);␊ |
| 295 | static void powerChangeHandler(void *, void *, void *);␊ |
| 296 | ␊ |
| 297 | public:␊ |
| 298 | ␊ |
| 299 | /*! @function isPrimaryInterface␊ |
| 300 | @abstract Queries whether the interface object provided represents␊ |
| 301 | the "primary" network interface for the system.␊ |
| 302 | @result Returns true if the interface provided is the primary inteface,␊ |
| 303 | false otherwise. ␊ |
| 304 | */␊ |
| 305 | ␊ |
| 306 | virtual bool isPrimaryInterface() const;␊ |
| 307 | ␊ |
| 308 | /*! @function init␊ |
| 309 | @abstract Initializes an IONetworkInterface object.␊ |
| 310 | @discussion Initializes instance variables, and allocates resources.␊ |
| 311 | @param controller A network controller object that will service␊ |
| 312 | the interface object being initialized.␊ |
| 313 | @result Returns true on success, false otherwise. ␊ |
| 314 | */␊ |
| 315 | ␊ |
| 316 | virtual bool init( IONetworkController * controller );␊ |
| 317 | ␊ |
| 318 | /*! @function isRegistered␊ |
| 319 | @abstract Returns true if the interface has been registered with␊ |
| 320 | the data link layer.␊ |
| 321 | @discussion Once registered, the interface will be assigned a␊ |
| 322 | BSD name (such as en0), and a kIOBSDNameKey property is added to the␊ |
| 323 | property table containing this name. Calling this method performs␊ |
| 324 | the same function as checking for the kIONetworkInterfaceRegisteredState␊ |
| 325 | bit in the value returned by getInterfaceState().␊ |
| 326 | @result Returns true if interface is registered. Returns false if the data link layer␊ |
| 327 | has no references to this network interface, which implies that either the␊ |
| 328 | interface has yet to attach to the data link layer, or the interface has␊ |
| 329 | been detached. ␊ |
| 330 | */␊ |
| 331 | ␊ |
| 332 | virtual bool isRegistered() const;␊ |
| 333 | ␊ |
| 334 | /*! @function getInterfaceState␊ |
| 335 | @abstract Reports the current state of the interface object by returning␊ |
| 336 | the interface state flags.␊ |
| 337 | @result Returns the interface state flags. ␊ |
| 338 | */␊ |
| 339 | ␊ |
| 340 | virtual UInt32 getInterfaceState() const;␊ |
| 341 | ␊ |
| 342 | /*! @function matchPropertyTable␊ |
| 343 | @abstract Overrides the implementation in IOService to␊ |
| 344 | implement family-specific matching.␊ |
| 345 | @discussion When the gIOLocationMatchKey property is present in the␊ |
| 346 | dictionary provided, then fail the match unless the kIOBSDNameKey property␊ |
| 347 | is found. This is to prevent a premature match when hunting for a root␊ |
| 348 | device for BSD. The presence of the kIOBSDNameKey property indicates that␊ |
| 349 | the interface has registered with BSD, and is a valid candidate for␊ |
| 350 | matching against the gIOLocationMatchKey property. If the␊ |
| 351 | gIOLocationMatchKey property is absent, then this method will always␊ |
| 352 | return true.␊ |
| 353 | @param table The dictionary of properties to match against.␊ |
| 354 | @param score Pointer to the current driver's probe score, not used.␊ |
| 355 | @result Returns true for a positive match, false otherwise. ␊ |
| 356 | */␊ |
| 357 | ␊ |
| 358 | virtual bool matchPropertyTable( OSDictionary * table,␊ |
| 359 | SInt32 * score );␊ |
| 360 | ␊ |
| 361 | /*! @function getController␊ |
| 362 | @abstract Returns the provider, an IONetworkController object, that␊ |
| 363 | is servicing this interface object.␊ |
| 364 | @discussion This is the same controller object that was supplied as␊ |
| 365 | an argument to the init() method.␊ |
| 366 | @result Returns the IONetworkController object that is providing service to␊ |
| 367 | this interface object. ␊ |
| 368 | */␊ |
| 369 | ␊ |
| 370 | virtual IONetworkController * getController() const;␊ |
| 371 | ␊ |
| 372 | /*! @function inputPacket␊ |
| 373 | @abstract Submits a single packet received from the network to the data link layer.␊ |
| 374 | @discussion This method is called by the network controller to submit a single packet␊ |
| 375 | received from the network to the data link layer. The packet received by this method may be added to an input␊ |
| 376 | queue on the interface object, which the controller can use to postpone␊ |
| 377 | the packet handoff to the upper layers, until all received packets have␊ |
| 378 | been transferred to the input queue. A subsequent call to flushInputQueue(),␊ |
| 379 | will transfer the entire contents of the queue to the data link layer,␊ |
| 380 | by making a single call to dlil_input(). Other methods that can be used␊ |
| 381 | to manage the input queue are flushInputQueue() and clearInputQueue().␊ |
| 382 | This input queue is not protected by a lock. Access to the queue by the␊ |
| 383 | controller must be serialized, otherwise its use must be avoided.␊ |
| 384 | @param m The mbuf containing the received packet.␊ |
| 385 | @param length Specify the size of the received packet in the mbuf.␊ |
| 386 | The mbuf length fields are updated with this value. If zero,␊ |
| 387 | then the mbuf length fields are not updated.␊ |
| 388 | @param options Options defined by inputPacket() that the caller␊ |
| 389 | can use to specify this method call.␊ |
| 390 | @param param A parameter provided by the caller. Not used by␊ |
| 391 | IONetworkInterface.␊ |
| 392 | @result Returns the number of packets that were submitted to the data link layer,␊ |
| 393 | or 0 if the packet was queued. ␊ |
| 394 | */␊ |
| 395 | ␊ |
| 396 | virtual UInt32 inputPacket(mbuf_t,␊ |
| 397 | UInt32 length = 0,␊ |
| 398 | IOOptionBits options = 0,␊ |
| 399 | void * param = 0);␊ |
| 400 | ␊ |
| 401 | /*! @enum InputOptionQueuePacket␊ |
| 402 | @discussion The option bits that can be specified␊ |
| 403 | in the options argument when calling inputPacket().␊ |
| 404 | @constant kInputOptionQueuePacket Keep the packet provided in the␊ |
| 405 | input packet queue. No packets are sent to the data link layers,␊ |
| 406 | and the caller's thread will not venture outside the interface␊ |
| 407 | object. Calls to inputPacket() must be serialized. ␊ |
| 408 | */␊ |
| 409 | ␊ |
| 410 | enum {␊ |
| 411 | kInputOptionQueuePacket = 0x1␊ |
| 412 | };␊ |
| 413 | ␊ |
| 414 | /*! @function flushInputQueue␊ |
| 415 | @abstract Sends all packets held in the input queue to the data␊ |
| 416 | link layer.␊ |
| 417 | @discussion Remove all packets from the input queue and␊ |
| 418 | send them to the data link layer by calling dlil_input(). This␊ |
| 419 | method should be used in connection with the inputPacket() method,␊ |
| 420 | to flush the input queue after inputPacket() was used to queue up␊ |
| 421 | some number of received packets. See inputPacket() and clearInputQueue().␊ |
| 422 | @result Returns the number of packets that were submitted to the data link layer.␊ |
| 423 | May be zero if the queue was empty. ␊ |
| 424 | */␊ |
| 425 | ␊ |
| 426 | virtual UInt32 flushInputQueue();␊ |
| 427 | ␊ |
| 428 | /*! @function clearInputQueue␊ |
| 429 | @abstract Removes and discards all packets in the input queue.␊ |
| 430 | @discussion This method removes all packets from the input queue and␊ |
| 431 | releases them back to the free mbuf pool. Also see flushInputQueue().␊ |
| 432 | @result Returns the number of packets freed. ␊ |
| 433 | */␊ |
| 434 | ␊ |
| 435 | virtual UInt32 clearInputQueue();␊ |
| 436 | ␊ |
| 437 | /*! @function inputEvent␊ |
| 438 | @abstract Sends an event to the data link layer.␊ |
| 439 | @discussion This method can be used by the network controller to␊ |
| 440 | send an event to the data link layer.␊ |
| 441 | @param type A constant describing the event type.␊ |
| 442 | @param data Data associated with the event.␊ |
| 443 | @result Returns true if the event was delivered, false if the event type␊ |
| 444 | specified is invalid, or if the event delivery was unsuccesful. ␊ |
| 445 | */␊ |
| 446 | ␊ |
| 447 | virtual bool inputEvent(UInt32 type, void * data);␊ |
| 448 | ␊ |
| 449 | /*! @function registerOutputHandler␊ |
| 450 | @abstract Registers a target/action to handle output packets.␊ |
| 451 | @discussion The interface object will forward all output packets,␊ |
| 452 | received from the data link layer, to the output handler registered␊ |
| 453 | through this method. The default target and action are set by the init()␊ |
| 454 | method to the controller, and the handler returned by the controller's␊ |
| 455 | getOutputHandler() method. Once the interface becomes registered with␊ |
| 456 | the data link layer, this method will return false and will reject any␊ |
| 457 | further changes.␊ |
| 458 | @param target Target object that implements the output handler.␊ |
| 459 | @param action The function that will process output packets.␊ |
| 460 | @result Returns true if the target/action provided was accepted,␊ |
| 461 | false otherwise. ␊ |
| 462 | */␊ |
| 463 | ␊ |
| 464 | virtual bool registerOutputHandler(OSObject * target,␊ |
| 465 | IOOutputAction action);␊ |
| 466 | ␊ |
| 467 | /*! @function getNamePrefix␊ |
| 468 | @abstract Returns a string containing the prefix to use when␊ |
| 469 | creating a BSD name for this interface.␊ |
| 470 | @discussion The BSD name for each interface object is generated by␊ |
| 471 | concatenating a string returned by this method, with an unique␊ |
| 472 | unit number assigned by IONetworkStack.␊ |
| 473 | A concrete subclass of IONetworkInterface must implement this method␊ |
| 474 | and enforce a consistent name for all of its instances.␊ |
| 475 | @result Returns a pointer to a constant C string.␊ |
| 476 | */␊ |
| 477 | ␊ |
| 478 | virtual const char * getNamePrefix() const = 0;␊ |
| 479 | ␊ |
| 480 | /*! @function getInterfaceType␊ |
| 481 | @abstract Gets the interface type.␊ |
| 482 | @discussion This method returns the value in the if_type field in the ifnet structure.␊ |
| 483 | @result Returns a constant defined in bsd/net/if_types.h header file␊ |
| 484 | that describes the interface type. ␊ |
| 485 | */␊ |
| 486 | ␊ |
| 487 | virtual UInt8 getInterfaceType() const;␊ |
| 488 | ␊ |
| 489 | /*! @function getMaxTransferUnit␊ |
| 490 | @abstract Gets the maximum transfer unit for this interface.␊ |
| 491 | @discussion This method returns the value in the if_mtu field in the ifnet structure.␊ |
| 492 | @result Returns the interface MTU size in bytes. ␊ |
| 493 | */␊ |
| 494 | ␊ |
| 495 | virtual UInt32 getMaxTransferUnit() const;␊ |
| 496 | ␊ |
| 497 | /*! @function getFlags␊ |
| 498 | @abstract Gets the value of the interface flags.␊ |
| 499 | @discussion This method returns the value in the if_flags field in the ifnet structure.␊ |
| 500 | @result Returns the value of the interface flags. ␊ |
| 501 | */␊ |
| 502 | ␊ |
| 503 | virtual UInt16 getFlags() const;␊ |
| 504 | ␊ |
| 505 | /*! @function getExtraFlags␊ |
| 506 | @abstract Gets the value of the interface extra flags.␊ |
| 507 | @discussion This method returns the value in the if_eflags field in the ifnet structure.␊ |
| 508 | @result Returns the value of the interface extra flags. ␊ |
| 509 | */␊ |
| 510 | ␊ |
| 511 | virtual UInt32 getExtraFlags() const;␊ |
| 512 | ␊ |
| 513 | /*! @function getMediaAddressLength␊ |
| 514 | @abstract Gets the size of the media (MAC-layer) address.␊ |
| 515 | @discussion This method returns the value in the if_addrlen field in the ifnet structure.␊ |
| 516 | @result Returns the size of the media address in bytes. ␊ |
| 517 | */␊ |
| 518 | ␊ |
| 519 | virtual UInt8 getMediaAddressLength() const;␊ |
| 520 | ␊ |
| 521 | /*! @function getMediaHeaderLength␊ |
| 522 | @abstract Gets the size of the media header.␊ |
| 523 | @discussion This method returns the value in the if_hdrlen field in the ifnet structure.␊ |
| 524 | @result Returns the size of the media header in bytes. ␊ |
| 525 | */␊ |
| 526 | ␊ |
| 527 | virtual UInt8 getMediaHeaderLength() const;␊ |
| 528 | ␊ |
| 529 | /*! @function getUnitNumber␊ |
| 530 | @abstract Gets the unit number assigned to this interface object.␊ |
| 531 | @discussion This method returns the value in the if_unit field in the ifnet structure.␊ |
| 532 | @result Returns the assigned interface unit number. ␊ |
| 533 | */␊ |
| 534 | ␊ |
| 535 | virtual UInt16 getUnitNumber() const;␊ |
| 536 | ␊ |
| 537 | /*! @function addNetworkData␊ |
| 538 | @abstract Adds an IONetworkData object to a dictionary managed by␊ |
| 539 | the interface.␊ |
| 540 | @param aData An IONetworkData object to be added to a dictionary␊ |
| 541 | managed by the interface. This object is retained by the dictionary.␊ |
| 542 | @result Returns true if the operation was successful, false otherwise. ␊ |
| 543 | */␊ |
| 544 | ␊ |
| 545 | virtual bool addNetworkData(IONetworkData * aData);␊ |
| 546 | ␊ |
| 547 | /*! @function removeNetworkData␊ |
| 548 | @abstract Removes an entry from the IONetworkData dictionary␊ |
| 549 | managed by the interface.␊ |
| 550 | @discussion This method removes an entry from the IONetworkData dictionary␊ |
| 551 | managed by the interface. The removed object is released.␊ |
| 552 | @param aKey A unique OSSymbol identifying the IONetworkData object␊ |
| 553 | to be removed from the dictionary.␊ |
| 554 | @result Returns true if the operation was successful, false otherwise. ␊ |
| 555 | */␊ |
| 556 | ␊ |
| 557 | virtual bool removeNetworkData(const OSSymbol * aKey);␊ |
| 558 | ␊ |
| 559 | /*! @function removeNetworkData␊ |
| 560 | @abstract Removes an entry from the IONetworkData dictionary␊ |
| 561 | managed by the interface.␊ |
| 562 | @discussion This method removes an entry from the IONetworkData dictionary␊ |
| 563 | managed by the interface. The removed object is released.␊ |
| 564 | @param aKey A unique string identifying the IONetworkData object␊ |
| 565 | to be removed from the dictionary.␊ |
| 566 | @result Returns true if the operation was successful, false otherwise. ␊ |
| 567 | */␊ |
| 568 | ␊ |
| 569 | virtual bool removeNetworkData(const char * aKey);␊ |
| 570 | ␊ |
| 571 | /*! @function getNetworkData␊ |
| 572 | @abstract Gets an IONetworkData object from the interface that is␊ |
| 573 | associated with the given key.␊ |
| 574 | @param aKey The unique string identifying the IONetworkData object to be␊ |
| 575 | returned to caller.␊ |
| 576 | @result Returns a reference to the matching IONetworkData object,␊ |
| 577 | or 0 if no match was found.␊ |
| 578 | */␊ |
| 579 | ␊ |
| 580 | virtual IONetworkData * getNetworkData(const char * aKey) const;␊ |
| 581 | ␊ |
| 582 | /*! @function getNetworkData␊ |
| 583 | @abstract Gets an IONetworkData object from the interface that is␊ |
| 584 | associated with the given key.␊ |
| 585 | @param aKey The unique OSSymbol identifying the IONetworkData object to be␊ |
| 586 | returned to caller.␊ |
| 587 | @result Returns a reference to the matching IONetworkData object,␊ |
| 588 | or 0 if no match was found. ␊ |
| 589 | */␊ |
| 590 | ␊ |
| 591 | virtual IONetworkData * getNetworkData(const OSSymbol * aKey) const;␊ |
| 592 | ␊ |
| 593 | /*! @function setProperties␊ |
| 594 | @abstract Handles a request to set network interface properties from␊ |
| 595 | kernel or non-kernel clients. ␊ |
| 596 | @discussion For non-kernel clients, the preferred␊ |
| 597 | access mechanism is through a user client connection.␊ |
| 598 | @param properties An OSDictionary containing a collection of␊ |
| 599 | properties.␊ |
| 600 | @result Returns kIOReturnUnsupported if the interface did not␊ |
| 601 | recognize any of the properties provided. Otherwise, the return␊ |
| 602 | code will be kIOReturnSuccess to indicate no errors, or an␊ |
| 603 | IOReturn error code to indicate that an error occurred while␊ |
| 604 | handling one of the properties. ␊ |
| 605 | */␊ |
| 606 | ␊ |
| 607 | virtual IOReturn setProperties( OSObject * properties );␊ |
| 608 | ␊ |
| 609 | // FIXME - Compatibility methods (to be removed)␊ |
| 610 | IONetworkData * getParameter(const char * aKey) const;␊ |
| 611 | ␉bool setExtendedFlags(UInt32 flags, UInt32 clear = 0);␊ |
| 612 | ␊ |
| 613 | virtual IOReturn message( UInt32 type, IOService * provider, void * argument );␊ |
| 614 | ␊ |
| 615 | /*! @function debuggerRegistered␊ |
| 616 | @abstract Tells the IONetworkInterface that this interface will be used␊ |
| 617 | by the debugger.␊ |
| 618 | */␊ |
| 619 | void debuggerRegistered(void);␊ |
| 620 | ␊ |
| 621 | protected:␊ |
| 622 | ␊ |
| 623 | /*! @function setInterfaceType␊ |
| 624 | @abstract Sest the interface type.␊ |
| 625 | @discussion Both the if_type field in the ifnet structure, and the␊ |
| 626 | kIOInterfaceType property are updated with the value provided.␊ |
| 627 | @param type A constant defined in bsd/net/if_types.h header file␊ |
| 628 | that describes the interface type.␊ |
| 629 | @result Returns true if the update was successful, false otherwise. ␊ |
| 630 | */␊ |
| 631 | ␊ |
| 632 | virtual bool setInterfaceType(UInt8 type);␊ |
| 633 | ␊ |
| 634 | /*! @function setMaxTransferUnit␊ |
| 635 | @abstract Sets the maximum transfer unit for this interface.␊ |
| 636 | @discussion Both the if_mtu field in the ifnet structure, and the␊ |
| 637 | kIOMaxTransferUnit property are updated with the value provided.␊ |
| 638 | @param mtu The interface MTU size in bytes.␊ |
| 639 | @result Returns true if the update was successful, false otherwise. ␊ |
| 640 | */␊ |
| 641 | ␊ |
| 642 | virtual bool setMaxTransferUnit(UInt32 mtu);␊ |
| 643 | ␊ |
| 644 | /*! @function setFlags␊ |
| 645 | @abstract Performs a read-modify-write operation on the current␊ |
| 646 | interface flags value.␊ |
| 647 | @discussion See bsd/net/if.h header file for the definition of the␊ |
| 648 | flag constants. Both the if_flags field in the ifnet structure, and␊ |
| 649 | the kIOInterfaceFlags property are updated with the value provided.␊ |
| 650 | @param flags The bits that should be set.␊ |
| 651 | @param clear The bits that should be cleared. If 0, then non␊ |
| 652 | of the flags are cleared and the result is formed by OR'ing the␊ |
| 653 | original flags value with the new flags.␊ |
| 654 | @result Returns true if the update was successful, false otherwise. ␊ |
| 655 | */␊ |
| 656 | ␊ |
| 657 | virtual bool setFlags(UInt16 flags, UInt16 clear = 0);␊ |
| 658 | ␊ |
| 659 | /*! @function setExtraFlags␊ |
| 660 | @abstract Performs a read-modify-write operation on the current␊ |
| 661 | interface extra flags value.␊ |
| 662 | @discussion See bsd/net/if.h header file for the definition of the␊ |
| 663 | extra flag constants. Both the if_eflags field in the ifnet structure,␊ |
| 664 | and the kIOInterfaceExtraFlags property are updated with the value␊ |
| 665 | provided.␊ |
| 666 | @param flags The bits that should be set.␊ |
| 667 | @param flags The bits that should be set.␊ |
| 668 | @param clear The bits that should be cleared. If 0, then non␊ |
| 669 | of the flags are cleared and the result is formed by OR'ing the␊ |
| 670 | original flags with the new flags.␊ |
| 671 | @result Returns true if the update was successful, false otherwise. ␊ |
| 672 | */␊ |
| 673 | ␊ |
| 674 | virtual bool setExtraFlags(UInt32 flags, UInt32 clear = 0);␊ |
| 675 | ␊ |
| 676 | /*! @function setMediaAddressLength␊ |
| 677 | @abstract Sets the size of the media (MAC-layer) address.␊ |
| 678 | @discussion Both the if_addrlen field in the ifnet structure, and the␊ |
| 679 | kIOMediaAddressLength property are updated with the value provided.␊ |
| 680 | @param length The size of the media address in bytes.␊ |
| 681 | @result Returns true if the update was successful, false otherwise.␊ |
| 682 | */␊ |
| 683 | ␊ |
| 684 | virtual bool setMediaAddressLength(UInt8 length);␊ |
| 685 | ␊ |
| 686 | /*! @function setMediaHeaderLength␊ |
| 687 | @abstract Sets the size of the media header.␊ |
| 688 | @discussion Both the if_hdrlen field in the ifnet structure, and the␊ |
| 689 | kIOMediaHeaderLength property are updated with the value provided.␊ |
| 690 | @param length The size of the media header in bytes.␊ |
| 691 | @result Returns true if the update was successful, false otherwise. ␊ |
| 692 | */␊ |
| 693 | ␊ |
| 694 | virtual bool setMediaHeaderLength(UInt8 length);␊ |
| 695 | ␊ |
| 696 | /*! @function setUnitNumber␊ |
| 697 | @abstract Assigns a unique unit number to this interface.␊ |
| 698 | @discussion This method is called by IONetworkStack before the␊ |
| 699 | interface is registered with the data link layer, to assign a␊ |
| 700 | unique unit number to the interface object. Both the if_unit field␊ |
| 701 | in the ifnet structure, and the kIOInterfaceUnit property are updated␊ |
| 702 | with the value provided.␊ |
| 703 | @param unit The unit number assigned to this interface object.␊ |
| 704 | @result Returns true if the update was successful, false otherwise. ␊ |
| 705 | */␊ |
| 706 | ␊ |
| 707 | virtual bool setUnitNumber(UInt16 unit);␊ |
| 708 | ␊ |
| 709 | /*! @function free␊ |
| 710 | @abstract Frees the IONetworkInterface object.␊ |
| 711 | @discussion Resource allocated by init() are released, and␊ |
| 712 | clearInputQueue() is called to ensure that the input queue is empty.␊ |
| 713 | */␊ |
| 714 | ␊ |
| 715 | virtual void free();␊ |
| 716 | ␊ |
| 717 | /*! @function handleOpen␊ |
| 718 | @abstract Handles a client open on the interface.␊ |
| 719 | @discussion This method is called by IOService::open() with the␊ |
| 720 | arbitration lock held, and must return true to accept the client open.␊ |
| 721 | This method will in turn call handleClientOpen() to qualify the client␊ |
| 722 | requesting the open. Since the controller is opened by the interface␊ |
| 723 | in a lazy fashion, the interface may also perform an open on the␊ |
| 724 | controller before this method returns. If the controller was opened,␊ |
| 725 | then controllerDidOpen() is called to notify interested subclasses.␊ |
| 726 | Subclasses should not override this method.␊ |
| 727 | @param client The client object that requested the open.␊ |
| 728 | @param options Options passed to IOService::open().␊ |
| 729 | @param argument Argument passed to IOService::open().␊ |
| 730 | @result Returns true to accept the client open, false otherwise. ␊ |
| 731 | */␊ |
| 732 | ␊ |
| 733 | virtual bool handleOpen(IOService * client,␊ |
| 734 | IOOptionBits options,␊ |
| 735 | void * argument);␊ |
| 736 | ␊ |
| 737 | /*! @function handleClose␊ |
| 738 | @abstract Handles a client close on the interface.␊ |
| 739 | @discussion This method is called by IOService::close() with the␊ |
| 740 | arbitration lock held. This method will in turn call handleClientClose()␊ |
| 741 | to notify interested subclasses about the client close. If this represents␊ |
| 742 | the last close, then the interface will also close the controller before␊ |
| 743 | this method returns. The controllerWillClose() method will be called before␊ |
| 744 | closing the controller. Subclasses should not override this method.␊ |
| 745 | @param client The client object that requested the close.␊ |
| 746 | @param options Options passed to IOService::close().␊ |
| 747 | */␊ |
| 748 | ␊ |
| 749 | virtual void handleClose(IOService * client, IOOptionBits options);␊ |
| 750 | ␊ |
| 751 | /*! @function handleIsOpen␊ |
| 752 | @abstract Queries whether a client has an open on the interface.␊ |
| 753 | @discussion This method is always called by IOService with the␊ |
| 754 | arbitration lock held. Subclasses should not override this method.␊ |
| 755 | @result Returns true if the specified client, or any client if none (0) is␊ |
| 756 | specified, presently has an open on this object. ␊ |
| 757 | */␊ |
| 758 | ␊ |
| 759 | virtual bool handleIsOpen(const IOService * client) const;␊ |
| 760 | ␊ |
| 761 | /*! @function lock␊ |
| 762 | @abstract Takes the network interface lock.␊ |
| 763 | @discussion This method takes the recursive lock that protects the interface␊ |
| 764 | state. All updates to the interface state and to the ifnet structure␊ |
| 765 | must be performed while holding this lock. This call must be balanced␊ |
| 766 | by a subsequent call to unlock(). ␊ |
| 767 | */␊ |
| 768 | ␊ |
| 769 | virtual void lock();␊ |
| 770 | ␊ |
| 771 | /*! @function unlock␊ |
| 772 | @abstract Releases the network interface lock.␊ |
| 773 | @discussion This method releases the recursive lock that protects the interface␊ |
| 774 | state to balance a previous lock() call. ␊ |
| 775 | */␊ |
| 776 | ␊ |
| 777 | virtual void unlock();␊ |
| 778 | ␊ |
| 779 | /*! @function controllerDidOpen␊ |
| 780 | @abstract Sends a notification that the interface has opened the network␊ |
| 781 | controller.␊ |
| 782 | @discussion This method is called by handleOpen() to notify subclasses that the␊ |
| 783 | controller has been opened. The open on the controller is done when␊ |
| 784 | the interface receives the initial open request from a client.␊ |
| 785 | Subclasses can override this method and inspect the controller before␊ |
| 786 | allowing the client open. The implementation in the subclass must first␊ |
| 787 | call the method in super and check the return value. This method is␊ |
| 788 | called with our arbitration lock held, hence issuing I/O to the␊ |
| 789 | controller must be avoided to eliminate the possibility of a␊ |
| 790 | deadlock.␊ |
| 791 | @param controller The controller that was opened.␊ |
| 792 | @result Must return true in order for handleOpen() to accept ␊ |
| 793 | the client open. If the return is false, then the controller will be␊ |
| 794 | closed and the client open will be refused. ␊ |
| 795 | */␊ |
| 796 | ␊ |
| 797 | virtual bool controllerDidOpen(IONetworkController * controller);␊ |
| 798 | ␊ |
| 799 | /*! @function controllerWillClose␊ |
| 800 | @abstract Sends a notification that the interface will close the network␊ |
| 801 | controller.␊ |
| 802 | @discussion This method is called by handleClose() after receiving a close from the␊ |
| 803 | last client, and just before the controller is closed. Subclasses␊ |
| 804 | can override this method to perform any cleanup action before the ␊ |
| 805 | controller is closed. This method is called with our arbitration lock␊ |
| 806 | held, hence issuing I/O to the controller must be avoided to eliminate␊ |
| 807 | the possibility of a deadlock.␊ |
| 808 | @param controller The controller that is about to be closed. ␊ |
| 809 | */␊ |
| 810 | ␊ |
| 811 | virtual void controllerWillClose(IONetworkController * controller);␊ |
| 812 | ␊ |
| 813 | /*! @function performCommand␊ |
| 814 | @abstract Handles an ioctl command sent to the network interface.␊ |
| 815 | @discussion This method handles socket ioctl commands sent to the␊ |
| 816 | network interface from DLIL.␊ |
| 817 | IONetworkInterface handles commands that are common for all network␊ |
| 818 | interface types. A subclass of IONetworkInterface may override this␊ |
| 819 | method to override the command handling in IONetworkInterface, or␊ |
| 820 | to extend the command processing to handle additional commands,␊ |
| 821 | and then call super for any commands not handled in the subclass.␊ |
| 822 | The ioctl commands handled by IONetworkInterface are␊ |
| 823 | SIOCGIFMTU (Get interface MTU size),␊ |
| 824 | SIOCSIFMTU (Set interface MTU size),␊ |
| 825 | SIOCSIFMEDIA (Set media), and␊ |
| 826 | SIOCGIFMEDIA (Get media and link status).␊ |
| 827 | @param controller The controller object.␊ |
| 828 | @param cmd The ioctl command code.␊ |
| 829 | @param arg0 Command argument 0. Generally a pointer to an ifnet structure␊ |
| 830 | associated with the interface.␊ |
| 831 | @param arg1 Command argument 1.␊ |
| 832 | @result Returns a BSD return value defined in bsd/sys/errno.h. ␊ |
| 833 | */␊ |
| 834 | ␊ |
| 835 | virtual SInt32 performCommand(IONetworkController * controller,␊ |
| 836 | unsigned long cmd,␊ |
| 837 | void * arg0,␊ |
| 838 | void * arg1);␊ |
| 839 | ␊ |
| 840 | public:␊ |
| 841 | ␊ |
| 842 | /*! @function getIfnet␊ |
| 843 | @abstract Gets the ifnet_t allocated by the interface object.␊ |
| 844 | @discussion Reveal the interface's ifnet_t. The ifnet_t is managed␊ |
| 845 | ␉␉primarily by IONetworkInterface, however sub-classes or drivers␊ |
| 846 | can use this method to get a reference to the ifnet_t object for␊ |
| 847 | interface KPI calls.␊ |
| 848 | @result Returns the ifnet_t object that is attached to the datalink layer.␊ |
| 849 | */␊ |
| 850 | ␊ |
| 851 | virtual ifnet_t getIfnet() const ;␊ |
| 852 | ␊ |
| 853 | protected:␊ |
| 854 | ␊ |
| 855 | /*! @function initIfnet␊ |
| 856 | @abstract Initializes the ifnet structure given.␊ |
| 857 | @discussion A concrete subclass must override this method and initialize␊ |
| 858 | the ifnet structure given. The implementation in the subclass must call␊ |
| 859 | super before it returns, to allow IONetworkInterface to complete the␊ |
| 860 | initialization, and to insert the BSD shim functions implemented in␊ |
| 861 | IONetworkInterface to the appropriate function pointer fields in the␊ |
| 862 | ifnet structure. IONetworkInterface will call this method during its␊ |
| 863 | init() method. Subclasses are encouraged to use the ifnet accessor␊ |
| 864 | methods to update the ifnet structure when possible, since this will␊ |
| 865 | ensure that properties in the registry will also be updated to reflect␊ |
| 866 | any changes made.␊ |
| 867 | @param ifp Pointer to an ifnet structure obtained earlier through␊ |
| 868 | the getIfnet() method call.␊ |
| 869 | @result Returns true on success, false otherwise. ␊ |
| 870 | */␊ |
| 871 | ␊ |
| 872 | virtual bool initIfnet(struct ifnet * ifp);␊ |
| 873 | ␊ |
| 874 | /*! @function handleClientOpen␊ |
| 875 | @abstract Handles a client open on the interface.␊ |
| 876 | @discussion This method is called by handleOpen() to handle an open from a client object.␊ |
| 877 | Unlike handleOpen(), subclasses may override this method to catch an open␊ |
| 878 | request from a client. This method is called with the arbitration lock held.␊ |
| 879 | @param client The client object requesting the open.␊ |
| 880 | @param options Options passed to IONetworkInterface::handleOpen().␊ |
| 881 | @param argument Argument passed to IONetworkInterface::handleOpen().␊ |
| 882 | @result Returns true to accept the client open, false to refuse it. ␊ |
| 883 | */␊ |
| 884 | ␊ |
| 885 | virtual bool handleClientOpen(IOService * client,␊ |
| 886 | IOOptionBits options,␊ |
| 887 | void * argument);␊ |
| 888 | ␊ |
| 889 | /*! @function handleClientClose␊ |
| 890 | @abstract Handles a client close on the interface.␊ |
| 891 | @discussion This method is called by handleClose() to handle a close from a client object.␊ |
| 892 | Unlike handleClose(), subclasses may override this method to catch a close␊ |
| 893 | reuqest from a client. This method is called with the arbitration lock held.␊ |
| 894 | @param client The client object requesting the close.␊ |
| 895 | @param options Options passed to IONetworkInterface::handleClose(). ␊ |
| 896 | */␊ |
| 897 | ␊ |
| 898 | virtual void handleClientClose(IOService * client,␊ |
| 899 | IOOptionBits options);␊ |
| 900 | ␊ |
| 901 | /*! @function newUserClient␊ |
| 902 | @abstract Creates a connection for a non kernel client.␊ |
| 903 | @discussion This method creates a new IOUserClient to service a connection to a␊ |
| 904 | non kernel client.␊ |
| 905 | @param owningTask The mach task requesting the connection.␊ |
| 906 | @param security_id A token representing the access level for the task.␊ |
| 907 | @param type A constant specifying the type of connection to be created.␊ |
| 908 | An IONetworkUserClient object is created if the type specified is␊ |
| 909 | kIONetworkUserClientTypeID.␊ |
| 910 | @param handler The IOUserClient object returned.␊ |
| 911 | @result Returns kIOReturnSuccess if an IONetworkUserClient was created,␊ |
| 912 | kIOReturnNoMemory for a memory allocation error, or␊ |
| 913 | kIOReturnBadArgument if the type specified is unknown. ␊ |
| 914 | */␊ |
| 915 | ␊ |
| 916 | virtual IOReturn newUserClient(task_t owningTask,␊ |
| 917 | void * security_id,␊ |
| 918 | UInt32 type,␊ |
| 919 | IOUserClient ** handler);␊ |
| 920 | ␊ |
| 921 | /*! @function setInterfaceState␊ |
| 922 | @abstract Updates the interface object state flags.␊ |
| 923 | @discussion The kIOInterfaceState property is updated with the value␊ |
| 924 | provided.␊ |
| 925 | @param flags The bits that should be set.␊ |
| 926 | @param clear The bits that should be cleared.␊ |
| 927 | @result Returns the resulting interface state flags following any changes␊ |
| 928 | made by this method. ␊ |
| 929 | */␊ |
| 930 | ␊ |
| 931 | virtual UInt32 setInterfaceState( UInt32 set, UInt32 clear = 0 );␊ |
| 932 | ␊ |
| 933 | /*! @function powerStateWillChangeTo␊ |
| 934 | @abstract Handles a notification that the network controller servicing␊ |
| 935 | this interface object is about to transition to a new power state.␊ |
| 936 | @discussion This method will call the controllerWillChangePowerState() method␊ |
| 937 | on the controller's work loop context to prepare for the power state change.␊ |
| 938 | Subclasses should not override this method.␊ |
| 939 | @param flags Flags that describe the capability of the controller in the new␊ |
| 940 | power state.␊ |
| 941 | @param stateNumber An index to a state in the network controller's␊ |
| 942 | power state array that the controller is switching to.␊ |
| 943 | @param policyMaker A reference to the network controller's policy-maker,␊ |
| 944 | and is also the originator of this notification.␊ |
| 945 | @result The return will always be IOPMAckImplied to indicate that the␊ |
| 946 | preparation for the power change has already completed when this method␊ |
| 947 | returns. ␊ |
| 948 | */␊ |
| 949 | ␊ |
| 950 | virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags flags,␊ |
| 951 | unsigned long stateNumber,␊ |
| 952 | IOService * policyMaker );␊ |
| 953 | ␊ |
| 954 | /*! @function powerStateDidChangeTo␊ |
| 955 | @abstract Handles a notification that the network controller servicing␊ |
| 956 | this interface object has transitioned to a new power state.␊ |
| 957 | @discussion This method will call the controllerDidChangePowerState() method␊ |
| 958 | on the controller's work loop context to prepare for the power state change.␊ |
| 959 | Subclasses should not override this method.␊ |
| 960 | @param flags Flags that describe the capability of the controller in the new␊ |
| 961 | power state.␊ |
| 962 | @param stateNumber An index to a state in the network controller's␊ |
| 963 | power state array that the controller has switched to.␊ |
| 964 | @param policyMaker A reference to the network controller's policy-maker,␊ |
| 965 | and is also the originator of this notification.␊ |
| 966 | @result The return will always be IOPMAckImplied to indicate that the␊ |
| 967 | preparation for the power change has already completed when this method␊ |
| 968 | returns. ␊ |
| 969 | */␊ |
| 970 | ␊ |
| 971 | virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags flags,␊ |
| 972 | unsigned long stateNumber,␊ |
| 973 | IOService * policyMaker );␊ |
| 974 | ␊ |
| 975 | /*! @function controllerWillChangePowerState␊ |
| 976 | @abstract Handles a notification that the network controller servicing␊ |
| 977 | this interface object is about to transition to a new power state.␊ |
| 978 | @param controller The network controller object.␊ |
| 979 | @param flags Flags that describe the capability of the controller in the new␊ |
| 980 | power state.␊ |
| 981 | @param stateNumber An index to a state in the network controller's␊ |
| 982 | power state array that the controller is switching to.␊ |
| 983 | @param policyMaker A reference to the network controller's policy-maker,␊ |
| 984 | and is also the originator of this notification.␊ |
| 985 | @result The return value is always kIOReturnSuccess. ␊ |
| 986 | */␊ |
| 987 | ␊ |
| 988 | virtual IOReturn controllerWillChangePowerState(␊ |
| 989 | IONetworkController * controller,␊ |
| 990 | IOPMPowerFlags flags,␊ |
| 991 | UInt32 stateNumber,␊ |
| 992 | IOService * policyMaker);␊ |
| 993 | ␊ |
| 994 | /*! @function controllerDidChangePowerState␊ |
| 995 | @abstract Handles a notification that the network controller servicing␊ |
| 996 | this interface object has transitioned to a new power state.␊ |
| 997 | @param controller The network controller object.␊ |
| 998 | @param flags Flags that describe the capability of the controller in the new␊ |
| 999 | power state.␊ |
| 1000 | @param stateNumber An index to a state in the network controller's␊ |
| 1001 | power state array that the controller has switched to.␊ |
| 1002 | @param policyMaker A reference to the network controller's policy-maker,␊ |
| 1003 | and is also the originator of this notification.␊ |
| 1004 | @result The return value is always kIOReturnSuccess. ␊ |
| 1005 | */␊ |
| 1006 | ␊ |
| 1007 | virtual IOReturn controllerDidChangePowerState(␊ |
| 1008 | IONetworkController * controller,␊ |
| 1009 | IOPMPowerFlags flags,␊ |
| 1010 | UInt32 stateNumber,␊ |
| 1011 | IOService * policyMaker);␊ |
| 1012 | ␊ |
| 1013 | public:␊ |
| 1014 | /* Override IOService::willTerminate() */␊ |
| 1015 | ␊ |
| 1016 | virtual bool willTerminate( IOService * provider,␊ |
| 1017 | IOOptionBits options );␊ |
| 1018 | ␊ |
| 1019 | /* Override IOService::serializeProperties() */␊ |
| 1020 | ␊ |
| 1021 | virtual bool serializeProperties( OSSerialize * s ) const;␊ |
| 1022 | ␊ |
| 1023 | /*! @function attachToDataLinkLayer␊ |
| 1024 | @abstract Attaches the network interface to the BSD data link layer.␊ |
| 1025 | @discussion This function is called by the family to attach the network␊ |
| 1026 | interface managed by an IONetworkInterface to the BSD data link layer.␊ |
| 1027 | This call occurs after the interface initialization and setup, and the␊ |
| 1028 | assignment of an interface unit number. The family does not implicitly␊ |
| 1029 | close the gate on the network controller's work loop when calling this␊ |
| 1030 | function. Prior to the data link attachment, services provided by an␊ |
| 1031 | IONetworkInterface will be inaccessible to BSD networking, though the␊ |
| 1032 | object can be found in the I/O Kit Registry. Subclasses can override␊ |
| 1033 | this function to perform interface specific work.␊ |
| 1034 | @param options Options for the attach call. None are currently defined.␊ |
| 1035 | @param parameter Parameter for the attach call. Not currently used.␊ |
| 1036 | @result Returns kIOReturnSuccess on success. ␊ |
| 1037 | */␊ |
| 1038 | ␊ |
| 1039 | virtual IOReturn attachToDataLinkLayer( IOOptionBits options,␊ |
| 1040 | void * parameter );␊ |
| 1041 | ␊ |
| 1042 | OSMetaClassDeclareReservedUsed(IONetworkInterface, 0);␊ |
| 1043 | ␊ |
| 1044 | /*! @function detachFromDataLinkLayer␊ |
| 1045 | @abstract Detaches the network interface from the BSD data link layer.␊ |
| 1046 | @discussion This function is called by the family to detach the network␊ |
| 1047 | interface managed by an IONetworkInterface from the BSD data link layer.␊ |
| 1048 | This call is made when the interface is terminated, before the last close.␊ |
| 1049 | The family does not implicitly close the gate on the network controller's␊ |
| 1050 | work loop when calling this function. Subclasses can override this function␊ |
| 1051 | to perform additional interface specific work.␊ |
| 1052 | @param options Options for the detach call. None are currently defined.␊ |
| 1053 | @param parameter Parameter for the detach call. Not currently used. ␊ |
| 1054 | */␊ |
| 1055 | ␊ |
| 1056 | virtual void detachFromDataLinkLayer( IOOptionBits options,␊ |
| 1057 | void * parameter );␊ |
| 1058 | ␊ |
| 1059 | OSMetaClassDeclareReservedUsed(IONetworkInterface, 1);␊ |
| 1060 | ␊ |
| 1061 | protected:␊ |
| 1062 | /*! @function feedInputPacketTap␊ |
| 1063 | @abstract Feed received packets to the BPF␊ |
| 1064 | @discussion This function is called by the family for each inbound packet␊ |
| 1065 | to feed it to the BPF function. Interface classes can override if they␊ |
| 1066 | need to provide class specific functionality or modifications to the BPF tap.␊ |
| 1067 | @param mbuf Pointer to the packet.␊ |
| 1068 | */␊ |
| 1069 | virtual void feedPacketInputTap(mbuf_t);␊ |
| 1070 | ␊ |
| 1071 | ␉OSMetaClassDeclareReservedUsed( IONetworkInterface, 2);␊ |
| 1072 | ␊ |
| 1073 | /*! @function feedOutputPacketTap␊ |
| 1074 | @abstract Feed sent packets to the BPF␊ |
| 1075 | @discussion This function is called by the family for each outbound packet␊ |
| 1076 | to feed it to the BPF function. Interface classes can override if they␊ |
| 1077 | need to provide class specific functionality or modifications to the BPF tap.␊ |
| 1078 | @param mbuf Pointer to the packet.␊ |
| 1079 | */␊ |
| 1080 | ␉virtual void feedPacketOutputTap(mbuf_t);␊ |
| 1081 | ␊ |
| 1082 | ␉OSMetaClassDeclareReservedUsed( IONetworkInterface, 3);␊ |
| 1083 | ␉␊ |
| 1084 | ␉virtual bool initIfnetParams(struct ifnet_init_params *params);␊ |
| 1085 | OSMetaClassDeclareReservedUsed( IONetworkInterface, 4);␊ |
| 1086 | ␉␊ |
| 1087 | public:␊ |
| 1088 | // Virtual function padding␊ |
| 1089 | ␉OSMetaClassDeclareReservedUnused( IONetworkInterface, 5);␊ |
| 1090 | ␉OSMetaClassDeclareReservedUnused( IONetworkInterface, 6);␊ |
| 1091 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 7);␊ |
| 1092 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 8);␊ |
| 1093 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 9);␊ |
| 1094 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 10);␊ |
| 1095 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 11);␊ |
| 1096 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 12);␊ |
| 1097 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 13);␊ |
| 1098 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 14);␊ |
| 1099 | OSMetaClassDeclareReservedUnused( IONetworkInterface, 15);␊ |
| 1100 | };␊ |
| 1101 | ␊ |
| 1102 | #endif /* defined(KERNEL) && defined(__cplusplus) */␊ |
| 1103 | ␊ |
| 1104 | #endif /* !_IONETWORKINTERFACE_H */␊ |
| 1105 | |
