Difference between revisions of "Techwiki:Kd"

From ReactOS Wiki
Jump to: navigation, search
(-Adding work in progress KD documentation)
 
Line 19: Line 19:
 
The kernel responds to failure by disabling the debugger.
 
The kernel responds to failure by disabling the debugger.
  
TODO:
+
TODO
-Do we rely on the command line settings to be correct?
+
Do we rely on the command line settings to be correct?
-If not, do we verify them and fail if they are invalid, and return appropriate error code?
+
If not, do we verify them and fail if they are invalid, and return appropriate error code?
-If we do assume the settings to be correct, then what to do if the settings are actually wrong?
+
If we do assume the settings to be correct, then what to do if the settings are actually wrong?
  
  
NTSTATUS
+
NTSTATUS
NTAPI
+
NTAPI
KdDebuggerInitialize0(
+
KdDebuggerInitialize0(
    PLOADER_PARAMETER_BLOCK LoaderBlock
+
    PLOADER_PARAMETER_BLOCK LoaderBlock
);
+
);
  
 
Performs early initialization in phase 0. This usually consists of reading command line parameters from the loader block  
 
Performs early initialization in phase 0. This usually consists of reading command line parameters from the loader block  
Line 37: Line 37:
  
  
NTSTATUS
+
NTSTATUS
NTAPI
+
NTAPI
KdDebuggerInitialize1(
+
KdDebuggerInitialize1(
    PLOADER_PARAMETER_BLOCK LoaderBlock
+
    PLOADER_PARAMETER_BLOCK LoaderBlock
);
+
);
  
 
Performs initialization which could not be done during phase 0.
 
Performs initialization which could not be done during phase 0.
Line 50: Line 50:
 
State Saving and Restoring
 
State Saving and Restoring
  
TODO:
+
TODO
-What does "saving" and "restoring" mean, really?
+
What does "saving" and "restoring" mean, really?
-Can this fail?
+
Can this fail?
-If so, then what to return? How does kernel respond?
+
If so, then what to return? How does kernel respond?
-If not fail, then do we actually return NTSTATUS?
+
If not fail, then do we actually return NTSTATUS?
  
  
NTSTATUS
+
NTSTATUS
NTAPI
+
NTAPI
KdSave(
+
KdSave(
    BOOLEAN SleepTransition
+
    BOOLEAN SleepTransition
);
+
);
  
  
Line 71: Line 71:
  
  
NTSTATUS
+
NTSTATUS
NTAPI
+
NTAPI
KdRestore(
+
KdRestore(
    BOOLEAN SleepTransition
+
    BOOLEAN SleepTransition
);
+
);
  
 
Restores the debug port state
 
Restores the debug port state
Line 89: Line 89:
 
As the KD dll is fully responsible for the debug port it must take care of the port's power state by itself.
 
As the KD dll is fully responsible for the debug port it must take care of the port's power state by itself.
  
TODO:
+
TODO
-Can this fail?
+
Can this fail?
-If so, what to return? And how does kernel respond?
+
If so, what to return? And how does kernel respond?
-If not, do we actually return NTSTATUS?
+
If not, do we actually return NTSTATUS?
  
NTSTATUS
+
NTSTATUS
NTAPI
+
NTAPI
KdD0Transition(
+
KdD0Transition(
    VOID
+
    VOID
);
+
);
  
 
Causes the debug port to undergo a D0 (fully on) transition.
 
Causes the debug port to undergo a D0 (fully on) transition.
  
  
NTSTATUS
+
NTSTATUS
NTAPI
+
NTAPI
KdD3Transition(
+
KdD3Transition(
    VOID
+
    VOID
);
+
);
  
 
Causes the debug port to undergo a D3 (fully off) transition.
 
Causes the debug port to undergo a D3 (fully off) transition.
Line 119: Line 119:
 
What each function does vary greatly depending on the type of packet.
 
What each function does vary greatly depending on the type of packet.
  
VOID
+
VOID
NTAPI
+
NTAPI
KdSendPacket(
+
KdSendPacket(
    ULONG PacketType,
+
    ULONG PacketType,
    PSTRING MessageHeader,
+
    PSTRING MessageHeader,
    PSTRING MessageData,
+
    PSTRING MessageData,
    PKD_CONTEXT Context
+
    PKD_CONTEXT Context
);
+
);
  
 
Sends a packet through the debug port.  
 
Sends a packet through the debug port.  
  
KDSTATUS
+
KDSTATUS
NTAPI
+
NTAPI
KdReceivePacket(
+
KdReceivePacket(
    ULONG PacketType,
+
    ULONG PacketType,
    PSTRING MessageHeader,
+
    PSTRING MessageHeader,
    PSTRING MessageData,
+
    PSTRING MessageData,
    PULONG DataLength,
+
    PULONG DataLength,
    PKD_CONTEXT Context
+
    PKD_CONTEXT Context
);
+
);
  
 
Receives a packet from the debug port.  
 
Receives a packet from the debug port.  
  
  
typedef enum _KDSTATUS
+
typedef enum _KDSTATUS
{
+
{
    KdPacketReceived,
+
    KdPacketReceived,
    KdPacketTimedOut,
+
    KdPacketTimedOut,
    KdPacketNeedsResend
+
    KdPacketNeedsResend
} KDSTATUS;
+
} KDSTATUS;
  
typedef struct _STRING
+
typedef struct _STRING
{
+
{
    USHORT Length;
+
    USHORT Length;
    USHORT MaximumLength;
+
    USHORT MaximumLength;
    PCHAR Buffer;
+
    PCHAR Buffer;
} STRING, *PSTRING;
+
} STRING, *PSTRING;
  
 
Buffer can be one of many types of structures, depending on the type of packet.
 
Buffer can be one of many types of structures, depending on the type of packet.
 
These structures in turn contain nested unions and even more flags, making up a large amount of possible structures.
 
These structures in turn contain nested unions and even more flags, making up a large amount of possible structures.
  
typedef struct _KD_CONTEXT
+
typedef struct _KD_CONTEXT
{
+
{
    ULONG KdpDefaultRetries;
+
    ULONG KdpDefaultRetries;
    BOOLEAN KdpControlCPending;
+
    BOOLEAN KdpControlCPending;
} KD_CONTEXT, *PKD_CONTEXT;
+
} KD_CONTEXT, *PKD_CONTEXT;
  
  
  
 
*1* The command line syntax is specified on msdn: http://msdn.micosoft.com/en-us/library/ms791537.aspx
 
*1* The command line syntax is specified on msdn: http://msdn.micosoft.com/en-us/library/ms791537.aspx

Revision as of 12:51, 18 June 2008

The KD Protocol

The KD (Kernel Debugging) protocol is a low-level interface used by the kernel and the kernel debugger for hardware independent communication. It hides the hardware specific implementation of port communication and presents a uniform API for all types of ports.

This API is implemented in a separate dll, and there is one dll for each type of port. The KD dll is given full control of the debug port. No one else is allowed to use it.


Initialization

KD initialization takes place early during boot, meaning the kernel debugger can connect early and troubleshoot boot issues. The KD dll is responsible for reading command line settings*1*, performing hardware-specific initialization, and everything else required to set up the debug port. All of this is specific to the type of port used.

If the port is successfully initialized, STATUS_SUCCESS is returned. If initialization failed, an appropriate error status is returned. The kernel responds to failure by disabling the debugger.

TODO Do we rely on the command line settings to be correct? If not, do we verify them and fail if they are invalid, and return appropriate error code? If we do assume the settings to be correct, then what to do if the settings are actually wrong?


NTSTATUS
NTAPI
KdDebuggerInitialize0(
    PLOADER_PARAMETER_BLOCK LoaderBlock
);

Performs early initialization in phase 0. This usually consists of reading command line parameters from the loader block and initializing the port itself. If no loader block is provided, or if no settings are specified, then default settings are used.


NTSTATUS
NTAPI
KdDebuggerInitialize1(
    PLOADER_PARAMETER_BLOCK LoaderBlock
);

Performs initialization which could not be done during phase 0. Again, if no loader block is provided then default settings are used.


State Saving and Restoring

TODO What does "saving" and "restoring" mean, really? Can this fail? If so, then what to return? How does kernel respond? If not fail, then do we actually return NTSTATUS?


NTSTATUS
NTAPI
KdSave(
    BOOLEAN SleepTransition
);


Saves the debug port state before undergoing a transitition.

SleepTransition If TRUE, this is a sleep transitition. If FALSE, this is a hibernation transitition.


NTSTATUS
NTAPI
KdRestore(
    BOOLEAN SleepTransition
);

Restores the debug port state

SleepTransition If TRUE, this is a sleep transitition. If FALSE, this is a hibernation transitition.


Power State Control

As the KD dll is fully responsible for the debug port it must take care of the port's power state by itself.

TODO Can this fail? If so, what to return? And how does kernel respond? If not, do we actually return NTSTATUS?

NTSTATUS
NTAPI
KdD0Transition(
    VOID
);

Causes the debug port to undergo a D0 (fully on) transition.


NTSTATUS
NTAPI
KdD3Transition(
    VOID
);

Causes the debug port to undergo a D3 (fully off) transition.


Packet Communication

  • The most interesting part! Much to do!*

A KD dll exports 2 functions for communication across the debug port. What each function does vary greatly depending on the type of packet.

VOID
NTAPI
KdSendPacket(
    ULONG PacketType,
    PSTRING MessageHeader,
    PSTRING MessageData,
    PKD_CONTEXT Context
);

Sends a packet through the debug port.

KDSTATUS
NTAPI
KdReceivePacket(
    ULONG PacketType,
    PSTRING MessageHeader,
    PSTRING MessageData,
    PULONG DataLength,
    PKD_CONTEXT Context
);

Receives a packet from the debug port.


typedef enum _KDSTATUS
{
    KdPacketReceived,
    KdPacketTimedOut,
    KdPacketNeedsResend
} KDSTATUS;
typedef struct _STRING
{
    USHORT Length;
    USHORT MaximumLength;
    PCHAR Buffer;
} STRING, *PSTRING;

Buffer can be one of many types of structures, depending on the type of packet. These structures in turn contain nested unions and even more flags, making up a large amount of possible structures.

typedef struct _KD_CONTEXT
{
    ULONG KdpDefaultRetries;
    BOOLEAN KdpControlCPending;
} KD_CONTEXT, *PKD_CONTEXT;