ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOKernelDebugger

Inherits from:	IOService
Declared In:	IOKernelDebugger.h

Overview

Kernel debugger nub.

Discussion

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.

Functions

debugger: Factory method that performs allocation and initialization of an IOKernelDebugger object.
free: Frees the IOKernelDebugger instance.
handleClose: Handles a client close.
handleIsOpen: Queries whether a client has an open on this object.
handleOpen: Handles a client open.
init: Initializes an IOKernelDebugger instance.
kdpReceiveDispatcher: The KDP receive dispatch function.
kdpTransmitDispatcher: The KDP transmit dispatch function.
lock: Takes the debugger lock conditionally.
nullRxHandler: Null receive handler.
nullTxHandler: Null transmit handler.
powerStateDidChangeTo: Handles notification that the network controller did change power state.
powerStateWillChangeTo: Handles notification that the network controller will change power state.
registerHandler: Registers the target and the handler functions.
unlock: Releases the debugger lock.

debugger

Factory method that performs allocation and initialization of an IOKernelDebugger object.

public

static IOKernelDebugger * debugger(
    IOService *target, 
    IODebuggerTxHandler txHandler, 
    IODebuggerRxHandler rxHandler );

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.

Return Value

Returns an IOKernelDebugger instance on success, 0 otherwise.

free

Frees the IOKernelDebugger instance.

protected

virtual void free();

handleClose

Handles a client close.

protected

virtual void handleClose(
    IOService *forClient, 
    IOOptionBits options );

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.

handleIsOpen

Queries whether a client has an open on this object.

protected

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.

handleOpen

Handles a client open.

protected

virtual bool handleOpen(
    IOService *forClient, 
    IOOptionBits options, 
    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.

init

Initializes an IOKernelDebugger instance.

public

virtual bool init(
    IOService *target, 
    IODebuggerTxHandler txHandler, 
    IODebuggerRxHandler rxHandler );

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.

Return Value

Returns true if the instance initialized successfully, false otherwise.

kdpReceiveDispatcher

The KDP receive dispatch function.

protected

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

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.

kdpTransmitDispatcher

The KDP transmit dispatch function.

protected

static void kdpTransmitDispatcher(
    void *buffer,
    UInt32 length);

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.

lock

Takes the debugger lock conditionally.

public

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().

nullRxHandler

Null receive handler.

protected

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.

nullTxHandler

Null transmit handler.

protected

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.

powerStateDidChangeTo

Handles notification that the network controller did change power state.

protected

virtual IOReturn powerStateDidChangeTo(
    IOPMPowerFlags flags, 
    UInt32 stateNumber, 
    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.

powerStateWillChangeTo

Handles notification that the network controller will change power state.

protected

virtual IOReturn powerStateWillChangeTo(
    IOPMPowerFlags flags, 
    UInt32 stateNumber, 
    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.

registerHandler

Registers the target and the handler functions.

protected

static void registerHandler(
    IOService *target, 
    IODebuggerTxHandler txHandler = 0, 
    IODebuggerRxHandler rxHandler = 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 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.

unlock

Releases the debugger lock.

public

static void unlock(
    IODebuggerLockState state );

Discussion

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

Member Data

_reserved

See Also:

reserved

protected

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

reserved

See Also:

_reserved

protected

ExpansionData * _reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19