reactos/ntoskrnl/kdbg/kdb.h

285 lines
5.9 KiB
C
Raw Normal View History

#pragma once
#include "internal/kd.h"
/* TYPES *********************************************************************/
/* from kdb.c */
typedef CONTEXT KDB_KTRAP_FRAME, *PKDB_KTRAP_FRAME;
typedef enum _KDB_BREAKPOINT_TYPE
{
KdbBreakPointNone = 0,
KdbBreakPointSoftware,
KdbBreakPointHardware,
KdbBreakPointTemporary
} KDB_BREAKPOINT_TYPE;
typedef enum _KDB_ACCESS_TYPE
{
KdbAccessRead,
KdbAccessWrite,
KdbAccessReadWrite,
KdbAccessExec
} KDB_ACCESS_TYPE;
typedef struct _KDB_BREAKPOINT
{
KDB_BREAKPOINT_TYPE Type; /* Type of breakpoint */
BOOLEAN Enabled; /* Whether the bp is enabled */
ULONG_PTR Address; /* Address of the breakpoint */
BOOLEAN Global; /* Whether the breakpoint is global or local to a process */
PEPROCESS Process; /* Owning process */
PCHAR ConditionExpression;
PVOID Condition;
union {
/* KdbBreakPointSoftware */
UCHAR SavedInstruction;
/* KdbBreakPointHardware */
struct {
UCHAR DebugReg : 2;
UCHAR Size : 3;
KDB_ACCESS_TYPE AccessType;
} Hw;
} Data;
} KDB_BREAKPOINT, *PKDB_BREAKPOINT;
typedef enum _KDB_ENTER_CONDITION
{
KdbDoNotEnter,
KdbEnterAlways,
KdbEnterFromKmode,
KdbEnterFromUmode
} KDB_ENTER_CONDITION;
/* These values MUST be nonzero. They're used as bit masks. */
typedef enum _KDB_OUTPUT_SETTINGS
{
KD_DEBUG_KDSERIAL = 1,
KD_DEBUG_KDNOECHO = 2
} KDB_OUTPUT_SETTINGS;
/* FUNCTIONS *****************************************************************/
/* from i386/i386-dis.c */
LONG
KdbpDisassemble(
2020-01-26 17:59:05 +00:00
IN ULONG_PTR Address,
IN ULONG IntelSyntax);
LONG
KdbpGetInstLength(
2020-01-26 17:59:05 +00:00
IN ULONG_PTR Address);
/* from i386/kdb_help.S */
VOID NTAPI
KdbpStackSwitchAndCall(
IN PVOID NewStack,
IN VOID (*Function)(VOID));
/* from kdb_cli.c */
extern PCHAR KdbInitFileBuffer;
[NTOS:KD][KDBG] Rework the BootPhase >= 2 initialization of the KD/KDBG kernel debugger. (#4892) CORE-17470 + KdpDebugLogInit: Add resources cleanup in failure code paths. Fix, in an NT-compatible manner, how (and when) the KD/KDBG BootPhase >=2 initialization steps are performed. These are necessary for any functionality KDBG needs, that would depend on the NT I/O Manager and the storage and filesystem stacks to be running. This includes, creating the debug log file, and for KDBG, loading its KDBinit initialization file. As a result, file debug logging is fixed. The old ReactOS-specific (NT-incompatible) callback we did in the middle of IoInitSystem() is removed, in favor of a runtime mechanism that should work on Windows as well. The idea for this new mechanism is loosely inspired by the TDL4 rootkit, see http://blog.w4kfu.com/public/tdl4_article/draft_tdl4article.html but contrary to it, a specific hook is used instead, as well as the technique of driver reinitialization: https://web.archive.org/web/20211021050515/https://driverentry.com.br/en/blog/?p=261 Its rationale is as follows: We want to be able to perform I/O-related initialization (starting a logger thread for file log debugging, loading KDBinit file for KDBG, etc.). A good place for this would be as early as possible, once the I/O Manager has started the storage and the boot filesystem drivers. Here is an overview of the initialization steps of the NT Kernel and Executive: ---- KiSystemStartup(KeLoaderBlock) if (Cpu == 0) KdInitSystem(0, KeLoaderBlock); KiSwitchToBootStack() -> KiSystemStartupBootStack() -> KiInitializeKernel() -> ExpInitializeExecutive(Cpu, KeLoaderBlock) (NOTE: Any unexpected debugger break will call KdInitSystem(0, NULL); ) KdInitSystem(0, LoaderBlock) -> KdDebuggerInitialize0(LoaderBlock); ExpInitializeExecutive(Cpu == 0): ExpInitializationPhase = 0; HalInitSystem(0, KeLoaderBlock); <-- Sets HalInitPnpDriver callback. ... PsInitSystem(LoaderBlock) PsCreateSystemThread(Phase1Initialization) Phase1Initialization(Discard): ExpInitializationPhase = 1; HalInitSystem(1, KeLoaderBlock); ... Early initialization of Ob, Ex, Ke. KdInitSystem(1, KeLoaderBlock); ... KdDebuggerInitialize1(LoaderBlock); ... IoInitSystem(LoaderBlock); ... ---- As we can see, KdDebuggerInitialize1() is the last KD initialization routine the kernel calls, and is called *before* the I/O Manager starts. Thus, direct Nt/ZwCreateFile ... calls done there would fail. Also, we want to do the I/O initialization as soon as possible. There does not seem to be any exported way to be notified about the I/O manager initialization steps... that is, unless we somehow become a driver and insert ourselves in the flow! Since we are not a regular driver, we need to invoke IoCreateDriver() to create one. However, remember that we are currently running *before* IoInitSystem(), the I/O subsystem is not initialized yet. Due to this, calling IoCreateDriver(), much like any other IO functions, would lead to a crash, because it calls ObCreateObject(..., IoDriverObjectType, ...), and IoDriverObjectType is non-initialized yet (it's NULL). The chosen solution is to hook a "known" exported callback: namely, the HalInitPnpDriver() callback (it initializes the "HAL Root Bus Driver"). It is set very early on by the HAL via the HalInitSystem(0, ...) call, and is called early on by IoInitSystem() before any driver is loaded, but after the I/O Manager has been minimally set up so that new drivers can be created. When the hook: KdpInitDriver() is called, we create our driver with IoCreateDriver(), specifying its entrypoint KdpDriverEntry(), then restore and call the original HalInitPnpDriver() callback. Another possible unexplored alternative, could be to insert ourselves in the KeLoaderBlock->LoadOrderListHead boot modules list, or in the KeLoaderBlock->BootDriverListHead boot-driver list. (Note that while we may be able to do this, because boot-drivers are resident in memory, much like we are, we cannot insert ourselves in the system-driver list however, since those drivers are expected to come from PE image files.) Once the KdpDriverEntry() driver entrypoint is called, we register KdpDriverReinit() for re-initialization with the I/O Manager, in order to provide more initialization points. KdpDriverReinit() calls the KD providers at BootPhase >= 2, and schedules further reinitializations (at most 3 more) if any of the providers request so.
2023-01-09 18:35:18 +00:00
NTSTATUS
NTAPI
KdbInitialize(
_In_ PKD_DISPATCH_TABLE DispatchTable,
_In_ ULONG BootPhase);
BOOLEAN
NTAPI
KdbRegisterCliCallback(
PVOID Callback,
BOOLEAN Deregister);
[NTOS:KD][KDBG] Rework the BootPhase >= 2 initialization of the KD/KDBG kernel debugger. (#4892) CORE-17470 + KdpDebugLogInit: Add resources cleanup in failure code paths. Fix, in an NT-compatible manner, how (and when) the KD/KDBG BootPhase >=2 initialization steps are performed. These are necessary for any functionality KDBG needs, that would depend on the NT I/O Manager and the storage and filesystem stacks to be running. This includes, creating the debug log file, and for KDBG, loading its KDBinit initialization file. As a result, file debug logging is fixed. The old ReactOS-specific (NT-incompatible) callback we did in the middle of IoInitSystem() is removed, in favor of a runtime mechanism that should work on Windows as well. The idea for this new mechanism is loosely inspired by the TDL4 rootkit, see http://blog.w4kfu.com/public/tdl4_article/draft_tdl4article.html but contrary to it, a specific hook is used instead, as well as the technique of driver reinitialization: https://web.archive.org/web/20211021050515/https://driverentry.com.br/en/blog/?p=261 Its rationale is as follows: We want to be able to perform I/O-related initialization (starting a logger thread for file log debugging, loading KDBinit file for KDBG, etc.). A good place for this would be as early as possible, once the I/O Manager has started the storage and the boot filesystem drivers. Here is an overview of the initialization steps of the NT Kernel and Executive: ---- KiSystemStartup(KeLoaderBlock) if (Cpu == 0) KdInitSystem(0, KeLoaderBlock); KiSwitchToBootStack() -> KiSystemStartupBootStack() -> KiInitializeKernel() -> ExpInitializeExecutive(Cpu, KeLoaderBlock) (NOTE: Any unexpected debugger break will call KdInitSystem(0, NULL); ) KdInitSystem(0, LoaderBlock) -> KdDebuggerInitialize0(LoaderBlock); ExpInitializeExecutive(Cpu == 0): ExpInitializationPhase = 0; HalInitSystem(0, KeLoaderBlock); <-- Sets HalInitPnpDriver callback. ... PsInitSystem(LoaderBlock) PsCreateSystemThread(Phase1Initialization) Phase1Initialization(Discard): ExpInitializationPhase = 1; HalInitSystem(1, KeLoaderBlock); ... Early initialization of Ob, Ex, Ke. KdInitSystem(1, KeLoaderBlock); ... KdDebuggerInitialize1(LoaderBlock); ... IoInitSystem(LoaderBlock); ... ---- As we can see, KdDebuggerInitialize1() is the last KD initialization routine the kernel calls, and is called *before* the I/O Manager starts. Thus, direct Nt/ZwCreateFile ... calls done there would fail. Also, we want to do the I/O initialization as soon as possible. There does not seem to be any exported way to be notified about the I/O manager initialization steps... that is, unless we somehow become a driver and insert ourselves in the flow! Since we are not a regular driver, we need to invoke IoCreateDriver() to create one. However, remember that we are currently running *before* IoInitSystem(), the I/O subsystem is not initialized yet. Due to this, calling IoCreateDriver(), much like any other IO functions, would lead to a crash, because it calls ObCreateObject(..., IoDriverObjectType, ...), and IoDriverObjectType is non-initialized yet (it's NULL). The chosen solution is to hook a "known" exported callback: namely, the HalInitPnpDriver() callback (it initializes the "HAL Root Bus Driver"). It is set very early on by the HAL via the HalInitSystem(0, ...) call, and is called early on by IoInitSystem() before any driver is loaded, but after the I/O Manager has been minimally set up so that new drivers can be created. When the hook: KdpInitDriver() is called, we create our driver with IoCreateDriver(), specifying its entrypoint KdpDriverEntry(), then restore and call the original HalInitPnpDriver() callback. Another possible unexplored alternative, could be to insert ourselves in the KeLoaderBlock->LoadOrderListHead boot modules list, or in the KeLoaderBlock->BootDriverListHead boot-driver list. (Note that while we may be able to do this, because boot-drivers are resident in memory, much like we are, we cannot insert ourselves in the system-driver list however, since those drivers are expected to come from PE image files.) Once the KdpDriverEntry() driver entrypoint is called, we register KdpDriverReinit() for re-initialization with the I/O Manager, in order to provide more initialization points. KdpDriverReinit() calls the KD providers at BootPhase >= 2, and schedules further reinitializations (at most 3 more) if any of the providers request so.
2023-01-09 18:35:18 +00:00
NTSTATUS
KdbpCliInit(VOID);
VOID
KdbpCliMainLoop(
IN BOOLEAN EnteredOnSingleStep);
VOID
KdbpCliInterpretInitFile(VOID);
SIZE_T
KdbpReadCommand(
_Out_ PCHAR Buffer,
_In_ SIZE_T Size);
VOID
KdbpPager(
_In_ PCHAR Buffer,
_In_ ULONG BufLength);
VOID
KdbpPrint(
_In_ PSTR Format,
_In_ ...);
VOID
KdbpPrintUnicodeString(
_In_ PCUNICODE_STRING String);
BOOLEAN
NTAPI
KdbpGetHexNumber(
IN PCHAR pszNum,
OUT ULONG_PTR *pulValue);
/* from kdb_expr.c */
BOOLEAN
KdbpRpnEvaluateExpression(
IN PCHAR Expression,
IN PKDB_KTRAP_FRAME TrapFrame,
OUT PULONGLONG Result,
OUT PLONG ErrOffset OPTIONAL,
OUT PCHAR ErrMsg OPTIONAL);
PVOID
KdbpRpnParseExpression(
IN PCHAR Expression,
OUT PLONG ErrOffset OPTIONAL,
OUT PCHAR ErrMsg OPTIONAL);
BOOLEAN
KdbpRpnEvaluateParsedExpression(
IN PVOID Expression,
IN PKDB_KTRAP_FRAME TrapFrame,
OUT PULONGLONG Result,
OUT PLONG ErrOffset OPTIONAL,
OUT PCHAR ErrMsg OPTIONAL);
/* from kdb_symbols.c */
BOOLEAN
KdbpSymFindModule(
IN PVOID Address OPTIONAL,
IN INT Index OPTIONAL,
OUT PLDR_DATA_TABLE_ENTRY* pLdrEntry);
BOOLEAN
KdbSymPrintAddress(
IN PVOID Address,
IN PCONTEXT Context);
VOID
KdbSymProcessSymbols(
_Inout_ PLDR_DATA_TABLE_ENTRY LdrEntry,
_In_ BOOLEAN Load);
BOOLEAN
KdbSymInit(
_In_ ULONG BootPhase);
/* from kdb.c */
extern PEPROCESS KdbCurrentProcess;
extern PETHREAD KdbCurrentThread;
extern LONG KdbLastBreakPointNr;
extern ULONG KdbNumSingleSteps;
extern BOOLEAN KdbSingleStepOver;
extern PKDB_KTRAP_FRAME KdbCurrentTrapFrame;
extern ULONG KdbDebugState;
LONG
KdbpGetNextBreakPointNr(
IN ULONG Start OPTIONAL);
BOOLEAN
KdbpGetBreakPointInfo(
IN ULONG BreakPointNr,
OUT ULONG_PTR *Address OPTIONAL,
OUT KDB_BREAKPOINT_TYPE *Type OPTIONAL,
OUT UCHAR *Size OPTIONAL,
OUT KDB_ACCESS_TYPE *AccessType OPTIONAL,
OUT UCHAR *DebugReg OPTIONAL,
OUT BOOLEAN *Enabled OPTIONAL,
OUT BOOLEAN *Global OPTIONAL,
OUT PEPROCESS *Process OPTIONAL,
OUT PCHAR *ConditionExpression OPTIONAL);
NTSTATUS
KdbpInsertBreakPoint(
IN ULONG_PTR Address,
IN KDB_BREAKPOINT_TYPE Type,
IN UCHAR Size OPTIONAL,
IN KDB_ACCESS_TYPE AccessType OPTIONAL,
IN PCHAR ConditionExpression OPTIONAL,
IN BOOLEAN Global,
OUT PLONG BreakPointNr OPTIONAL);
BOOLEAN
KdbpDeleteBreakPoint(
IN LONG BreakPointNr OPTIONAL,
IN OUT PKDB_BREAKPOINT BreakPoint OPTIONAL);
BOOLEAN
KdbpEnableBreakPoint(
IN LONG BreakPointNr OPTIONAL,
IN OUT PKDB_BREAKPOINT BreakPoint OPTIONAL);
BOOLEAN
KdbpDisableBreakPoint(
IN LONG BreakPointNr OPTIONAL,
IN OUT PKDB_BREAKPOINT BreakPoint OPTIONAL);
BOOLEAN
KdbpGetEnterCondition(
IN LONG ExceptionNr,
IN BOOLEAN FirstChance,
OUT KDB_ENTER_CONDITION *Condition);
BOOLEAN
KdbpSetEnterCondition(
IN LONG ExceptionNr,
IN BOOLEAN FirstChance,
IN KDB_ENTER_CONDITION Condition);
BOOLEAN
KdbpAttachToThread(
PVOID ThreadId);
BOOLEAN
KdbpAttachToProcess(
PVOID ProcessId);
VOID
NTAPI
KdbpGetCommandLineSettings(PCHAR p1);
KD_CONTINUE_TYPE
KdbEnterDebuggerException(IN PEXCEPTION_RECORD64 ExceptionRecord,
IN KPROCESSOR_MODE PreviousMode,
IN OUT PCONTEXT Context,
IN BOOLEAN FirstChance);
/* other functions */
NTSTATUS
KdbpSafeReadMemory(OUT PVOID Dest,
IN PVOID Src,
IN ULONG Bytes);
NTSTATUS
KdbpSafeWriteMemory(OUT PVOID Dest,
IN PVOID Src,
IN ULONG Bytes);
#define KdbpGetCharKeyboard(ScanCode) KdbpTryGetCharKeyboard(ScanCode, 0)
CHAR
KdbpTryGetCharKeyboard(PULONG ScanCode, ULONG Retry);
#define KdbpGetCharSerial() KdbpTryGetCharSerial(0)
CHAR
KdbpTryGetCharSerial(ULONG Retry);
VOID
KbdDisableMouse(VOID);
VOID
KbdEnableMouse(VOID);