Return to IONetworkController.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / network

Annotation of XNU/iokit/IOKit/network/IONetworkController.h, revision 1.1

1.1     ! root        1: /*
        !             2:  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
        !             3:  *
        !             4:  * @APPLE_LICENSE_HEADER_START@
        !             5:  * 
        !             6:  * The contents of this file constitute Original Code as defined in and
        !             7:  * are subject to the Apple Public Source License Version 1.1 (the
        !             8:  * "License").  You may not use this file except in compliance with the
        !             9:  * License.  Please obtain a copy of the License at
        !            10:  * http://www.apple.com/publicsource and read it before using this file.
        !            11:  * 
        !            12:  * This Original Code and all software distributed under the License are
        !            13:  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
        !            14:  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
        !            15:  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
        !            16:  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
        !            17:  * License for the specific language governing rights and limitations
        !            18:  * under the License.
        !            19:  * 
        !            20:  * @APPLE_LICENSE_HEADER_END@
        !            21:  */
        !            22: /*
        !            23:  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved. 
        !            24:  *
        !            25:  * IONetworkController.h
        !            26:  *
        !            27:  * Network controller driver superclass.
        !            28:  *
        !            29:  * HISTORY
        !            30:  * 9-Dec-1998       Joe Liu (jliu) created.
        !            31:  *
        !            32:  */
        !            33: 
        !            34: #ifndef _IONETWORKCONTROLLER_H
        !            35: #define _IONETWORKCONTROLLER_H
        !            36: 
        !            37: #include <IOKit/IOService.h>
        !            38: #include <IOKit/IOWorkLoop.h>
        !            39: #include <IOKit/network/IONetworkInterface.h>
        !            40: #include <IOKit/network/IOKernelDebugger.h>
        !            41: 
        !            42: struct mbuf;            // forward declarations
        !            43: class  IOCommandGate;
        !            44: class  IOOutputQueue;
        !            45: class  IONetworkMedium;
        !            46: 
        !            47: // Keys for property table entries.
        !            48: //
        !            49: #define kIOVendor                "IOVendor"                // OSString
        !            50: #define kIOModel                 "IOModel"                 // OSString
        !            51: #define kIORevision              "IORevision"              // OSString
        !            52: #define kIOInfo                  "IOInfo"                  // OSString
        !            53: #define kIOControllerIndex       "IOControllerIndex"       // OSNumber:32
        !            54: #define kIOFeatureSet            "IOFeatureSet"            // OSNumber:32
        !            55: #define kIOFamilyFeatureSet      "IOFamilyFeatureSet"      // OSNumber:32
        !            56: #define kIOMediumDictionary      "IOMediumDictionary"      // OSDictionary
        !            57: #define kIODefaultMedium         "IODefaultMedium"         // OSString
        !            58: #define kIOCurrentMedium         "IOCurrentMedium"         // OSSymbol
        !            59: #define kIOActiveMedium          "IOActiveMedium"          // OSSymbol
        !            60: #define kIOEnableDebugger        "IOEnableDebugger"        // OSString (Yes/No)
        !            61: #define kIOLinkSpeed             "IOLinkSpeed"             // OSNumber:64
        !            62: #define kIOLinkStatus            "IOLinkStatus"            // OSNumber:32
        !            63: #define kIOLinkData              "IOLinkData"              // OSData
        !            64: #define kIOPacketFilters         "IOPacketFilters"         // OSNumber:32
        !            65: #define kIOActivePacketFilters   "IOActivePacketFilters"   // OSNumber:32
        !            66: 
        !            67: /*! @typedef IOPacketBufferConstraints
        !            68:     @discussion Constraint parameters used by allocatePacket() to
        !            69:     align the memory buffer associated with a mbuf.
        !            70:     @field alignStart Alignment for the buffer's starting address.
        !            71:     @field alignLength Buffer length alignment.
        !            72:     @field maxLength Maximum buffer size (not implemented).
        !            73:     */
        !            74: 
        !            75: typedef struct {
        !            76:     UInt32 alignStart;
        !            77:     UInt32 alignLength;
        !            78:     UInt32 maxLength;
        !            79: } IOPacketBufferConstraints;
        !            80: 
        !            81: // Some frequently used alignment constants.
        !            82: //
        !            83: enum {
        !            84:     kIOPacketBufferAlign1   = 1,
        !            85:     kIOPacketBufferAlign2   = 2,
        !            86:     kIOPacketBufferAlign4   = 4,
        !            87:     kIOPacketBufferAlign8   = 8,
        !            88:     kIOPacketBufferAlign16  = 16,
        !            89:     kIOPacketBufferAlign32  = 32,
        !            90: };
        !            91: 
        !            92: // Packet filters. Upper 16-bits are family specific.
        !            93: //
        !            94: enum {
        !            95:     kIOPacketFilterUnicast          = 0x1,
        !            96:     kIOPacketFilterBroadcast        = 0x2,
        !            97:     kIOPacketFilterMulticast        = 0x10,
        !            98:     kIOPacketFilterMulticastAll     = 0x20,
        !            99:     kIOPacketFilterPromiscuous      = 0x100,
        !           100:     kIOPacketFilterPromiscuousAll   = 0x200,
        !           101:     kIOPacketFilterFamilyMask       = 0xffff0000,
        !           102: };
        !           103: 
        !           104: // Generic controller features.
        !           105: //
        !           106: enum {
        !           107:     kIONetworkFeatureNoBSDWait = 0x01,  // start() should not wait for BSD.
        !           108: };
        !           109: 
        !           110:     
        !           111: /*! @class IONetworkController
        !           112:     @abstract IONetworkController implements the framework for a generic 
        !           113:     network controller. A subclass of IONetworkController must provide
        !           114:     additional functionality specific for a particular network family.
        !           115:     In addition, the driver must implement (override) a basic set of 
        !           116:     hardware dependent methods to create a working driver.
        !           117:     
        !           118:     IONetworkController attaches itself to the network layer via an
        !           119:     IONetworkInterface object. A controller object without a companion
        !           120:     interface is not known to the networking system. The controller
        !           121:     interacts with the network layer by calling methods defined by
        !           122:     the interface object. And conversely, the network layer issues
        !           123:     command and packets to the controller through its interface object.
        !           124:     
        !           125:     IONetworkController allocates an IOWorkLoop and an IOCommandGate object.
        !           126:     Most commands (requests) sent from the interface object are handled
        !           127:     by instructing the IOCommandGate instance to call one or more methods,
        !           128:     usually implemented by the driver, that may require hardware access.
        !           129:     Thus interface requests are always serialized. Outbound packets sent
        !           130:     from the interface to the controller have no implicit serialization. 
        !           131:     Drivers must implement an output function that is thread safe, or use
        !           132:     an IOOutputQueue object which will provide a serialization model.
        !           133:     */
        !           134: 
        !           135: class IONetworkController : public IOService
        !           136: {
        !           137:     OSDeclareAbstractStructors(IONetworkController)
        !           138: 
        !           139: public:
        !           140: 
        !           141: /*! @typedef RequestAction
        !           142:     @discussion Prototype for an action to be called through syncRequest().
        !           143:     See syncRequest().
        !           144:     @param arg0 Action argument.
        !           145:     @param arg1 Action argument.
        !           146:     @param arg2 Action argument.
        !           147:     @param arg3 Action argument.
        !           148:     */
        !           149: 
        !           150:     typedef UInt32 (OSObject::*RequestAction)(void * arg0,
        !           151:                                               void * arg1,
        !           152:                                               void * arg2,
        !           153:                                               void * arg3);
        !           154: 
        !           155: private:
        !           156: 
        !           157:     IOWorkLoop *             _workLoop;
        !           158:     IOCommandGate *          _cmdGate;
        !           159:     IOOutputQueue *          _outputQueue;
        !           160:     OSSet *                  _clientSet;
        !           161:     OSObject *               _reqClient;
        !           162:     UInt32                   _alignStart;
        !           163:     UInt32                   _alignLength;
        !           164:     UInt32                   _alignPadding;
        !           165:     bool                     _handleReady;
        !           166:     bool                     _requestEnabled;
        !           167:     IOLock *                 _mediumLock;
        !           168:     IODebuggerLockState      _debugLockState;
        !           169:     UInt32                   _linkStatus;
        !           170:     UInt64                   _linkSpeed;
        !           171:     OSData *                 _linkData;
        !           172:     const IONetworkMedium *  _activeMedium;
        !           173:     const IONetworkMedium *  _currentMedium;
        !           174: 
        !           175:     bool     _controllerIsReady();
        !           176:     IOReturn _enable(IOService * client);
        !           177:     IOReturn _disable(IOService * client);
        !           178:     void     commandHandler(void *, void *, void *, void *);
        !           179:     IOReturn selectMediumWithName(const OSSymbol * mediumName);
        !           180: 
        !           181:     bool setMediumProperty(const OSSymbol *         key,
        !           182:                            const IONetworkMedium *  medium,
        !           183:                            const IONetworkMedium ** cache,
        !           184:                            bool                     force = false,
        !           185:                            bool *                   changed = 0);
        !           186: 
        !           187:     bool setLink64Property(const char * key,
        !           188:                            UInt64       value,
        !           189:                            UInt64 *     cache,
        !           190:                            bool         force = false,
        !           191:                            bool *       changed = 0);
        !           192: 
        !           193:     bool setLink32Property(const char * key,
        !           194:                            UInt32       value,
        !           195:                            UInt32 *     cache,
        !           196:                            bool         force = false,
        !           197:                            bool *       changed = 0);
        !           198: 
        !           199:     bool verifyMediumDictionary(const OSDictionary * mediumDict);
        !           200: 
        !           201:     static void _logMbuf(struct mbuf * m);
        !           202: 
        !           203:     static void _enableSyncRequestFilter(IONetworkController *, bool);
        !           204: 
        !           205:     static void debugRxHandler(IOService * handler,
        !           206:                                void *      buffer,
        !           207:                                UInt *      length,
        !           208:                                UInt        timeout);
        !           209: 
        !           210:     static void debugTxHandler(IOService * handler,
        !           211:                                void *      buffer,
        !           212:                                UInt        length);
        !           213: 
        !           214: public:
        !           215: 
        !           216: /*! @function initialize
        !           217:     @abstract IONetworkController class initializer.
        !           218:     @discussion Create often used OSSymbol objects that are used as keys.
        !           219:     This method is called explicitly by a line in IOStartIOKit.cpp and not
        !           220:     by the OSDefineMetaClassAndInit() mechanism, since the OSSymbol class
        !           221:     is not guaranteed to be initialized first, and likewise for the
        !           222:     OSSymbol pool. */
        !           223: 
        !           224:     static void initialize();
        !           225: 
        !           226: /*! @function init
        !           227:     @abstract Initialize the IONetworkController instance.
        !           228:     @discussion Instance variables are initialized to their default values,
        !           229:     then super::init() is called.
        !           230:     @param properties A dictionary object containing a property table.
        !           231:     @result true on success, false otherwise. */ 
        !           232: 
        !           233:     virtual bool init(OSDictionary * properties);
        !           234: 
        !           235: /*! @function start
        !           236:     @abstract Start the controller driver.
        !           237:     @discussion Called when the controller was matched to a provider and
        !           238:     has been selected to start running. IONetworkController will allocate
        !           239:     resources and gather the controller's properties. No I/O will be
        !           240:     triggered until the subclass attaches a client object from its own
        !           241:     start method. Subclasses must override this method and call
        !           242:     super::start() at the beginning of its implementation. They should
        !           243:     also check the return value to make sure their superclass was
        !           244:     started successfully. The resources allocated by IONetworkController
        !           245:     include: An IOWorkLoop object, an IOCommandGate object to handle 
        !           246:     synchronous requests, an OSSet to track our clients, and an optional
        !           247:     IOOutputQueue object for output queueing.
        !           248: 
        !           249:     Tasks that are usually performed by a driver's start method are;
        !           250:     resource allocation, hardware initialization, allocation of 
        !           251:     IOEventSources and attaching them to an IOWorkLoop object,
        !           252:     publishing a medium dictionary, and finally, attaching an
        !           253:     interface object when the driver is ready to handle client
        !           254:     requests.
        !           255:     @param provider The provider that the controller was matched
        !           256:     (and attached) to.
        !           257:     @result true on success, false otherwise. */
        !           258: 
        !           259:     virtual bool start(IOService * provider);
        !           260: 
        !           261: /*! @function stop
        !           262:     @abstract Stop the controller driver.
        !           263:     @discussion The opposite of start(). The controller has been
        !           264:     instructed to stop running. This method is called when the
        !           265:     driver has been terminated. The stop() method should release
        !           266:     resources and undo actions performed by start(). Subclasses
        !           267:     must override this method and call super::stop() at the end
        !           268:     of its implementation.
        !           269:     @param provider The provider that the controller was matched
        !           270:     (and attached) to. */
        !           271: 
        !           272:     void stop(IOService * provider);
        !           273: 
        !           274: /*! @function outputPacket
        !           275:     @abstract Transmit a packet mbuf.
        !           276:     @discussion If an IOOutputQueue was allocated and returned by 
        !           277:     createOutputQueue(), then this method will be called by the queue object.
        !           278:     Otherwise, an interface object will call this method directly upon 
        !           279:     receiving an output packet from the network layer. When a queue object
        !           280:     is not present, this method must be safe from multiple client threads,
        !           281:     each pushing a packet to be sent on the wire.
        !           282:     
        !           283:     There is no upper limit on the number of mbufs, hence the number of
        !           284:     memory fragments, in the mbuf chain provided. Drivers must be able to
        !           285:     handle cases when the chain might exceed the limit supported by their
        !           286:     DMA engines, and perform coalescing to copy the various memory fragments
        !           287:     into a lesser number of fragments. This complexity can be hidden from
        !           288:     a driver when an IOMBufMemoryCursor is used, which is able to convert
        !           289:     a mbuf chain into a physical address scatter-gather list that will not
        !           290:     exceed a specified number of physically contiguous memory segments.
        !           291:     See IOMBufMemoryCursor.
        !           292: 
        !           293:     Packets may also be chained to form a packet chain. Although the
        !           294:     network layer, through the interface object, will currently only
        !           295:     send a single mbuf packet to the controller for each outputPacket()
        !           296:     call, it is possible for this to change. When a queue object is used,
        !           297:     the queue will automatically accept a single packet or a packet chain,
        !           298:     but it will call outputPacket() for each packet removed from the queue.
        !           299: 
        !           300:     The implementation in IONetworkController performs no useful action
        !           301:     and will drop all packets. A driver must always override this method.
        !           302: 
        !           303:     @param m The packet mbuf.
        !           304:     @result A return code defined by the caller. */
        !           305: 
        !           306:     virtual UInt32 outputPacket(struct mbuf * m);
        !           307: 
        !           308: /*! @function getFeatureSet
        !           309:     @discussion Report features supported by the controller.
        !           310:     @result Returns 0. Drivers may override this method and return a mask
        !           311:     containing all supported feature bits. */
        !           312: 
        !           313:     virtual UInt32 getFeatureSet() const;
        !           314: 
        !           315: /*! @function getFamilyFeatureSet
        !           316:     @discussion Report family specific features supported by the controller.
        !           317:     @result Drivers may override this method and return a mask containing
        !           318:     all supported family feature bits. */
        !           319: 
        !           320:     virtual UInt32 getFamilyFeatureSet() const = 0;
        !           321: 
        !           322: /*! @function getVendorString
        !           323:     @result Return a vendor string. i.e. "Apple" */
        !           324: 
        !           325:     virtual const char * getVendorString() const = 0;
        !           326: 
        !           327: /*! @function getModelString
        !           328:     @result Return a string describing the model of the network controller.
        !           329:     i.e. "BMac Ethernet" */
        !           330: 
        !           331:     virtual const char * getModelString() const = 0;
        !           332: 
        !           333: /*! @function getRevisionString
        !           334:     @result Return a string describing the revision level of the 
        !           335:     controller. */
        !           336: 
        !           337:     virtual const char * getRevisionString() const;
        !           338: 
        !           339: /*! @function getInfoString
        !           340:     @result Return a string containing any additional information about
        !           341:     the controller and/or driver. */
        !           342: 
        !           343:     virtual const char * getInfoString() const;
        !           344: 
        !           345: /*! @function getCurrentMedium
        !           346:     @abstract Get the currently selected medium.
        !           347:     @discussion Returns the currently selected medium object. If the driver
        !           348:     has yet to assign an entry in its medium dictionary as the current medium 
        !           349:     using the setCurrentMedium() method, then the driver's property table is 
        !           350:     consulted and a default medium property (can be set by the user), is
        !           351:     looked up and the corresponding entry in the medium dictionary is returned.
        !           352:     Therefore, drivers can always call getCurrentMedium() to either get
        !           353:     the current medium selected by the driver, or the default
        !           354:     medium chosen by the user.
        !           355:     @result The current medium entry from the medium dictionary, or 0
        !           356:     if a matching entry was not found. */
        !           357: 
        !           358:     virtual const IONetworkMedium * getCurrentMedium() const;
        !           359: 
        !           360: /*! @function getMediumDictionary
        !           361:     @abstract Returns the medium dictionary published by the driver.
        !           362:     @discussion Returns the medium dictionary published by the driver
        !           363:     through publishMediumDictionary(). Use copyMediumDictionary() to
        !           364:     get a copy of the medium dictionary.
        !           365:     @result The published medium dictionary, or 0 if the driver has not
        !           366:     yet published a medium dictionary using publishMediumDictionary(). */
        !           367: 
        !           368:     virtual const OSDictionary * getMediumDictionary() const;
        !           369: 
        !           370: /*! @function copyMediumDictionary
        !           371:     @abstract Returns a copy of the medium dictionary published by the driver.
        !           372:     @discussion The caller is responsible for releasing the dictionary
        !           373:     object returned. Use getMediumDictionary() to get a reference to the
        !           374:     published medium dictionary instead of creating a copy.
        !           375:     @result A copy of the medium dictionary, or 0 if the driver has not
        !           376:     published a medium dictionary using publishMediumDictionary(). */
        !           377: 
        !           378:     virtual OSDictionary * copyMediumDictionary() const;
        !           379: 
        !           380: /*! @function syncRequest
        !           381:     @abstract Perform a request action synchronously.
        !           382:     @discussion Used both internally and also by clients to execute an
        !           383:     arbitrary request action using the IOCommandGate's runAction()
        !           384:     method. For client requests, where the client field is not equal to
        !           385:     'this', the request is filtered by calling syncRequestFilter() to
        !           386:     qualify the client request. This filter function must return true
        !           387:     in order for the request to be accepted and the request action called.
        !           388:     @param client The client (caller) of the synchronous request.
        !           389:     @param target The target object that implements the request action.
        !           390:     @param action The action to perform.
        !           391:     @param ret    The return value from the action is written to the
        !           392:                   integer with the provided address. The result is
        !           393:                   not written if the request was rejected by the request
        !           394:                   filter.
        !           395:     @param arg0 Optional action argument.
        !           396:     @param arg1 Optional action argument.
        !           397:     @param arg2 Optional action argument.
        !           398:     @param arg3 Optional action argument.
        !           399:     @result kIOReturnNotReady if the client request was rejected by the filter.
        !           400:     Otherwise kIOReturnSuccess is returned. */
        !           401: 
        !           402:     virtual IOReturn syncRequest(OSObject *     client,
        !           403:                                  OSObject *     target,
        !           404:                                  RequestAction  action,
        !           405:                                  UInt32 *       ret  = 0,
        !           406:                                  void *         arg0 = 0,
        !           407:                                  void *         arg1 = 0,
        !           408:                                  void *         arg2 = 0,
        !           409:                                  void *         arg3 = 0);
        !           410: 
        !           411: /*! @function getOutputHandler
        !           412:     @abstract Get the address of the method designated to handle output 
        !           413:     packets.
        !           414:     @result the address of the outputPacket() method. */
        !           415: 
        !           416:     virtual IOOutputAction getOutputHandler() const;
        !           417: 
        !           418: /*! @function doEnablePacketFilters
        !           419:     @discussion Call enablePacketFilters() through syncRequest().
        !           420:     See enablePacketFilters(). */
        !           421: 
        !           422:     virtual IOReturn doEnablePacketFilters(IOService * client,
        !           423:                                            UInt32      filters,
        !           424:                                            UInt32 *    activeFiltersP = 0);
        !           425: 
        !           426: /*! @function doGetPacketFilters
        !           427:     @discussion Call getPacketFilters() through syncRequest().
        !           428:     See getPacketFilters(). */
        !           429: 
        !           430:     virtual IOReturn doGetPacketFilters(IOService * client, UInt32 * filtersP);
        !           431: 
        !           432: /*! @function doEnable
        !           433:     @discussion Call enable(IOService *) through syncRequest().
        !           434:     See enable(). */
        !           435: 
        !           436:     virtual IOReturn doEnable(IOService * client);
        !           437: 
        !           438: /*! @function doDisable
        !           439:     @discussion Call disable(IOService *) through syncRequest().
        !           440:     See disable(). */
        !           441: 
        !           442:     virtual IOReturn doDisable(IOService * client);
        !           443: 
        !           444: /*! @function doGetControllerIndex
        !           445:     @discussion Call getControllerIndex(IOService *) through syncRequest().
        !           446:     See getControllerIndex(). */
        !           447: 
        !           448:     virtual IOReturn doGetControllerIndex(IOService * client,
        !           449:                                           UInt32 *    index);
        !           450: 
        !           451: /*! @function doSetMaxTransferUnit
        !           452:     @discussion Call setMaxTransferUnit() through syncRequest().
        !           453:     See setMaxTransferUnit(). */
        !           454: 
        !           455:     virtual IOReturn doSetMaxTransferUnit(IOService * client, UInt32 mtu);
        !           456: 
        !           457: /*! @function doSelectMedium
        !           458:     @discussion Call selectMedium() through syncRequest().
        !           459:     See selectMedium(). */
        !           460: 
        !           461:     virtual IOReturn doSelectMedium(IOService *      client,
        !           462:                                     const OSSymbol * mediumName);
        !           463: 
        !           464: /*! @function doSetOutputQueueCapacity
        !           465:     @discussion Call setOutputQueueCapacity() through syncRequest().
        !           466:     See setOutputQueueCapacity(). */
        !           467: 
        !           468:     virtual IOReturn doSetOutputQueueCapacity(IOService * client,
        !           469:                                               UInt32      capacity);
        !           470: 
        !           471: /*! @function doGetOutputQueueCapacity
        !           472:     @discussion Call getOutputQueueCapacity() through syncRequest().
        !           473:     See getOutputQueueCapacity(). */
        !           474: 
        !           475:     virtual IOReturn doGetOutputQueueCapacity(IOService * client,
        !           476:                                               UInt32 *    capacityP);
        !           477: 
        !           478: /*! @function doGetOutputQueueSize
        !           479:     @discussion Call getOutputQueueSize() through syncRequest().
        !           480:     See getOutputQueueSize(). */
        !           481: 
        !           482:     virtual IOReturn doGetOutputQueueSize(IOService * client,
        !           483:                                           UInt32 *    sizeP);
        !           484: 
        !           485: /*! @function doFlushOutputQueue
        !           486:     @discussion Call flushOutputQueue() through syncRequest().
        !           487:     See flushOutputQueue(). */
        !           488: 
        !           489:     virtual IOReturn doFlushOutputQueue(IOService * client,
        !           490:                                         UInt32 *    flushCountP);
        !           491: 
        !           492: /*! @function doPerformDiagnostics
        !           493:     @discussion Call performDiagnostics() through syncRequest().
        !           494:     See performDiagnostics(). */
        !           495: 
        !           496:     virtual IOReturn doPerformDiagnostics(IOService * client,
        !           497:                                           UInt32 *    failureCode);
        !           498: 
        !           499: protected:
        !           500: 
        !           501: /*! @function free
        !           502:     @abstract Free the IONetworkController instance.
        !           503:     @discussion Free the IONetworkController instance and all allocated
        !           504:     resources, then call super::free(). */
        !           505: 
        !           506:     virtual void free();
        !           507: 
        !           508: /*! @function setOutputQueueCapacity
        !           509:     @abstract Adjust the capacity of the output queue.
        !           510:     @discussion A client request to adjust the capacity of the driver's
        !           511:     output queue (number of packets the queue can hold). If a driver does
        !           512:     not override this method, then the default action is to forward the
        !           513:     request to an IOOutputQueue object if it was created. Otherwise return
        !           514:     kIOReturnUnsupported.
        !           515:     @param capacity The new capacity of the output queue.
        !           516:     @result kIOReturnSuccess on success, kIOReturnBadArgument if the
        !           517:     specified capacity is invalid, or kIOReturnUnsupported if the
        !           518:     function is not supported. */
        !           519: 
        !           520:     virtual IOReturn setOutputQueueCapacity(UInt32 capacity);
        !           521: 
        !           522: /*! @function getOutputQueueCapacity
        !           523:     @abstract Get the capacity of the output queue.
        !           524:     @discussion A client request to get the capacity of the driver's
        !           525:     output queue. If a driver does not override this method, then the
        !           526:     default action is to forward the request to an IOOutputQueue object
        !           527:     if it was created. Otherwise return kIOReturnUnsupported.
        !           528:     @param capacityP Address of an integer where the capacity
        !           529:     shall be written to.
        !           530:     @result kIOReturnSuccess on success, or kIOReturnUnsupported if an
        !           531:     IOOutputQueue object was not created. */
        !           532: 
        !           533:     virtual IOReturn getOutputQueueCapacity(UInt32 * capacityP) const;
        !           534: 
        !           535: /*! @function getOutputQueueSize
        !           536:     @abstract Get the number of packets in the output queue.
        !           537:     @discussion A client request to get the number of packets currently held
        !           538:     by the queue. If a driver does not override this method, then the default
        !           539:     action is to forward the request to an IOOutputQueue object if it was 
        !           540:     created. Otherwise return kIOReturnUnsupported.
        !           541:     @param sizeP Address of an integer where the queue size shall be
        !           542:            written to.
        !           543:     @result kIOReturnSuccess on success, or kIOReturnUnsupported if an
        !           544:     IOOutputQueue object was not created. */
        !           545: 
        !           546:     virtual IOReturn getOutputQueueSize(UInt32 * sizeP) const;
        !           547: 
        !           548: /*! @function flushOutputQueue
        !           549:     @abstract Discard all packets in the output queue.
        !           550:     @discussion A client request to flush all packets currently held by the
        !           551:     queue, and return the number of packets discarded. If a driver does not
        !           552:     override this method, then the default action is to forward the request
        !           553:     to an IOOutputQueue object if it was created. Otherwise return
        !           554:     kIOReturnUnsupported.
        !           555:     @param flushCountP Address of an integer where the number of
        !           556:     discarded packets shall be written to.
        !           557:     @result kIOReturnSuccess on success, or kIOReturnUnsupported if an
        !           558:     IOOutputQueue object was not created. */
        !           559: 
        !           560:     virtual IOReturn flushOutputQueue(UInt32 * flushCountP);
        !           561: 
        !           562: /*! @function ready
        !           563:     @abstract An indication that the controller is ready to service
        !           564:     clients.
        !           565:     @discussion This method is called the first time that a controller
        !           566:     driver calls attachInterface() or attachDebuggerClient(), which is
        !           567:     an indication that the driver has been started and is ready to
        !           568:     service client requests. IONetworkController uses this method to
        !           569:     complete its initialization before any client objects are attached.
        !           570:     @param provider The controller's provider.
        !           571:     @result true on success, false otherwise. */
        !           572: 
        !           573:     virtual bool ready(IOService * provider);
        !           574: 
        !           575: /*! @function enable
        !           576:     @abstract An enable request from an interface client.
        !           577:     @discussion Called by an interface client to enable the controller.
        !           578:     This method must bring up the hardware and enable event sources
        !           579:     to prepare for packet transmission and reception. A driver should
        !           580:     delay the allocation of most runtime resources until this method is
        !           581:     called to conserve shared system resources.
        !           582:     @param interface The interface client object that requested the enable.
        !           583:     @result kIOReturnUnsupported. Driver may override this method and
        !           584:     return kIOReturnSuccess on success, or an error code otherwise. */
        !           585: 
        !           586:     virtual IOReturn enable(IONetworkInterface * interface);
        !           587: 
        !           588: /*! @function disable
        !           589:     @abstract A disable request from an interface client.
        !           590:     @discussion Called by an interface object to disable the controller.
        !           591:     This method should quiesce the hardware and disable event sources.
        !           592:     Any resources allocated in enable() should also be deallocated.
        !           593:     @param interface The interface object that requested the disable.
        !           594:     @result kIOReturnUnsupported. Driver may override this method and
        !           595:     return kIOReturnSuccess on success, or an error code otherwise. */
        !           596: 
        !           597:     virtual IOReturn disable(IONetworkInterface * interface);
        !           598: 
        !           599: /*! @function enable
        !           600:     @abstract An enable request from a client.
        !           601:     @discussion Handle an enable request from a client. The client
        !           602:     object is typecasted using OSDynamicCast, and if the client is an
        !           603:     IOKernelDebugger or an IONetworkInterface, then an overloaded enable
        !           604:     method that takes a more specific argument is called. If the client
        !           605:     matches neither type, a kIOReturnBadArgument is returned.
        !           606:     A driver has the option of override this generic enable method,
        !           607:     or the derived version.
        !           608:     @param client The client object requesting the enable.
        !           609:     @result The return value from the derived enable method, or
        !           610:     kIOReturnBadArgument if the client's type is unknown. */
        !           611: 
        !           612:     virtual IOReturn enable(IOService * client);
        !           613: 
        !           614: /*! @function disable
        !           615:     @abstract A disable request from a client.
        !           616:     @discussion Handle an enable request from a client. The client
        !           617:     object is typecasted using OSDynamicCast, and if the client is an
        !           618:     IOKernelDebugger or an IONetworkInterface, then an overloaded disable
        !           619:     method that takes a more specific argument is called. If the client
        !           620:     matches neither type, a kIOReturnBadArgument is returned.
        !           621:     A driver has the option of override this generic enable method,
        !           622:     or the derived version.
        !           623:     @param client The client object requesting the disable.
        !           624:     @result The return from the derived disable method, or
        !           625:     kIOReturnBadArgument if the client's type is unknown. */
        !           626:     
        !           627:     virtual IOReturn disable(IOService * client);
        !           628: 
        !           629: /*! @function getControllerIndex
        !           630:     @abstract Return an ordinal number for multiport adapters.
        !           631:     @discussion Return an ordinal number for multiport network adapters.
        !           632:     The implementation in IONetworkController will work for PCI controllers
        !           633:     behind a PCI-PCI bridge. This method exists solely to support the
        !           634:     current interface naming scheme, and is likely to
        !           635:     undergo changes or may disappear in the future.
        !           636:     @param indexP The oridinal number should be written to the
        !           637:            integer at this address.
        !           638:     @result kIOReturnSuccess. */
        !           639: 
        !           640:     virtual IOReturn getControllerIndex(UInt32 * indexP) const;
        !           641: 
        !           642: /*! @function setMaxTransferUnit
        !           643:     @abstract Change the controller's MTU size.
        !           644:     @discussion A client request for the controller to change to
        !           645:     a new MTU size.
        !           646:     @param mtu The new MTU size requested.
        !           647:     @result kIOReturnUnsupported. Drivers may override this method
        !           648:     and return either kIOReturnSuccess to indicate that the new MTU size
        !           649:     was accepted and is in effect, or an error to indicate failure. */
        !           650: 
        !           651:     virtual IOReturn setMaxTransferUnit(UInt32 mtu);
        !           652: 
        !           653: /*! @function performDiagnostics
        !           654:     @abstract A request for the driver to perform hardware diagnostics.
        !           655:     @discussion A client request for the driver to perform hardware 
        !           656:     diagnostics and return the test result after completion.
        !           657:     @param resultCodeP In addition to the return code, drivers may
        !           658:     write a hardware specific result code to the integer at this
        !           659:     address.
        !           660:     
        !           661:     @result kIOReturnSuccess if hardware passed all test, otherwise
        !           662:     an appropriate error code should be returned. The default return
        !           663:     is always kIOReturnUnsupported. */
        !           664: 
        !           665:     virtual IOReturn performDiagnostics(UInt32 * resultCodeP);
        !           666: 
        !           667: /*! @function publishCapabilities
        !           668:     @abstract Publish controller's properties and capabilities.
        !           669:     @discussion Discover and publish controller capabilities to the
        !           670:     property table. This method is called by ready().
        !           671:     @result true if all capabilities were discovered and published
        !           672:     successfully, false otherwise. Returning false will prevent client
        !           673:     objects from attaching to the controller since a property that
        !           674:     a client depends on may be missing. */
        !           675: 
        !           676:     virtual bool publishCapabilities();
        !           677: 
        !           678: /*! @function publishMediumDictionary
        !           679:     @abstract Publish a medium dictionary.
        !           680:     @discussion Called by drivers to publish their medium dictionary.
        !           681:     The dictionary consist of IONetworkMedium entries that represent
        !           682:     the entire media selection supported by the hardware. This method
        !           683:     will make a copy of the provided dictionary, then add the copy to
        !           684:     the driver's property table. The dictionary provided can be
        !           685:     released after this call returns. It is permissible to call
        !           686:     this method multiple times, which may be necessary if the hardware's
        !           687:     media capability changes dynamically. However, if this were not
        !           688:     so, then drivers will typically call this method from its start() 
        !           689:     implementation, after the hardware capability is discovered.
        !           690: 
        !           691:     Several methods depends on the presence of a medium dictionary.
        !           692:     They should be called after the dictionary has been published.
        !           693:     Those are:
        !           694:         selectMedium()
        !           695:         setCurrentMedium()
        !           696:         getCurrentMedium()
        !           697:         getMediumDictionary()
        !           698:         copyMediumDictionary()
        !           699:     
        !           700:     Calling publishMediumDictionary() will cause a media change event
        !           701:     to be delivered to all attached interface clients.
        !           702:     @param mediumDict A dictionary containing IONetworkMedium objects.
        !           703:     @result true if the dictionary is valid, and was successfully
        !           704:     added to the property table, false otherwise. */
        !           705: 
        !           706:     virtual bool publishMediumDictionary(const OSDictionary * mediumDict);
        !           707: 
        !           708: /*! @function setCurrentMedium
        !           709:     @abstract Designate an entry in the published medium dictionary as
        !           710:     the currently selected medium.
        !           711:     @discussion From the set of medium objects in the medium dictionary
        !           712:     published by the driver, one of them can be designated as the
        !           713:     currently selected medium. Drivers should call this method whenever
        !           714:     their media selection changes. An entry in the driver's property
        !           715:     table is updated to advertise the current medium.
        !           716:     
        !           717:     A media change event will be broadcasted to all attached interface
        !           718:     clients when the current medium property changes.
        !           719:     
        !           720:     @param medium A medium object to promote as the current medium.
        !           721:     @result true if the medium dictionary exists, the medium object
        !           722:     provided matches an entry in this dictionary, and the property
        !           723:     table update was successful, false otherwise. */
        !           724: 
        !           725:     virtual bool setCurrentMedium(const IONetworkMedium * medium);
        !           726: 
        !           727: /*! @function selectMedium
        !           728:     @abstract Change the controller's medium selection.
        !           729:     @discussion A client request for the controller to change the
        !           730:     selected medium. Drivers may override this method and provide
        !           731:     an implementation appropriate for its hardware, then call
        !           732:     setCurrentMedium() to update the current medium property if
        !           733:     a change occurred.
        !           734:     @param medium An entry in the published medium dictionary.
        !           735:     @result kIOReturnUnsupported. Drivers may override this method and
        !           736:     return kIOReturnSuccess if the selected medium was activated,
        !           737:     or an error code otherwise. */
        !           738: 
        !           739:     virtual IOReturn selectMedium(const IONetworkMedium * medium);
        !           740: 
        !           741: /*! @function setLinkStatus
        !           742:     @abstract Report the link status and the active medium.
        !           743:     @discussion Update the link status parameters published by the
        !           744:     controller. Drivers should call this method whenever the link
        !           745:     status changes. Never call this method from interrupt context
        !           746:     since this method may block. An event will be sent to all
        !           747:     attached interface objects when a change is detected.
        !           748:     @param status Link status bits.
        !           749:            See IONetworkMedium.h for defined link status bits.
        !           750:     @param speed Link speed in units of bits per second.
        !           751:     @param activeMedium A medium entry in the published medium dictionary
        !           752:            where the link was established. This may not be the same as the
        !           753:            current medium. See setCurrentMedium().
        !           754:     @param data An OSData containing any additional link information.
        !           755:     @result true if all link properties were successfully updated,
        !           756:     false otherwise. */
        !           757: 
        !           758:     virtual bool setLinkStatus(UInt32                  status,
        !           759:                                UInt64                  speed,
        !           760:                                const IONetworkMedium * activeMedium,
        !           761:                                OSData *                data = 0);
        !           762: 
        !           763: /*! @function syncRequestFilter
        !           764:     @abstract Filter client requests sent to syncRequest().
        !           765:     @discussion This method is called to qualify all client requests
        !           766:     sent to syncRequest(). This implementation will either allow or
        !           767:     refuse all requests, and this behavior is set by calling the 
        !           768:     enableSyncRequest() or disableSyncRequest() methods. By default,
        !           769:     all requests are allowed.
        !           770:     @param client The client of the synchronous request.
        !           771:     @param target The target object that implements the request action.
        !           772:     @param action The action to perform.
        !           773:     @param arg0 Action argument.
        !           774:     @param arg1 Action argument.
        !           775:     @param arg2 Action argument.
        !           776:     @param arg3 Action argument.
        !           777:     @result true to accept the request and allow the request action to be
        !           778:     called, or false to refuse it. */
        !           779: 
        !           780:     virtual bool syncRequestFilter(OSObject *     client,
        !           781:                                    OSObject *     target,
        !           782:                                    RequestAction  action,
        !           783:                                    void *         arg0,
        !           784:                                    void *         arg1,
        !           785:                                    void *         arg2,
        !           786:                                    void *         arg3);
        !           787: 
        !           788: /*! @function enableSyncRequest
        !           789:     @abstract Set syncRequestFilter() to accept all client requests.
        !           790:     @discussion Enable all client requests sent to the syncRequest() method.
        !           791:     Don't use this method if the driver overrides syncRequestFilter(). */
        !           792: 
        !           793:     virtual void enableSyncRequest();
        !           794: 
        !           795: /*! @function disableSyncRequest
        !           796:     @abstract Set syncRequestFilter() to refuse all client requests.
        !           797:     @discussion Disable all client requests sent to the syncRequest() method.
        !           798:     Don't use this method if the driver overrides syncRequestFilter(). */
        !           799: 
        !           800:     virtual void disableSyncRequest();  
        !           801: 
        !           802: /*! @function getSyncRequestClient
        !           803:     @abstract Get request client.
        !           804:     @discussion Methods that are called by syncRequest() can call this
        !           805:     to get the client object which initiated the request.
        !           806:     @result The request client. If the caller's context does not indicate
        !           807:     that it is running through syncRequest(), then 0 is returned. */
        !           808: 
        !           809:     virtual OSObject * getSyncRequestClient() const;
        !           810: 
        !           811: /*! @function handleOpen
        !           812:     @abstract Handle a client open.
        !           813:     @discussion Handle a client open on the controller object. IOService
        !           814:     calls this method with the arbitration lock held. Subclasses
        !           815:     should not override this method.
        !           816:     @param client The client that is trying to open the controller.
        !           817:     @param options Not used. See IOService.
        !           818:     @param argument Not used. See IOService.
        !           819:     @result true to accept the client open, false to refuse the open. */
        !           820: 
        !           821:     virtual bool handleOpen(IOService *  client,
        !           822:                             IOOptionBits options,
        !           823:                             void *       argument);
        !           824: 
        !           825: /*! @function handleClose
        !           826:     @abstract Handle a client close.
        !           827:     @discussion Handle a close from one of our client objects. IOService
        !           828:     calls this method with the arbitration lock held. Subclasses
        !           829:     should not override this method.
        !           830:     @param client The client that has closed the controller.
        !           831:     @param options Not used. See IOService. */
        !           832: 
        !           833:     virtual void handleClose(IOService * client, IOOptionBits options);
        !           834: 
        !           835: /*! @function handleIsOpen
        !           836:     @abstract Query a client that has an open on the controller.
        !           837:     @discussion This method is always called by IOService with the
        !           838:     arbitration lock held. Subclasses should not override this method.
        !           839:     @result true if the specified client, or any client if none is
        !           840:     specified, presently has an open on this object. */
        !           841: 
        !           842:     virtual bool handleIsOpen(const IOService * client) const;
        !           843: 
        !           844: /*! @function attachInterface
        !           845:     @abstract Attach a new interface client object.
        !           846:     @discussion Create a new interface client object and attach it
        !           847:     to the controller. The createInterface() method is called to
        !           848:     perform the allocation and initialization, followed by a call to 
        !           849:     configureInterface() to configure the interface. Both of these
        !           850:     methods can be overridden by subclasses to customize the
        !           851:     interface client attached. Drivers must call attachInterface()
        !           852:     from its start() method, after it is ready to service client requests.
        !           853:     @param interfaceP If successful (return value is true), then the
        !           854:     interface object will be written to the handle provided.
        !           855:     @param doRegister If true, then registerService() is called to register
        !           856:     the interface, which will trigger the matching process, and cause the 
        !           857:     interface to become registered with the network layer. For drivers that
        !           858:     wish to delay the registration, and hold off servicing requests and data
        !           859:     packets from the network layer, set doRegister to false and call 
        !           860:     registerService() on the interface client when the controller becomes
        !           861:     ready.
        !           862:     @result true on success, false otherwise. */
        !           863: 
        !           864:     virtual bool attachInterface(IONetworkInterface ** interface,
        !           865:                                  bool  doRegister = true);
        !           866: 
        !           867:     virtual bool attachNetworkInterface(IONetworkInterface ** interface,
        !           868:                                         bool  doRegister = true);  // obsolete
        !           869: 
        !           870: /*! @function detachInterface
        !           871:     @abstract Detach an interface client object.
        !           872:     @discussion This method will check that the object provided is indeed
        !           873:     an IONetworkInterface, and if so its terminate() method is called.
        !           874:     The interface object will close and detach from its controller only
        !           875:     after the network layer has removed all references to the data
        !           876:     structures exposed by the interface.
        !           877:     @param interface An interface object to be detached.
        !           878:     @param sync If true, the interface is terminated synchronously.
        !           879:            Note that this may cause detachInterface() to block
        !           880:            for an indefinite period of time. */
        !           881: 
        !           882:     virtual void detachInterface(IONetworkInterface * interface,
        !           883:                                  bool                 sync = false);
        !           884: 
        !           885: /*! @function getPacketBufferConstraints
        !           886:     @abstract Get controller's packet buffer constraints.
        !           887:     @discussion Called by start() to obtain the constraints on the
        !           888:     memory buffer associated with each mbuf allocated through
        !           889:     allocatePacket(). Drivers can override this method to specify
        !           890:     their buffer constraints imposed by their bus master hardware.
        !           891:     Note that outbound packets, those that originate from the
        !           892:     network stack, are not subject to the constraints reported here.
        !           893:     @param constraintsP A pointer to an IOPacketBufferConstraints
        !           894:     structure that that this method is expected to initialize.
        !           895:     See IOPacketBufferConstraints structure definition.
        !           896:     */
        !           897: 
        !           898:     virtual void getPacketBufferConstraints(
        !           899:                     IOPacketBufferConstraints * constraintsP) const;
        !           900: 
        !           901: /*! @function allocatePacket
        !           902:     @discussion Allocate a mbuf packet with the given size. This method
        !           903:     will always return a single mbuf unless the size requested (plus the
        !           904:     alignment padding) is greater than MCLBYTES. The mbuf (or a mbuf
        !           905:     chain) returned is aligned according to the constraints reported
        !           906:     by getPacketBufferConstraints().
        !           907:     
        !           908:     The m_len and pkthdr.len fields in the mbuf is updated by this
        !           909:     method, thus allowing the packet to be passed directly to an
        !           910:     IOMbufMemoryCursor object in order to convert the mbuf to a
        !           911:     scatter-gather list.
        !           912: 
        !           913:     @param size The desired size of the mbuf packet.
        !           914:     @result The allocated mbuf packet, or 0 if allocation failed. */
        !           915: 
        !           916:     virtual struct mbuf * allocatePacket(UInt size);
        !           917: 
        !           918: /*! @function copyPacket
        !           919:     @discussion Make a copy of a mbuf, and return the copy.
        !           920:     The source mbuf is not modified.
        !           921:     @param m The source mbuf.
        !           922:     @param size The number of bytes to copy. If set to 0, then the entire
        !           923:     source mbuf is copied (source length is taken from the m_pkthdr.len).
        !           924:     @result A new mbuf created from the source packet. */
        !           925: 
        !           926:     virtual struct mbuf * copyPacket(const struct mbuf * m, UInt size = 0);
        !           927: 
        !           928: /*! @function replacePacket
        !           929:     @discussion Replace the mbuf pointed by the given pointer with
        !           930:     another mbuf. Drivers can call this method to replace a mbuf before
        !           931:     passing the original mbuf, which contains a received frame, to the
        !           932:     network layer.
        !           933:     @param mp A pointer to the original mbuf that shall be updated by this
        !           934:     method to point to the new mbuf.
        !           935:     @param size If size is 0, then the new mbuf shall have the same size
        !           936:     as the original mbuf that is being replaced. Otherwise, the new
        !           937:     mbuf shall have the size specified here.
        !           938:     @result If mbuf allocation was successful, then the replacement will
        !           939:     take place and the original mbuf will be returned. Otherwise, a NULL
        !           940:     is returned. */
        !           941: 
        !           942:     virtual struct mbuf * replacePacket(struct mbuf ** mp, UInt size = 0);
        !           943: 
        !           944: /*! @function replaceOrCopyPacket
        !           945:     @discussion Either replace or copy the source mbuf given depending
        !           946:     on the amount of data in the source mbuf. This method will either
        !           947:     perform a copy or replace the source mbuf, whichever is more
        !           948:     time efficient. If replaced, then the original mbuf is returned, and
        !           949:     a new mbuf is allocated to take its place. If copied, the source mbuf is
        !           950:     left intact, while a copy is returned that is just big enough to hold
        !           951:     all the data from the source mbuf.
        !           952:     @param mp A pointer to the source mbuf that may be updated by this
        !           953:     method to point to the new mbuf if replaced.
        !           954:     @param rcvlen The number of data bytes in the source mbuf.
        !           955:     @param replacedP Pointer to a bool that is set to true if the
        !           956:            source mbuf was replaced, or set to false if the
        !           957:            source mbuf was copied.
        !           958:     @result A replacement or a copy of the source mbuf, 0 if mbuf
        !           959:     allocation failed. */
        !           960: 
        !           961:     virtual struct mbuf * replaceOrCopyPacket(struct mbuf ** mp,
        !           962:                                               UInt           rcvlen,
        !           963:                                               bool *         replacedP);
        !           964: 
        !           965: /*! @function freePacket
        !           966:     @discussion Release the mbuf back to the free pool.
        !           967:     @param m The mbuf to be freed. */
        !           968: 
        !           969:     virtual void freePacket(struct mbuf * m);
        !           970: 
        !           971: /*! @function createInterface
        !           972:     @abstract Create an interface client object.
        !           973:     @discussion Create a new IONetworkInterface instance.
        !           974:     This method is called by attachInterface() to perform the
        !           975:     allocation and initialization of a new interface client object.
        !           976:     A family specific subclass of IONetworkController must implement
        !           977:     this method and return a matching interface instance. For example,
        !           978:     IOEthernetController implements this method and returns an
        !           979:     IOEthernetInterface instance.
        !           980:     @result The allocated interface object. */
        !           981: 
        !           982:     virtual IONetworkInterface * createInterface() = 0;
        !           983: 
        !           984: /*! @function configureInterface
        !           985:     @abstract Configure an interface client object.
        !           986:     @discussion Configure an interface object created through
        !           987:     createInterface(). IONetworkController will register
        !           988:     its output handler with the interface object provided.
        !           989:     Subclasses may override this method to customize the interface object.
        !           990:     Once the interface is registered and opened by a client, it will
        !           991:     refuse changes to its properties. And since this method is called
        !           992:     before the interface has become registered, this is a final
        !           993:     opportunity for the controller to configure the interface.
        !           994:     @param interface The interface object to be configured.
        !           995:     @result true if configuration was successful, false otherwise
        !           996:     (this will cause attachInterface() to fail). */
        !           997: 
        !           998:     virtual bool configureInterface(IONetworkInterface * interface);
        !           999: 
        !          1000:     // obsolete
        !          1001:     virtual bool configureNetworkInterface(IONetworkInterface * interface);
        !          1002: 
        !          1003: /*! @function createOutputQueue
        !          1004:     @abstract Create an IOOutputQueue to handle output queueing.
        !          1005:     @discussion Called by start() to create an IOOutputQueue instance
        !          1006:     to handle output queueing. The default implementation will always
        !          1007:     return 0, hence no output queue will be created. A driver may override
        !          1008:     this method and return a subclass of IOOutputQueue. IONetworkController
        !          1009:     will keep a reference to the queue created, and will release the 
        !          1010:     object when IONetworkController is freed. Also see getOutputQueue().
        !          1011:     @result A newly allocated and initialized IOOutputQueue instance. */
        !          1012: 
        !          1013:     virtual IOOutputQueue * createOutputQueue();
        !          1014:     virtual IOOutputQueue * allocateOutputQueue();  // obsolete
        !          1015: 
        !          1016: /*! @function getOutputQueue
        !          1017:     @abstract Get the IOOutputQueue object created by createOutputQueue().
        !          1018:     @result Return the output queue created by createOutputQueue(). */
        !          1019: 
        !          1020:     virtual IOOutputQueue * getOutputQueue() const;
        !          1021: 
        !          1022: /*! @function getWorkLoop
        !          1023:     @abstract Get the IOWorkLoop object created by IONetworkController.
        !          1024:     @discussion An IOWorkLoop object is created by the start() method.
        !          1025:     Drivers can call getWorkLoop() to obtain a reference to the
        !          1026:     IOWorkLoop object, and attach their event sources, such
        !          1027:     as IOTimerEventSource or IOInterruptEventSource.
        !          1028:     See IOWorkLoop.
        !          1029:     @result The IOWorkLoop object created by IONetworkController. */
        !          1030: 
        !          1031:     virtual IOWorkLoop * getWorkLoop() const;
        !          1032: 
        !          1033: /*! @function getCommandGate
        !          1034:     @abstract Get the IOCommandGate object created by IONetworkController.
        !          1035:     @discussion An IOCommandGate is created and attached to an
        !          1036:     IOWorkLoop by the start() method. This IOCommandGate object is used
        !          1037:     to handle client requests issued through the syncRequest() method.
        !          1038:     Subclasses that need an IOCommandGate should try to use the object
        !          1039:     returned by this method, rather than creating a new instance.
        !          1040:     See IOCommandGate.
        !          1041:     @result The IOCommandGate object created by IONetworkController. */
        !          1042: 
        !          1043:     virtual IOCommandGate * getCommandGate() const;
        !          1044: 
        !          1045: /*! @function broadcastEvent
        !          1046:     @abstract Send an event to all interface client objects.
        !          1047:     @discussion Broadcast an event to all attached interface objects.
        !          1048:     This is equivalent to calling the IONetworkInterface::inputEvent()
        !          1049:     method for all interfaces.
        !          1050:     
        !          1051:     IONetworkController uses this method to broadcast link and media
        !          1052:     events. Drivers will usually call the inputEvent() method directly
        !          1053:     since it is more efficient, and most drivers will only attach a
        !          1054:     single interface client.
        !          1055:     
        !          1056:     @param type Event type.
        !          1057:     @param arg Event argument.
        !          1058:     @result true if the event was delivered, false if an error occurred
        !          1059:     (unable to perform object allocation) and the event was not delivered. */
        !          1060: 
        !          1061:     virtual bool broadcastEvent(UInt32 type, void * arg = 0);
        !          1062: 
        !          1063: /*! @function getPacketFilters
        !          1064:     @abstract Get the set of packet filters supported by the controller.
        !          1065:     @discussion A subclass must implement this method and report its
        !          1066:     supported filter set. See IOPacketFilter enum for the list of defined
        !          1067:     packet filters.
        !          1068:     @param filtersP A mask of supported filters should be written to the
        !          1069:     integer with this address.
        !          1070:     @result kIOReturnSuccess on success, or an error to indicate
        !          1071:     failure to discover the hardware supported filters. */
        !          1072: 
        !          1073:     virtual IOReturn getPacketFilters(UInt32 * filtersP) = 0;
        !          1074: 
        !          1075: /*! @function enablePacketFilters
        !          1076:     @abstract Enable a set of packet filters supported by the controller.
        !          1077:     @discussion After calling getPacketFilters() to gather the set of
        !          1078:     supported packet filters, a client may issue a request to enable a
        !          1079:     (sub)set of filters from the supported set.
        !          1080:     @param filters Each bit that is set indicates a particular filter that
        !          1081:            should be enabled. Filter bits that cleared should be disabled.
        !          1082:     @param activeFiltersP Must be updated by this method to contain the filter
        !          1083:            set that was activated. Ideally, it should be the same as the filter 
        !          1084:            set specified by the first argument.
        !          1085:     @result kIOReturnSuccess on success, otherwise an error code is
        !          1086:     returned. If (*activeFiltersP != filters), then an error is expected. */
        !          1087: 
        !          1088:     virtual IOReturn enablePacketFilters(UInt32   filters,
        !          1089:                                          UInt32 * activeFiltersP) = 0;
        !          1090: 
        !          1091: /*! @function attachDebuggerClient
        !          1092:     @abstract Attach a new IOKernelDebugger client object. Attaching
        !          1093:     a debugger client implies that the driver supports the kernel
        !          1094:     debugging interface, and must implement the two polled-mode entry
        !          1095:     points. See sendPacket() and receivePacket().
        !          1096:     @discussion Allocate and attach a new IOKernelDebugger client object.
        !          1097:     @param debuggerP An IOKernelDebugger handle that is updated by this
        !          1098:            method to contain the allocated IOKernelDebugger instance.
        !          1099:     @result true on success, false otherwise. */
        !          1100: 
        !          1101:     virtual bool attachDebuggerClient(IOKernelDebugger ** debuggerP);
        !          1102: 
        !          1103: /*! @function detachDebuggerClient
        !          1104:     @abstract Detach an IOKernelDebugger client object.
        !          1105:     @discussion Detach and terminate the IOKernelDebugger client object
        !          1106:     provided. A synchronous termination is issued, and this method returns
        !          1107:     after the client has been terminated.
        !          1108:     @param debugger The IOKernelDebugger instance to be detached and
        !          1109:            terminated. If the argument provided is NULL or is not an
        !          1110:            IOKernelDebugger, this method will return immediately. */
        !          1111: 
        !          1112:     virtual void detachDebuggerClient(IOKernelDebugger * debugger);
        !          1113: 
        !          1114: /*! @function enable
        !          1115:     @abstract An enable request from an IOKernelDebugger client.
        !          1116:     @discussion This method is called when an open is received from an
        !          1117:     IOKernelDebugger client. Drivers that wish to provide debugging
        !          1118:     services must override this method and setup the hardware to
        !          1119:     support the polled-mode send and receive methods; receivePacket()
        !          1120:     and sendPacket(). Debug capable drivers may also override the
        !          1121:     more generic enable/disable calls that take an IOService argument.
        !          1122:     @param debugger The IOKernelDebugger client that issued the open.
        !          1123:     @result kIOReturnSuccess. The driver method must return kIOReturnSuccess
        !          1124:     to allow the debugger open, anything else will cause the debugger open
        !          1125:     to fail and the attachDebuggerClient() method will return false. */
        !          1126: 
        !          1127:     virtual IOReturn enable(IOKernelDebugger * debugger);
        !          1128:     virtual IOReturn handleDebuggerOpen(IOKernelDebugger * debugger);
        !          1129: 
        !          1130: /*! @function disable
        !          1131:     @abstract A disable request from an IOKernelDebugger client.
        !          1132:     @discussion This method is called when a close is received from an
        !          1133:     IOKernelDebugger client. A driver which implements
        !          1134:     enable(IOKernelDebugger *) should also implement this method to
        !          1135:     disable hardware support for the polled-mode send and receive methods.
        !          1136:     @param debugger The IOKernelDebugger client that issued the close.
        !          1137:     @result kIOReturnSuccess. The driver method should return a status
        !          1138:     from the disable operation. */
        !          1139: 
        !          1140:     virtual IOReturn disable(IOKernelDebugger * debugger);
        !          1141:     virtual IOReturn handleDebuggerClose(IOKernelDebugger * debugger);
        !          1142: 
        !          1143: /*! @function reserveDebuggerLock
        !          1144:     @abstract Take the global debugger lock.
        !          1145:     @discussion This method should not be used. Call the
        !          1146:     lock() method provided by IOKernelDebugger instead. */
        !          1147:     
        !          1148:     void reserveDebuggerLock();
        !          1149: 
        !          1150: /*! @function releaseDebuggerLock
        !          1151:     @abstract Release the global debugger lock.
        !          1152:     @discussion This method should not be used. Call the
        !          1153:     unlock() method provided by IOKernelDebugger instead. */
        !          1154: 
        !          1155:     void releaseDebuggerLock();
        !          1156: 
        !          1157: /*! @function receivePacket
        !          1158:     @abstract Debugger polled-mode receive handler.
        !          1159:     @discussion This method must be implemented by a driver that supports
        !          1160:     kernel debugging. After a debugger client is attached through
        !          1161:     attachDebuggerClient(), this method will be called by the debugger
        !          1162:     object to poll for a incoming packet when the debugger is active.
        !          1163:     This method can be called from an interrupt context, and the
        !          1164:     driver must never block or perform any memory allocation. The
        !          1165:     receivePacket() method in IONetworkController is used as a placeholder
        !          1166:     and should never be called. A driver that attaches a debugger client
        !          1167:     must override this method.
        !          1168:     @param pkt Pointer to a receive buffer where the received packet should
        !          1169:            be stored to. The buffer has room for 1518 bytes.
        !          1170:     @param pkt_len The length of the received packet must be written to the
        !          1171:            integer pointed by pkt_len.
        !          1172:     @param timeout The maximum amount of time in milliseconds to poll for
        !          1173:            a packet to arrive before this method must return. */ 
        !          1174: 
        !          1175:     virtual void receivePacket(void * pkt, UInt * pkt_len, UInt timeout);
        !          1176: 
        !          1177: /*! @function sendPacket
        !          1178:     @abstract Debugger polled-mode transmit handler.
        !          1179:     @discussion This method must be implemented by a driver that supports
        !          1180:     kernel debugging. After a debugger client is attached through
        !          1181:     attachDebuggerClient(), this method will be called by the debugger
        !          1182:     object to send an outbound packet generated by the debugger.
        !          1183:     This method can be called from an interrupt context, and the
        !          1184:     driver must never block or perform any memory allocation. The
        !          1185:     sendPacket() method in IONetworkController is used as a placeholder
        !          1186:     and should never be called. A driver that attaches a debugger client
        !          1187:     must override this method.
        !          1188:     @param pkt Pointer to a transmit buffer containing the packet to be sent.
        !          1189:     @param pkt_len The amount of data in the transmit buffer. */
        !          1190: 
        !          1191:     virtual void sendPacket(void * pkt, UInt pkt_len);
        !          1192: };
        !          1193: 
        !          1194: #define IONetworkAction IONetworkController::RequestAction
        !          1195: 
        !          1196: inline bool
        !          1197: IONetworkController::attachNetworkInterface(IONetworkInterface ** interface,
        !          1198:                                             bool  doRegister = true)
        !          1199: {
        !          1200:     return attachInterface(interface, doRegister);
        !          1201: }
        !          1202: 
        !          1203: #endif /* !_IONETWORKCONTROLLER_H */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.