IOKernelDebugger

Inherits from
IOService
Availability
Available in OS X v10.0 and later.
Declared in
IOKernelDebugger.h

Overview

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.

Tasks

Miscellaneous

Instance Methods

debugger

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

static IOKernelDebugger * debugger( IOService *target, IODebuggerTxHandler txHandler, IODebuggerRxHandler rxHandler, IODebuggerLinkStatusHandler linkStatusHandler, IODebuggerSetModeHandler setModeHandler);
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.

free

Frees the IOKernelDebugger instance.

virtual void free();

handleClose

Handles a client close.

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.

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.

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.

virtual bool init( IOService *target, IODebuggerTxHandler txHandler, IODebuggerRxHandler rxHandler, IODebuggerLinkStatusHandler linkUpHandler, IODebuggerSetModeHandler setModeHandler);
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.

kdpLinkStatusDispatcher

The KDP link status dispatch function.

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.

kdpReceiveDispatcher

The KDP receive dispatch function.

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.

kdpSetModeDispatcher

The KDP set mode dispatch function.

static boolean_t kdpSetModeDispatcher( boolean_t active);
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.

kdpTransmitDispatcher

The KDP transmit dispatch function.

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.

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

nullLinkStatusHandler

Null link status handler.

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.

nullRxHandler

Null receive handler.

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.

nullSetModeHandler

Null set mode handler.

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.

nullTxHandler

Null transmit handler.

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.

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

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

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.

signalDebugger

Signal the kernel to enter the debugger when safe.

static void signalDebugger( void);

unlock

Releases the debugger lock.

static void unlock( IODebuggerLockState state );
Discussion

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

Instance Variables

reserved

ExpansionData * _reserved;

Reserved for future use. (Internal use only)

See Also

_reserved

ExpansionData * _reserved;

Reserved for future use. (Internal use only)

See Also