Return to IOKernelDebugger.h CVS log

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

Annotation of XNU/iokit/IOKit/network/IOKernelDebugger.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:  * IOKernelDebugger.cpp
        !            26:  *
        !            27:  * HISTORY
        !            28:  *
        !            29:  */
        !            30: 
        !            31: #ifndef _IOKERNELDEBUGGER_H
        !            32: #define _IOKERNELDEBUGGER_H
        !            33: 
        !            34: // #define __USE_DEBUGGER_LOCK  1    // XXX - not yet!!!
        !            35: 
        !            36: #include <IOKit/IOService.h>
        !            37: 
        !            38: 
        !            39: /*! @typedef IODebuggerRxHandler
        !            40:     @discussion Defines the receive handler that must be implemented
        !            41:     by the provider to service KDP requests. This handler is called
        !            42:     by the dispatch function in IOKernelDebugger.
        !            43:     @param provider The provider object.
        !            44:     @param buffer KDP receive buffer. The buffer allocated has room for
        !            45:            1518 bytes. Never overflow the buffer!
        !            46:     @param length The amount of data placed into the receive buffer
        !            47:            by teh receive handler. Set to 0 if no frame was received
        !            48:            during the poll interval.
        !            49:     @param timeout Poll for a maximum period of 'timeout' milliseconds
        !            50:            while waiting for a frame to arrive. */
        !            51: 
        !            52: typedef void (*IODebuggerRxHandler)(IOService * provider,
        !            53:                                     void *      buffer,
        !            54:                                     UInt *      length,
        !            55:                                     UInt        timeout);
        !            56: 
        !            57: /*! @typedef IODebuggerTxHandler
        !            58:     @discussion Defines the transmit handler that must be implemented
        !            59:     by the provider to service KDP requests. This handler is called
        !            60:     by the dispatch function in IOKernelDebugger.
        !            61:     @param provider The provider object.
        !            62:     @param buffer KDP transmit buffer. This buffer contains a KDP frame
        !            63:            to be sent on the wire.
        !            64:     @param length The number of bytes in the transmit buffer. */
        !            65: 
        !            66: typedef void (*IODebuggerTxHandler)(IOService * provider,
        !            67:                                     void *      buffer,
        !            68:                                     UInt        length);
        !            69: 
        !            70: /*! @typedef IODebuggerLockState
        !            71:     @discussion Defines the return from IOKernelDebugger::lock.
        !            72:     @constant kIODebuggerLocked Set if the debugger lock was taken.
        !            73:                  Otherwise, the debugger lock was not taken. */
        !            74: 
        !            75: typedef enum {
        !            76:     kIODebuggerLockTaken = 0x1,
        !            77: } IODebuggerLockState;
        !            78: 
        !            79: /*! class IOKernelDebugger : public IOService
        !            80:     @abstract Kernel debugger nub.
        !            81:     @discussion This object interfaces with the KDP module and
        !            82:     dispatches KDP requests to its provider. The provider, designated the
        !            83:     debugger device, must implement a pair of handler functions that are
        !            84:     called to handle KDP transmit and receive requests. A debugger lock,
        !            85:     allocated by the IOKernelDebugger, can be used by the debugger device
        !            86:     to block calls to its handler functions during critical sections.
        !            87:     Only a single IOKernelDebugger can be registered at any given time.
        !            88: 
        !            89:     The debugger device is usually a subclass of IOEthernetController.
        !            90:     However, any IOService can attach an IOKernelDebugger client,
        !            91:     implement the two polled mode handlers, and transport the KDP
        !            92:     packets through a data channel. Having said this, the KDP assumes
        !            93:     that the debugger device is an Ethernet interface and therefore
        !            94:     it will always send, and expect to receive, an Ethernet frame. */
        !            95: 
        !            96: class IOKernelDebugger : public IOService
        !            97: {
        !            98:     OSDeclareDefaultStructors(IOKernelDebugger)
        !            99: 
        !           100: protected:
        !           101:     IOService *            _provider;      // debugger device.
        !           102:     IODebuggerTxHandler    _txHandler;     // provider's transmit handler.
        !           103:     IODebuggerRxHandler    _rxHandler;     // provider's receive handler.
        !           104: 
        !           105: /*! @function initialize
        !           106:     @discussion IOKernelDebugger class initializer.
        !           107:     The debugger lock is allocated and initialized. */
        !           108: 
        !           109:     static void initialize();
        !           110: 
        !           111: /*! @function kdpReceiveDispatcher
        !           112:     @abstract The KDP receive dispatch function.
        !           113:     @discussion Handles KDP receive requests during a debugging session,
        !           114:     then dispatches the call to the registered receiver handler. This
        !           115:     function is registered with KDP via kdp_register_send_receive().
        !           116:     @param pkt KDP receive buffer. The buffer allocated has room for
        !           117:            1518 bytes. Never overflow the buffer!
        !           118:     @param pkt_len The amount of data placed into the receive buffer.
        !           119:            Set to 0 if a frame was not received during the poll interval.
        !           120:     @param timeout The registered handler must poll for a maximum period of
        !           121:            'timeout' milliseconds while waiting for a frame to arrive. */
        !           122: 
        !           123:     static void kdpReceiveDispatcher(void * pkt, UInt * pkt_len, UInt timeout);
        !           124: 
        !           125: /*! @function kdpTransmitDispatcher
        !           126:     @abstract The KDP transmit dispatch function.
        !           127:     @discussion Handles KDP transmit requests during a debugging session,
        !           128:     then dispatches the call to the registered transmit handler. This
        !           129:     function is registered with KDP via kdp_register_send_receive().
        !           130:     @param pkt KDP transmit buffer. This buffer contains a KDP frame to be
        !           131:            sent on the wire.
        !           132:     @param pkt_len The number of bytes in the transmit buffer. */
        !           133: 
        !           134:     static void kdpTransmitDispatcher(void * pkt, UInt pkt_len);
        !           135: 
        !           136: /*! @function free
        !           137:     @discussion Free the IOKernelDebugger instance. Used for debugging.
        !           138:     Log a message then call super::free(). */
        !           139: 
        !           140:     virtual void free();
        !           141: 
        !           142: /*! @function openProvider
        !           143:     @discussion Open the attached provider, register it as the debugger
        !           144:     device, and register the dispatch and handler functions.
        !           145:     @param provider The provider object. This object is registered as the
        !           146:            debugger device.
        !           147:     @result true on sucess, or false if the controller open failed, or an
        !           148:     IOKernelDebugger instance has already been registered. */
        !           149: 
        !           150:     bool openProvider(IOService * provider);
        !           151: 
        !           152: /*! @function closeProvider
        !           153:     @discussion Close our provider, and undo the registration performed in
        !           154:     openProvider(). Another IOKernelDebugger instance that comes along will
        !           155:     be able to take over the debugging responsibilities.
        !           156:     provider: The provider object. */
        !           157: 
        !           158:     void closeProvider(IOService * provider);
        !           159: 
        !           160: /*! @function nullTxHandler
        !           161:     @abstract Null transmit handler.
        !           162:     @discussion This function is registered as the transmit handler by
        !           163:     closeProvider() after the provider's handler is unregistered. This
        !           164:     function does nothing except to log a warning message. */
        !           165: 
        !           166:     static void nullTxHandler(IOService * provider,
        !           167:                               void *      buffer,
        !           168:                               UInt        length);
        !           169: 
        !           170: /*! @function nullRxHandler
        !           171:     @abstract Null receive handler.
        !           172:     @discussion This function is registered as the receive handler by
        !           173:     closeProvider() after the provider's handler is unregistered. This
        !           174:     function does nothing except to log a warning message. */
        !           175: 
        !           176:     static void nullRxHandler(IOService * provider,
        !           177:                               void *      buffer,
        !           178:                               UInt *      length,
        !           179:                               UInt        timeout);
        !           180: 
        !           181: public:
        !           182: 
        !           183: /*! @function lock
        !           184:     @discussion Take the debugger lock conditionally. The debugger lock
        !           185:     is taken only if the provider given is the current registered
        !           186:     debugger device. The debugger device is registered via the
        !           187:     openProvider() method, and unregistered via closeProvider().
        !           188:     @param provider The caller of the lock function.
        !           189:     @result kIODebuggerLocked if the lock was taken, or kIODebuggerUnlocked
        !           190:     if the lock was not taken. */
        !           191: 
        !           192:     static IODebuggerLockState   lock(IOService * provider);
        !           193: 
        !           194: /*! @function unlock
        !           195:     @discussion Release the debugger lock if the argument is
        !           196:     kIODebuggerLocked.
        !           197:     @param state The return from the IOKernelDebugger::lock(). */
        !           198: 
        !           199:     static void             unlock(IODebuggerLockState state);
        !           200: 
        !           201: /*! @function init
        !           202:     @discussion The IOKernelDebugger initializer.
        !           203:     @param provider  The provider of the IOKernelDebugger object.
        !           204:     @param txHandler The provider's transmit handler. A pointer to a C 
        !           205:            function.
        !           206:     @param rxHandler The provider's receive handler. A pointer to a C function.
        !           207:     @result true if the instance initialized successfully, false otherwise. */
        !           208: 
        !           209:     virtual bool init(IOService *         provider,
        !           210:                       IODebuggerTxHandler txHandler,
        !           211:                       IODebuggerRxHandler rxHandler);
        !           212: 
        !           213: /*! @function debugger
        !           214:     @discussion A factory method that performs allocation and initialization.
        !           215:     @param provider  The provider of the IOKernelDebugger object.
        !           216:     @param txHandler The provider's transmit handler. A pointer to a C 
        !           217:            function.
        !           218:     @param rxHandler The provider's receive handler. A pointer to a C function.
        !           219:     @result An IOKernelDebugger instance on success, 0 otherwise. */
        !           220: 
        !           221:     static IOKernelDebugger * debugger(IOService *         provider,
        !           222:                                        IODebuggerTxHandler txHandler,
        !           223:                                        IODebuggerRxHandler rxHandler);
        !           224: 
        !           225: /*! @function attach
        !           226:     @discussion Attach to our provider, then call openProvider().
        !           227:     @param provider The provider object.
        !           228:     @result true on success, false otherwise. */
        !           229: 
        !           230:     virtual bool attach(IOService * provider);
        !           231: 
        !           232: /*! @function detach
        !           233:     @discussion Call closeProvider(), then detach from our provider.
        !           234:     @param provider The provider object. */
        !           235: 
        !           236:     virtual void detach(IOService * provider);
        !           237: 
        !           238: /*! @function finalize
        !           239:     @discussion Final termination notification. To ensure that closeProvider()
        !           240:     is called before the object is terminated.
        !           241:     @param options termination options, not used. */
        !           242: 
        !           243:     virtual bool finalize(IOOptionBits options = 0);
        !           244: 
        !           245: /*! @function message
        !           246:     @discussion Facility provided by IOService for general purpose
        !           247:     provider-to-client notification. We catch the kIOMessageServiceIsTerminated
        !           248:     message to detect when our provider becomes inactive, and call
        !           249:     closeProvider().
        !           250:     @param type message tupe.
        !           251:     @param provider The provider object.
        !           252:     @param argument message argument. Not used.
        !           253:     @result kIOReturnSuccess for kIOMessageServiceIsTerminated messages,
        !           254:     kIOReturnUnsupported otherwise. */
        !           255: 
        !           256:     virtual IOReturn message(UInt32      type,
        !           257:                              IOService * provider,
        !           258:                              void *      argument = 0);
        !           259: };
        !           260: 
        !           261: // Shortened versions of the lock/unlock static functions.
        !           262: //
        !           263: #define IODebuggerLock    IOKernelDebugger::lock
        !           264: #define IODebuggerUnlock  IOKernelDebugger::unlock
        !           265: 
        !           266: #endif /* !_IOKERNELDEBUGGER_H */

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