[reactos] 10/30: [NTOS:EX:KD64] Add Doxygen documentation for Nt/KdSystemDebugControl.

[Hermès Bélusca-Maïto]

https://git.reactos.org/?p=reactos.git;a=commitdiff;h=a0b009f1ed9e7711377e6a...

commit a0b009f1ed9e7711377e6a52a7034c3083a188bf
Author:     Hermès Bélusca-Maïto [e-mail]
AuthorDate: Mon Mar 13 01:10:57 2023 +0100
Commit:     Hermès Bélusca-Maïto [e-mail]
CommitDate: Tue Jan 28 22:00:36 2025 +0100

[NTOS:EX:KD64] Add Doxygen documentation for Nt/KdSystemDebugControl.

Based from external documentation:
    https://www.ivanlef0u.tuxfamily.org/?p=21
    https://www.ivanlef0u.tuxfamily.org/?p=382
    http://pds8.egloos.com/pds/200807/09/51/Subverting_Windows_2003_Service_Pack...
    http://www.nynaeve.net/?p=114
    https://media.defcon.org/DEF%20CON%2030/DEF%20CON%2030%20presentations/Eran%...
    https://vidstromlabs.com/blog/memory-dumping-with-ntsystemdebugcontrol/
    https://www.kernelmode.info/forum/viewtopic0aa3.html?t=5317
---
 ntoskrnl/ex/dbgctrl.c | 80 ++++++++++++++++++++++++++++++++-------------------
 ntoskrnl/kd64/kdapi.c | 43 +++++++++++++++++++++++++--
 2 files changed, 91 insertions(+), 32 deletions(-)

diff --git a/ntoskrnl/ex/dbgctrl.c b/ntoskrnl/ex/dbgctrl.c
index 17dc980f999..3aa65b99a97 100644
--- a/ntoskrnl/ex/dbgctrl.c
+++ b/ntoskrnl/ex/dbgctrl.c
@@ -146,54 +146,75 @@ ExpDebuggerWorker(
     }
 }

-/*++
- * @name NtSystemDebugControl
- * @implemented
+/**
+ * @brief
+ * Perform various queries to the kernel debugger.
  *
- * Perform various queries to debugger.
- * This API is subject to test-case creation to further evaluate its
- * abilities (if needed to at all)
+ * @param[in]   Command
+ * A SYSDBG_COMMAND value describing the kernel debugger command to perform.
  *
- * See: http://www.osronline.com/showthread.cfm?link=93915
- *      http://void.ru/files/Ntexapi.h
- *      http://www.codeguru.com/code/legacy/system/ntexapi.zip
- *      http://www.securityfocus.com/bid/9694
+ * @param[in]   InputBuffer
+ * Pointer to a user-provided input command-specific buffer, whose length
+ * is given by InputBufferLength.
  *
- * @param ControlCode
- *        Description of the parameter. Wrapped to more lines on ~70th
- *        column.
+ * @param[in]   InputBufferLength
+ * The size (in bytes) of the buffer pointed by InputBuffer.
  *
- * @param InputBuffer
- *        FILLME
+ * @param[out]  OutputBuffer
+ * Pointer to a user-provided command-specific output buffer, whose length
+ * is given by OutputBufferLength.
  *
- * @param InputBufferLength
- *        FILLME
+ * @param[in]   OutputBufferLength
+ * The size (in bytes) of the buffer pointed by OutputBuffer.
  *
- * @param OutputBuffer
- *        FILLME
+ * @param[out]  ReturnLength
+ * Optional pointer to a ULONG variable that receives the actual length of
+ * data written written in the output buffer. It is always zero, except for
+ * the live dump commands where an actual non-zero length is returned.
  *
- * @param OutputBufferLength
- *        FILLME
+ * @return
+ * STATUS_SUCCESS in case of success, or a proper error code otherwise.
  *
-  * @param ReturnLength
- *        FILLME
+ * @remarks
  *
- * @return STATUS_SUCCESS in case of success, proper error code otherwise
+ * - The caller must have SeDebugPrivilege, otherwise the function fails
+ *   with STATUS_ACCESS_DENIED.
  *
- * @remarks None
+ * - Only the live dump commands: SysDbgGetTriageDump, and SysDbgGetLiveKernelDump
+ *   (Win8.1+) are available even if the debugger is disabled or absent.
  *
- *--*/
+ * - The following system-critical commands are not accessible anymore
+ *   for user-mode usage with this API on NT 5.2+ (Windows 2003 SP1 and later)
+ *   systems:
+ *
+ *   SysDbgQueryVersion,
+ *   SysDbgReadVirtual and SysDbgWriteVirtual,
+ *   SysDbgReadPhysical and SysDbgWritePhysical,
+ *   SysDbgReadControlSpace and SysDbgWriteControlSpace,
+ *   SysDbgReadIoSpace and SysDbgWriteIoSpace,
+ *   SysDbgReadMsr and SysDbgWriteMsr,
+ *   SysDbgReadBusData and SysDbgWriteBusData,
+ *   SysDbgCheckLowMemory.
+ *
+ *   For these, NtSystemDebugControl() will return STATUS_NOT_IMPLEMENTED.
+ *   They are now available from kernel-mode only with KdSystemDebugControl().
+ *
+ * @note
+ * See: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-2339
+ *
+ * @see KdSystemDebugControl()
+ **/
 NTSTATUS
 NTAPI
 NtSystemDebugControl(
-    _In_ SYSDBG_COMMAND ControlCode,
+    _In_ SYSDBG_COMMAND Command,
     _In_reads_bytes_(InputBufferLength) PVOID InputBuffer,
     _In_ ULONG InputBufferLength,
     _Out_writes_bytes_(OutputBufferLength) PVOID OutputBuffer,
     _In_ ULONG OutputBufferLength,
     _Out_opt_ PULONG ReturnLength)
 {
-    switch (ControlCode)
+    switch (Command)
     {
         case SysDbgQueryModuleInformation:
         case SysDbgQueryTraceInformation:
@@ -226,10 +247,11 @@ NtSystemDebugControl(
         case SysDbgSetPrintBufferSize:
         case SysDbgGetKdUmExceptionEnable:
         case SysDbgSetKdUmExceptionEnable:
+
         case SysDbgGetKdBlockEnable:
         case SysDbgSetKdBlockEnable:
             return KdSystemDebugControl(
-                ControlCode,
+                Command,
                 InputBuffer, InputBufferLength,
                 OutputBuffer, OutputBufferLength,
                 ReturnLength, KeGetPreviousMode());
diff --git a/ntoskrnl/kd64/kdapi.c b/ntoskrnl/kd64/kdapi.c
index cb0c65bd341..36600e4beac 100644
--- a/ntoskrnl/kd64/kdapi.c
+++ b/ntoskrnl/kd64/kdapi.c
@@ -2171,9 +2171,46 @@ KdDisableDebugger(VOID)
     return KdDisableDebuggerWithLock(TRUE);
 }

-/*
- * @unimplemented
- */
+/**
+ * @brief
+ * Perform various queries to the kernel debugger.
+ *
+ * @param[in]   Command
+ * A SYSDBG_COMMAND value describing the kernel debugger command to perform.
+ *
+ * @param[in]   InputBuffer
+ * Pointer to a user-provided input command-specific buffer, whose length
+ * is given by InputBufferLength.
+ *
+ * @param[in]   InputBufferLength
+ * The size (in bytes) of the buffer pointed by InputBuffer.
+ *
+ * @param[out]  OutputBuffer
+ * Pointer to a user-provided command-specific output buffer, whose length
+ * is given by OutputBufferLength.
+ *
+ * @param[in]   OutputBufferLength
+ * The size (in bytes) of the buffer pointed by OutputBuffer.
+ *
+ * @param[out]  ReturnLength
+ * Optional pointer to a ULONG variable that receives the actual length of
+ * data written written in the output buffer. It is always zero, except for
+ * the live dump commands where an actual non-zero length is returned.
+ *
+ * @param[in]   PreviousMode
+ * The processor mode (KernelMode or UserMode) in which the command is being executed.
+ *
+ * @return
+ * STATUS_SUCCESS in case of success, or a proper error code otherwise.
+ *
+ * @remarks
+ * - This is a kernel-mode function, accessible only by kernel-mode drivers.
+ *
+ * @note
+ * See: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2004-2339
+ *
+ * @see NtSystemDebugControl()
+ **/
 NTSTATUS
 NTAPI
 KdSystemDebugControl(