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