Mac Developer Library

Developer

IOKernelDebugger Class Reference

Options
Deployment Target:

On This Page
Language:

IOKernelDebugger

Kernel debugger nub.

This object interfaces with the KDP (kernel debugger protocol) module and dispatches KDP requests to its target (provider). The target, designated as the debugger device, must implement a pair of handler functions that are called to handle KDP transmit and receive requests during a debugging session. Only a single IOKernelDebugger in the system can be active at a given time. The active IOKernelDebugger is the one that has an IOKDP object attached as a client.

The debugger device is usually a subclass of IOEthernetController. However, any IOService can service an IOKernelDebugger client, implement the two polled mode handlers, and transport the KDP packets through a data channel. However, KDP assumes that the debugger device is an Ethernet interface and therefore it will always send, and expect to receive, an Ethernet frame.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Factory method that performs allocation and initialization of an IOKernelDebugger object.

    Declaration

    C++

    static IOKernelDebugger * debugger( IOService *target, IODebuggerTxHandlertxHandler, IODebuggerRxHandlerrxHandler, IODebuggerLinkStatusHandlerlinkStatusHandler, IODebuggerSetModeHandlersetModeHandler);

    Parameters

    target

    The target object that implements the debugger handlers.

    txHandler

    The target's transmit handler. A pointer to a 'C' function.

    rxHandler

    The target's receive handler. A pointer to a 'C' function.

    linkStatusHandler

    The target's link status handler. A pointer to a 'C' function.

    setModeHandler

    The target's set mode handler. A pointer to a 'C' function.

    Return Value

    Returns an IOKernelDebugger instance on success, 0 otherwise.

  • Frees the IOKernelDebugger instance.

    Declaration

    C++

    virtual void free();

  • Handles a client close.

    Declaration

    C++

    virtual void handleClose( IOService *forClient, IOOptionBitsoptions );

    Parameters

    forClient

    The client (IOKDP) requesting the close.

    options

    Options passed to the close() call. Not used.

    Discussion

    This method is called by IOService::close() to handle a close from a client with the arbitration lock held.

  • Queries whether a client has an open on this object.

    Declaration

    C++

    virtual bool handleIsOpen( const IOService *forClient ) const;

    Return Value

    Returns true if the specified client, or any client if none (0) is specified, presently has an open on this object.

    Discussion

    This method is called by IOService::isOpen() with the arbitration lock held.

  • Handles a client open.

    Declaration

    C++

    virtual bool handleOpen( IOService *forClient, IOOptionBitsoptions, void *arg );

    Parameters

    forClient

    The client (IOKDP) requesting the open.

    options

    Options passed to the open() call. Not used.

    arg

    A family defined argument passed to the open() call. Not used.

    Return Value

    Returns true on success, false otherwise.

    Discussion

    This method is called by IOService::open() to handle an open from a client (IOKDP) with the arbitration lock held.

  • Initializes an IOKernelDebugger instance.

    Declaration

    C++

    virtual bool init( IOService *target, IODebuggerTxHandlertxHandler, IODebuggerRxHandlerrxHandler, IODebuggerLinkStatusHandlerlinkStatusHandler, IODebuggerSetModeHandlersetModeHandler);

    Parameters

    target

    The target object that implements the debugger handlers.

    txHandler

    The target's transmit handler. A pointer to a 'C' function.

    rxHandler

    The target's receive handler. A pointer to a 'C' function.

    linkStatusHandler

    The target's link status handler. A pointer to a 'C' function.

    setModeHandler

    The target's set mode handler. A pointer to a 'C' function.

    Return Value

    Returns true if the instance initialized successfully, false otherwise.

  • The KDP link status dispatch function.

    Declaration

    C++

    static UInt32 kdpLinkStatusDispatcher( void);

    Return Value

    Return link status.

    Discussion

    Field KDP link status requests, then dispatches the call to the registered link up handler.

  • The KDP receive dispatch function.

    Declaration

    C++

    static void kdpReceiveDispatcher( void *buffer, UInt32 *length, UInt32timeout);

    Parameters

    buffer

    KDP receive buffer. The buffer allocated by KDP has room for 1518 bytes. The receive handler must not overflow this buffer.

    length

    The amount of data received and placed into the buffer. Set to 0 if a frame was not received during the poll interval.

    timeout

    The amount of time to poll in milliseconds while waiting for a frame to arrive.

    Discussion

    Field KDP receives requests, then dispatches the call to the registered receiver handler.

  • The KDP set mode dispatch function.

    Declaration

    C++

    static boolean_t kdpSetModeDispatcher( boolean_tactive);

    Parameters

    active

    TRUE if entering KDP. FALSE if leaving KDP.

    Return Value

    Return TRUE if the link is up and data can be sent/received. Otherwise, return FALSE.

    Discussion

    Field KDP set mode requests, then dispatches the call to the registered set mode handler.

  • The KDP transmit dispatch function.

    Declaration

    C++

    static void kdpTransmitDispatcher( void *buffer, UInt32length);

    Parameters

    buffer

    KDP transmit buffer. This buffer contains a KDP frame to be sent on the network.

    length

    The number of bytes in the transmit buffer.

    Discussion

    Field KDP transmit requests, then dispatches the call to the registered transmit handler.

  • Takes the debugger lock conditionally.

    Declaration

    C++

    static IODebuggerLockState lock( IOService *target );

    Parameters

    target

    The target or provider of an IOKernelDebugger object.

    Return Value

    Returns kIODebuggerLockTaken if the lock was taken, or 0 otherwise.

    Discussion

    This method takes the debugger lock if the object given matches the target registered by registerHandler().

  • Null link status handler.

    Declaration

    C++

    static UInt32 nullLinkStatusHandler( IOService *target);

    Return Value

    This function will always report link up.

    Discussion

    This function is registered as the link status handler when an IOKernelDebugger object surrenders its status as the active debugger nub. Until another IOKernelDebugger object gets promoted, this function will handle polled link status requests from KDP.

  • Null receive handler.

    Declaration

    C++

    static void nullRxHandler( IOService *target, void *buffer, UInt32 *length, UInt32 timeout );

    Discussion

    This function is registered as the receive handler when an IOKernelDebugger object surrenders its status as the active debugger nub. Until another IOKernelDebugger object gets promoted, this function will handle polled receive requests from KDP. This function does nothing except to log a warning message.

  • Null set mode handler.

    Declaration

    C++

    static bool nullSetModeHandler( IOService *target, bool active);

    Return Value

    This function will always return true.

    Discussion

    This function is registered as the set mode handler when an IOKernelDebugger object surrenders its status as the active debugger nub. Until another IOKernelDebugger object gets promoted, this function will handle set mode requests from KDP.

  • Null transmit handler.

    Declaration

    C++

    static void nullTxHandler( IOService *target, void *buffer, UInt32 length );

    Discussion

    This function is registered as the transmit handler when an IOKernelDebugger object surrenders its status as the active debugger nub. Until another IOKernelDebugger object gets promoted, this function will handle polled transmit requests from KDP. This function does nothing useful.

  • Handles notification that the network controller did change power state.

    Declaration

    C++

    virtual IOReturn powerStateDidChangeTo( IOPMPowerFlagsflags, unsigned longstateNumber, IOService *policyMaker );

    Parameters

    flags

    Description of the capability of the controller in the new power state.

    stateNumber

    The number of the state in the state array that the controller is switching to.

    policyMaker

    The policy maker that manages the controller's power state.

    Return Value

    Returns the constant 3000000, to indicate a maximum of 3 seconds for the preparation to complete, and an acknowledgement delivered to the policy maker.

    Discussion

    If the controller became usable, then the controller is re-enabled, and the controller's handlers are re-registered.

  • Handles notification that the network controller will change power state.

    Declaration

    C++

    virtual IOReturn powerStateWillChangeTo( IOPMPowerFlagsflags, unsigned longstateNumber, IOService *policyMaker );

    Parameters

    flags

    Describe the capability of the controller in the new power state.

    stateNumber

    The number of the state in the state array that the controller is switching to.

    policyMaker

    The policy maker that manages the controller's power state.

    Return Value

    Returns the constant 3000000, to indicate a maximum of 3 seconds for the preparation to complete, and an acknowledgement delivered to the policy maker.

    Discussion

    If the controller is about to become unusable, then the controller's handlers are unregistered, and the controller is disabled.

  • Registers the target and the handler functions.

    Declaration

    C++

    static void registerHandler( IOService *target, IODebuggerTxHandler txHandler = 0, IODebuggerRxHandler rxHandler = 0, IODebuggerLinkStatusHandler linkUpHandler = 0, IODebuggerSetModeHandler setModeHandler = 0);

    Parameters

    target

    The target object.

    txHandler

    The transmit handler function. The null handler is registered if the argument is zero.

    rxHandler

    The receive handler function. The null handler is

    linkUpHandler

    The linkup handler function. The null handler is registered if the argument is zero.

    Discussion

    This method is called by handleOpen() and handleClose() to register or unregister the target and its handler functions.

  • Signal the kernel to enter the debugger when safe.

    Declaration

    C++

    static void signalDebugger( void);

  • Releases the debugger lock.

    Declaration

    C++

    static void unlock( IODebuggerLockState state );

    Discussion

    This method releases the debugger lock if the kIODebuggerLockTaken flag is set in the argument.

Instance Variables

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;

  • Reserved for future use. (Internal use only)

    Declaration

    C++

    ExpansionData * _reserved;