[reactos] 04/06: [NTOS:KD64] Some code formatting + add SAL2 annotations to the functions that are going to be involved in the next commit.

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

https://git.reactos.org/?p=reactos.git;a=commitdiff;h=54c03f6965ec8fdca52ac…

commit 54c03f6965ec8fdca52aca75c3baed6e959fb07b
Author:     Hermès Bélusca-Maïto <hermes.belusca-maito(a)reactos.org>
AuthorDate: Sun Nov 17 22:28:42 2019 +0100
Commit:     Hermès Bélusca-Maïto <hermes.belusca-maito(a)reactos.org>
CommitDate: Sun Nov 17 23:21:53 2019 +0100

    [NTOS:KD64] Some code formatting + add SAL2 annotations to the functions that are
going to be involved in the next commit.
    
    + s/ReturnStatus/Status/ , and get rid of Win32 LPSTR and replace by
      PCHAR (since the concerned code deals with counted strings).
---
 ntoskrnl/include/internal/kd64.h |  58 +++++++++++-----------
 ntoskrnl/kd64/kdapi.c            |  49 +++++++++----------
 ntoskrnl/kd64/kdprint.c          | 101 ++++++++++++++++++---------------------
 ntoskrnl/kd64/kdtrap.c           |  21 ++++----
 sdk/include/ndk/kdfuncs.h        |  14 +++---
 5 files changed, 115 insertions(+), 128 deletions(-)

diff --git a/ntoskrnl/include/internal/kd64.h b/ntoskrnl/include/internal/kd64.h
index f1fa443c8da..bff0a3a872d 100644
--- a/ntoskrnl/include/internal/kd64.h
+++ b/ntoskrnl/include/internal/kd64.h
@@ -12,9 +12,9 @@
 // Default size of the DbgPrint log buffer
 //
 #if DBG
-#define KD_DEFAULT_LOG_BUFFER_SIZE                      0x8000
+#define KD_DEFAULT_LOG_BUFFER_SIZE  0x8000
 #else
-#define KD_DEFAULT_LOG_BUFFER_SIZE                      0x1000
+#define KD_DEFAULT_LOG_BUFFER_SIZE  0x1000
 #endif
 
 //
@@ -211,26 +211,26 @@ KdDisableDebuggerWithLock(
 NTSTATUS
 NTAPI
 KdpPrint(
-    IN ULONG ComponentId,
-    IN ULONG Level,
-    IN LPSTR String,
-    IN USHORT Length,
-    IN KPROCESSOR_MODE PreviousMode,
-    IN PKTRAP_FRAME TrapFrame,
-    IN PKEXCEPTION_FRAME ExceptionFrame,
-    OUT PBOOLEAN Handled
+    _In_ ULONG ComponentId,
+    _In_ ULONG Level,
+    _In_reads_bytes_(Length) PCHAR String,
+    _In_ USHORT Length,
+    _In_ KPROCESSOR_MODE PreviousMode,
+    _In_ PKTRAP_FRAME TrapFrame,
+    _In_ PKEXCEPTION_FRAME ExceptionFrame,
+    _Out_ PBOOLEAN Handled
 );
 
 USHORT
 NTAPI
 KdpPrompt(
-    IN LPSTR PromptString,
-    IN USHORT PromptLength,
-    OUT LPSTR ResponseString,
-    IN USHORT MaximumResponseLength,
-    IN KPROCESSOR_MODE PreviousMode,
-    IN PKTRAP_FRAME TrapFrame,
-    IN PKEXCEPTION_FRAME ExceptionFrame
+    _In_reads_bytes_(PromptLength) PCHAR PromptString,
+    _In_ USHORT PromptLength,
+    _Out_writes_bytes_(MaximumResponseLength) PCHAR ResponseString,
+    _In_ USHORT MaximumResponseLength,
+    _In_ KPROCESSOR_MODE PreviousMode,
+    _In_ PKTRAP_FRAME TrapFrame,
+    _In_ PKEXCEPTION_FRAME ExceptionFrame
 );
 
 VOID
@@ -345,12 +345,12 @@ KdpAllowDisable(
 NTSTATUS
 NTAPI
 KdpCopyMemoryChunks(
-    IN ULONG64 Address,
-    IN PVOID Buffer,
-    IN ULONG TotalSize,
-    IN ULONG ChunkSize,
-    IN ULONG Flags,
-    OUT PULONG ActualSize OPTIONAL
+    _In_ ULONG64 Address,
+    _In_ PVOID Buffer,
+    _In_ ULONG TotalSize,
+    _In_ ULONG ChunkSize,
+    _In_ ULONG Flags,
+    _Out_opt_ PULONG ActualSize
 );
 
 //
@@ -359,16 +359,16 @@ KdpCopyMemoryChunks(
 VOID
 NTAPI
 KdpMoveMemory(
-    IN PVOID Destination,
-    IN PVOID Source,
-    IN SIZE_T Length
+    _In_ PVOID Destination,
+    _In_ PVOID Source,
+    _In_ SIZE_T Length
 );
 
 VOID
 NTAPI
 KdpZeroMemory(
-    IN PVOID Destination,
-    IN SIZE_T Length
+    _In_ PVOID Destination,
+    _In_ SIZE_T Length
 );
 
 //
@@ -510,7 +510,7 @@ KdpSysCheckLowMemory(
 VOID
 __cdecl
 KdpDprintf(
-    IN PCHAR Format,
+    _In_ PCHAR Format,
     ...
 );
 
diff --git a/ntoskrnl/kd64/kdapi.c b/ntoskrnl/kd64/kdapi.c
index 1f0066d8ffe..5c48a1e767e 100644
--- a/ntoskrnl/kd64/kdapi.c
+++ b/ntoskrnl/kd64/kdapi.c
@@ -17,9 +17,10 @@
 
 VOID
 NTAPI
-KdpMoveMemory(IN PVOID Destination,
-              IN PVOID Source,
-              IN SIZE_T Length)
+KdpMoveMemory(
+    _In_ PVOID Destination,
+    _In_ PVOID Source,
+    _In_ SIZE_T Length)
 {
     PCHAR DestinationBytes, SourceBytes;
 
@@ -31,8 +32,9 @@ KdpMoveMemory(IN PVOID Destination,
 
 VOID
 NTAPI
-KdpZeroMemory(IN PVOID Destination,
-              IN SIZE_T Length)
+KdpZeroMemory(
+    _In_ PVOID Destination,
+    _In_ SIZE_T Length)
 {
     PCHAR DestinationBytes;
 
@@ -43,12 +45,13 @@ KdpZeroMemory(IN PVOID Destination,
 
 NTSTATUS
 NTAPI
-KdpCopyMemoryChunks(IN ULONG64 Address,
-                    IN PVOID Buffer,
-                    IN ULONG TotalSize,
-                    IN ULONG ChunkSize,
-                    IN ULONG Flags,
-                    OUT PULONG ActualSize OPTIONAL)
+KdpCopyMemoryChunks(
+    _In_ ULONG64 Address,
+    _In_ PVOID Buffer,
+    _In_ ULONG TotalSize,
+    _In_ ULONG ChunkSize,
+    _In_ ULONG Flags,
+    _Out_opt_ PULONG ActualSize)
 {
     NTSTATUS Status;
     ULONG RemainingLength, CopyChunk;
@@ -94,10 +97,7 @@ KdpCopyMemoryChunks(IN ULONG64 Address,
         }
 
         /* Do the copy */
-        Status = MmDbgCopyMemory(Address,
-                                 Buffer,
-                                 CopyChunk,
-                                 Flags);
+        Status = MmDbgCopyMemory(Address, Buffer, CopyChunk, Flags);
         if (!NT_SUCCESS(Status))
         {
             /* Copy failed, break out */
@@ -2147,15 +2147,16 @@ KdDisableDebugger(VOID)
  */
 NTSTATUS
 NTAPI
-KdSystemDebugControl(IN SYSDBG_COMMAND Command,
-                     IN PVOID InputBuffer,
-                     IN ULONG InputBufferLength,
-                     OUT PVOID OutputBuffer,
-                     IN ULONG OutputBufferLength,
-                     IN OUT PULONG ReturnLength,
-                     IN KPROCESSOR_MODE PreviousMode)
+KdSystemDebugControl(
+    _In_ SYSDBG_COMMAND Command,
+    _In_ PVOID InputBuffer,
+    _In_ ULONG InputBufferLength,
+    _Out_ PVOID OutputBuffer,
+    _In_ ULONG OutputBufferLength,
+    _Inout_ PULONG ReturnLength,
+    _In_ KPROCESSOR_MODE PreviousMode)
 {
-    /* handle sime internal commands */
+    /* Handle some internal commands */
     if (Command == ' soR')
     {
         switch ((ULONG_PTR)InputBuffer)
@@ -2269,7 +2270,7 @@ KdRefreshDebuggerNotPresent(VOID)
     /* Check if the debugger is completely disabled */
     if (KdPitchDebugger)
     {
-        /* Don't try to refresh then -- fail early */
+        /* Don't try to refresh then, fail early */
         return TRUE;
     }
 
diff --git a/ntoskrnl/kd64/kdprint.c b/ntoskrnl/kd64/kdprint.c
index 8f721e80887..0389f32e39b 100644
--- a/ntoskrnl/kd64/kdprint.c
+++ b/ntoskrnl/kd64/kdprint.c
@@ -17,7 +17,8 @@
 
 BOOLEAN
 NTAPI
-KdpPrintString(IN PSTRING Output)
+KdpPrintString(
+    _In_ PSTRING Output)
 {
     STRING Data, Header;
     DBGKD_DEBUG_IO DebugIo;
@@ -57,8 +58,9 @@ KdpPrintString(IN PSTRING Output)
 
 BOOLEAN
 NTAPI
-KdpPromptString(IN PSTRING PromptString,
-                IN PSTRING ResponseString)
+KdpPromptString(
+    _In_ PSTRING PromptString,
+    _In_ PSTRING ResponseString)
 {
     STRING Data, Header;
     DBGKD_DEBUG_IO DebugIo;
@@ -210,19 +212,20 @@ KdpSymbol(IN PSTRING DllPath,
 
 USHORT
 NTAPI
-KdpPrompt(IN LPSTR PromptString,
-          IN USHORT PromptLength,
-          OUT PCHAR ResponseString,
-          IN USHORT MaximumResponseLength,
-          IN KPROCESSOR_MODE PreviousMode,
-          IN PKTRAP_FRAME TrapFrame,
-          IN PKEXCEPTION_FRAME ExceptionFrame)
+KdpPrompt(
+    _In_reads_bytes_(PromptLength) PCHAR PromptString,
+    _In_ USHORT PromptLength,
+    _Out_writes_bytes_(MaximumResponseLength) PCHAR ResponseString,
+    _In_ USHORT MaximumResponseLength,
+    _In_ KPROCESSOR_MODE PreviousMode,
+    _In_ PKTRAP_FRAME TrapFrame,
+    _In_ PKEXCEPTION_FRAME ExceptionFrame)
 {
     STRING PromptBuffer, ResponseBuffer;
     BOOLEAN Enable, Resend;
+    PCHAR SafeResponseString;
     CHAR CapturedPrompt[512];
     CHAR SafeResponseBuffer[512];
-    PCHAR SafeResponseString;
 
     /* Normalize the lengths */
     PromptLength = min(PromptLength,
@@ -236,26 +239,18 @@ KdpPrompt(IN LPSTR PromptString,
         /* Handle user-mode buffers safely */
         _SEH2_TRY
         {
-            /* Probe the prompt */
-            ProbeForRead(PromptString,
-                         PromptLength,
-                         1);
-
-            /* Capture prompt */
-            KdpMoveMemory(CapturedPrompt,
-                          PromptString,
-                          PromptLength);
+            /* Probe and capture the prompt */
+            ProbeForRead(PromptString, PromptLength, 1);
+            KdpMoveMemory(CapturedPrompt, PromptString, PromptLength);
             PromptString = CapturedPrompt;
 
-            /* Probe and make room for response */
-            ProbeForWrite(ResponseString,
-                          MaximumResponseLength,
-                          1);
+            /* Probe and make room for the response */
+            ProbeForWrite(ResponseString, MaximumResponseLength, 1);
             SafeResponseString = SafeResponseBuffer;
         }
         _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
         {
-            /* Bad string pointer, bail out  */
+            /* Bad string pointer, bail out */
             _SEH2_YIELD(return 0);
         }
         _SEH2_END;
@@ -265,7 +260,7 @@ KdpPrompt(IN LPSTR PromptString,
         SafeResponseString = ResponseString;
     }
 
-    /* Setup the prompt and response  buffers */
+    /* Setup the prompt and response buffers */
     PromptBuffer.Buffer = PromptString;
     PromptBuffer.Length = PromptLength;
     ResponseBuffer.Buffer = SafeResponseString;
@@ -290,19 +285,19 @@ KdpPrompt(IN LPSTR PromptString,
     /* Exit the debugger */
     KdExitDebugger(Enable);
 
-    /* Copy back response if required */
+    /* Copy back the response if required */
     if (PreviousMode != KernelMode)
     {
         _SEH2_TRY
         {
-            /* Safely copy back response to user mode  */
+            /* Safely copy back the response to user mode */
             KdpMoveMemory(ResponseString,
                           ResponseBuffer.Buffer,
                           ResponseBuffer.Length);
         }
         _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
         {
-            /* String became invalid after we exited, fail  */
+            /* String became invalid after we exited, fail */
             _SEH2_YIELD(return 0);
         }
         _SEH2_END;
@@ -314,16 +309,17 @@ KdpPrompt(IN LPSTR PromptString,
 
 NTSTATUS
 NTAPI
-KdpPrint(IN ULONG ComponentId,
-         IN ULONG Level,
-         IN LPSTR String,
-         IN USHORT Length,
-         IN KPROCESSOR_MODE PreviousMode,
-         IN PKTRAP_FRAME TrapFrame,
-         IN PKEXCEPTION_FRAME ExceptionFrame,
-         OUT PBOOLEAN Handled)
+KdpPrint(
+    _In_ ULONG ComponentId,
+    _In_ ULONG Level,
+    _In_reads_bytes_(Length) PCHAR String,
+    _In_ USHORT Length,
+    _In_ KPROCESSOR_MODE PreviousMode,
+    _In_ PKTRAP_FRAME TrapFrame,
+    _In_ PKEXCEPTION_FRAME ExceptionFrame,
+    _Out_ PBOOLEAN Handled)
 {
-    NTSTATUS ReturnStatus;
+    NTSTATUS Status;
     BOOLEAN Enable;
     STRING OutputString;
     PVOID CapturedString;
@@ -356,27 +352,21 @@ KdpPrint(IN ULONG ComponentId,
     /* Normalize the length */
     Length = min(Length, 512);
 
-    /* Check if we need to verify the buffer */
+    /* Check if we need to verify the string */
     if (PreviousMode != KernelMode)
     {
         /* Capture user-mode buffers */
         _SEH2_TRY
         {
-            /* Probe the string */
-            ProbeForRead(String,
-                         Length,
-                         1);
-
-            /* Capture it */
+            /* Probe and capture the string */
+            ProbeForRead(String, Length, 1);
             CapturedString = alloca(Length);
-            KdpMoveMemory(CapturedString,
-                          String,
-                          Length);
+            KdpMoveMemory(CapturedString, String, Length);
             String = CapturedString;
         }
         _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
         {
-            /* Bad pointer, fail the print */
+            /* Bad string pointer, bail out */
             _SEH2_YIELD(return STATUS_ACCESS_VIOLATION);
         }
         _SEH2_END;
@@ -404,29 +394,30 @@ KdpPrint(IN ULONG ComponentId,
     if (KdpPrintString(&OutputString))
     {
         /* User pressed CTRL-C, breakpoint on return */
-        ReturnStatus = STATUS_BREAKPOINT;
+        Status = STATUS_BREAKPOINT;
     }
     else
     {
         /* String was printed */
-        ReturnStatus = STATUS_SUCCESS;
+        Status = STATUS_SUCCESS;
     }
 
     /* Exit the debugger and return */
     KdExitDebugger(Enable);
     *Handled = TRUE;
-    return ReturnStatus;
+    return Status;
 }
 
 VOID
 __cdecl
-KdpDprintf(IN PCHAR Format,
-           ...)
+KdpDprintf(
+    _In_ PCHAR Format,
+    ...)
 {
     STRING String;
-    CHAR Buffer[100];
     USHORT Length;
     va_list ap;
+    CHAR Buffer[100];
 
     /* Format the string */
     va_start(ap, Format);
diff --git a/ntoskrnl/kd64/kdtrap.c b/ntoskrnl/kd64/kdtrap.c
index 91a83de4691..0be83956849 100644
--- a/ntoskrnl/kd64/kdtrap.c
+++ b/ntoskrnl/kd64/kdtrap.c
@@ -166,7 +166,7 @@ KdpTrap(IN PKTRAP_FRAME TrapFrame,
                 /* Call the worker routine */
                 ReturnStatus = KdpPrint((ULONG)KdpGetParameterThree(ContextRecord),
                                         (ULONG)KdpGetParameterFour(ContextRecord),
-                                       
(LPSTR)ExceptionRecord->ExceptionInformation[1],
+                                       
(PCHAR)ExceptionRecord->ExceptionInformation[1],
                                        
(USHORT)ExceptionRecord->ExceptionInformation[2],
                                         PreviousMode,
                                         TrapFrame,
@@ -174,17 +174,16 @@ KdpTrap(IN PKTRAP_FRAME TrapFrame,
                                         &Handled);
 
                 /* Update the return value for the caller */
-                KeSetContextReturnRegister(ContextRecord,
-                                           ReturnStatus);
+                KeSetContextReturnRegister(ContextRecord, ReturnStatus);
                 break;
 
             /* DbgPrompt */
             case BREAKPOINT_PROMPT:
 
                 /* Call the worker routine */
-                ReturnLength =
KdpPrompt((LPSTR)ExceptionRecord->ExceptionInformation[1],
+                ReturnLength =
KdpPrompt((PCHAR)ExceptionRecord->ExceptionInformation[1],
                                         
(USHORT)ExceptionRecord->ExceptionInformation[2],
-                                         (LPSTR)KdpGetParameterThree(ContextRecord),
+                                         (PCHAR)KdpGetParameterThree(ContextRecord),
                                          (USHORT)KdpGetParameterFour(ContextRecord),
                                          PreviousMode,
                                          TrapFrame,
@@ -205,10 +204,8 @@ KdpTrap(IN PKTRAP_FRAME TrapFrame,
             case BREAKPOINT_LOAD_SYMBOLS:
 
                 /* Call the worker routine */
-                KdpSymbol((PSTRING)ExceptionRecord->
-                          ExceptionInformation[1],
-                          (PKD_SYMBOLS_INFO)ExceptionRecord->
-                          ExceptionInformation[2],
+                KdpSymbol((PSTRING)ExceptionRecord->ExceptionInformation[1],
+                          (PKD_SYMBOLS_INFO)ExceptionRecord->ExceptionInformation[2],
                           Unload,
                           PreviousMode,
                           ContextRecord,
@@ -221,10 +218,8 @@ KdpTrap(IN PKTRAP_FRAME TrapFrame,
             case BREAKPOINT_COMMAND_STRING:
 
                 /* Call the worker routine */
-                KdpCommandString((PSTRING)ExceptionRecord->
-                                 ExceptionInformation[1],
-                                 (PSTRING)ExceptionRecord->
-                                 ExceptionInformation[2],
+                KdpCommandString((PSTRING)ExceptionRecord->ExceptionInformation[1],
+                                 (PSTRING)ExceptionRecord->ExceptionInformation[2],
                                  PreviousMode,
                                  ContextRecord,
                                  TrapFrame,
diff --git a/sdk/include/ndk/kdfuncs.h b/sdk/include/ndk/kdfuncs.h
index 2d9278f8f80..21681a67674 100644
--- a/sdk/include/ndk/kdfuncs.h
+++ b/sdk/include/ndk/kdfuncs.h
@@ -33,13 +33,13 @@ Author:
 NTSTATUS
 NTAPI
 KdSystemDebugControl(
-    SYSDBG_COMMAND Command,
-    PVOID InputBuffer,
-    ULONG InputBufferLength,
-    PVOID OutputBuffer,
-    ULONG OutputBufferLength,
-    PULONG ReturnLength,
-    KPROCESSOR_MODE PreviousMode
+    _In_ SYSDBG_COMMAND Command,
+    _In_ PVOID InputBuffer,
+    _In_ ULONG InputBufferLength,
+    _Out_ PVOID OutputBuffer,
+    _In_ ULONG OutputBufferLength,
+    _Inout_ PULONG ReturnLength,
+    _In_ KPROCESSOR_MODE PreviousMode
 );
 
 BOOLEAN