From f86b63f68d500e31369c0dfb048ae949177ae094 Mon Sep 17 00:00:00 2001 From: Aiken Harris Date: Tue, 16 Sep 2025 11:42:40 +0200 Subject: [PATCH] Add missing documentation and fix formatting --- xtoskrnl/ke/bootinfo.cc | 7 ++++ xtoskrnl/ke/exports.cc | 14 +++---- xtoskrnl/ke/kprocess.cc | 8 ++-- xtoskrnl/rtl/amd64/exsup.cc | 80 +++++++++++++++++++++++++++++++++---- xtoskrnl/rtl/i686/exsup.cc | 80 +++++++++++++++++++++++++++++++++---- 5 files changed, 162 insertions(+), 27 deletions(-) diff --git a/xtoskrnl/ke/bootinfo.cc b/xtoskrnl/ke/bootinfo.cc index d77d8a4..bd01a5c 100644 --- a/xtoskrnl/ke/bootinfo.cc +++ b/xtoskrnl/ke/bootinfo.cc @@ -97,6 +97,13 @@ KE::BootInformation::GetKernelParameter(IN PCWSTR ParameterName, return STATUS_NOT_FOUND; } +/** + * Retrieves a pointer to the list of memory descriptors. + * + * @return This routine returns a pointer to the list of memory descriptors. + * + * @since XT 1.0 + */ XTAPI PLIST_ENTRY KE::BootInformation::GetMemoryDescriptors(VOID) diff --git a/xtoskrnl/ke/exports.cc b/xtoskrnl/ke/exports.cc index 9040a2d..5502932 100644 --- a/xtoskrnl/ke/exports.cc +++ b/xtoskrnl/ke/exports.cc @@ -192,8 +192,8 @@ XTCLINK XTAPI VOID KeInitializeDpc(IN PKDPC Dpc, - IN PKDEFERRED_ROUTINE DpcRoutine, - IN PVOID DpcContext) + IN PKDEFERRED_ROUTINE DpcRoutine, + IN PVOID DpcContext) { KE::Dpc::InitializeDpc(Dpc, DpcRoutine, DpcContext); @@ -267,8 +267,8 @@ XTCLINK XTAPI VOID KeInitializeSemaphore(IN PKSEMAPHORE Semaphore, - IN LONG Count, - IN LONG Limit) + IN LONG Count, + IN LONG Limit) { KE::Semaphore::InitializeSemaphore(Semaphore, Count, Limit); } @@ -350,9 +350,9 @@ XTCLINK XTAPI LONG KeReleaseSemaphore(IN PKSEMAPHORE Semaphore, - IN KPRIORITY Increment, - IN LONG Adjustment, - IN BOOLEAN Wait) + IN KPRIORITY Increment, + IN LONG Adjustment, + IN BOOLEAN Wait) { return KE::Semaphore::ReleaseSemaphore(Semaphore, Increment, Adjustment, Wait); } diff --git a/xtoskrnl/ke/kprocess.cc b/xtoskrnl/ke/kprocess.cc index d5bdf6c..ad67909 100644 --- a/xtoskrnl/ke/kprocess.cc +++ b/xtoskrnl/ke/kprocess.cc @@ -41,10 +41,10 @@ KE::KProcess::GetInitialProcess(VOID) XTAPI VOID KE::KProcess::InitializeProcess(IN OUT PKPROCESS Process, - IN KPRIORITY Priority, - IN KAFFINITY Affinity, - IN PULONG_PTR DirectoryTable, - IN BOOLEAN Alignment) + IN KPRIORITY Priority, + IN KAFFINITY Affinity, + IN PULONG_PTR DirectoryTable, + IN BOOLEAN Alignment) { /* Initialize process dispatcher header */ Process->Header.Type = ProcessObject; diff --git a/xtoskrnl/rtl/amd64/exsup.cc b/xtoskrnl/rtl/amd64/exsup.cc index ec10900..39aff65 100644 --- a/xtoskrnl/rtl/amd64/exsup.cc +++ b/xtoskrnl/rtl/amd64/exsup.cc @@ -10,6 +10,25 @@ #include +/** + * Handles SEH structured exception frames. + * + * @param ExceptionRecord + * A pointer to the exception record. + * + * @param EstablisherFrame + * The address of the base of the fixed stack allocation. + * + * @param ContextRecord + * A pointer to the context record at the time the exception was raised. + * + * @param DispatcherContext + * A pointer to the dispatcher context for the function. + * + * @return This routine returns an exception disposition value if the exception was not handled by any filter. + * + * @since XT 1.0 + */ XTCLINK XTAPI EXCEPTION_DISPOSITION @@ -24,13 +43,32 @@ __C_specific_handler(IN PEXCEPTION_RECORD ExceptionRecord, return ExceptionContinueExecution; } +/** + * Handles C++ structured exception frames. This implementation displays a panic screen and halts the system. + * + * @param ExceptionRecord + * A pointer to the exception record that is passed to the possible catch statements. + * + * @param EstablisherFrame + * A pointer to the stack frame that is used to handle the exception. + * + * @param ContextRecord + * A pointer to the context record (not used on Intel CPUs). + * + * @param DispatcherContext + * A pointer to the dispatcher provding information about function entry and stack frame (not used on Intel CPUs). + * + * @return This routine returns an exception disposition value if the exception was not handled by any filter. + * + * @since XT 1.0 + */ XTCLINK XTCDECL EXCEPTION_DISPOSITION - __CxxFrameHandler3(IN PEXCEPTION_RECORD ExceptionRecord, - IN PVOID EstablisherFrame, - IN OUT PCONTEXT ContextRecord, - IN OUT PVOID DispatcherContext) +__CxxFrameHandler3(IN PEXCEPTION_RECORD ExceptionRecord, + IN PVOID EstablisherFrame, + IN OUT PCONTEXT ContextRecord, + IN OUT PVOID DispatcherContext) { UNIMPLEMENTED; @@ -42,13 +80,32 @@ EXCEPTION_DISPOSITION return ExceptionContinueSearch; } +/** + * Finds the appropriate exception handler to process the current exception. + * + * @param ExceptionRecord + * A pointer to the exception record providing information about the specific exception. + * + * @param Registration + * A pointer to the record that indicates which scope table should be used to find the exception handler. + * + * @param Context + * Reserved. + * + * @param Dispatcher + * Reserved. + * + * @return This routine returns DISPOSITION_DISMISS or DISPOSITION_CONTINUE_SEARCH. + * + * @since XT 1.0 + */ XTCLINK XTCDECL INT -_except_handler3(PEXCEPTION_RECORD ExceptionRecord, - PVOID Registration, - PCONTEXT Context, - PVOID Dispatcher) +_except_handler3(IN PEXCEPTION_RECORD ExceptionRecord, + IN PVOID Registration, + IN PCONTEXT Context, + IN PVOID Dispatcher) { UNIMPLEMENTED; @@ -56,6 +113,13 @@ _except_handler3(PEXCEPTION_RECORD ExceptionRecord, return 0; } +/** + * Handles pure virtual function call error. This implementation displays a panic screen and halts the system. + * + * @return This function does not return any value. + * + * @since XT 1.0 + */ XTCLINK XTCDECL VOID diff --git a/xtoskrnl/rtl/i686/exsup.cc b/xtoskrnl/rtl/i686/exsup.cc index d7827d8..03019d6 100644 --- a/xtoskrnl/rtl/i686/exsup.cc +++ b/xtoskrnl/rtl/i686/exsup.cc @@ -10,6 +10,25 @@ #include +/** + * Handles SEH structured exception frames. + * + * @param ExceptionRecord + * A pointer to the exception record. + * + * @param EstablisherFrame + * The address of the base of the fixed stack allocation. + * + * @param ContextRecord + * A pointer to the context record at the time the exception was raised. + * + * @param DispatcherContext + * A pointer to the dispatcher context for the function. + * + * @return This routine returns an exception disposition value if the exception was not handled by any filter. + * + * @since XT 1.0 + */ XTCLINK XTCDECL EXCEPTION_DISPOSITION @@ -24,13 +43,32 @@ __C_specific_handler(IN PEXCEPTION_RECORD ExceptionRecord, return ExceptionContinueExecution; } +/** + * Handles C++ structured exception frames. This implementation displays a panic screen and halts the system. + * + * @param ExceptionRecord + * A pointer to the exception record that is passed to the possible catch statements. + * + * @param EstablisherFrame + * A pointer to the stack frame that is used to handle the exception. + * + * @param ContextRecord + * A pointer to the context record (not used on Intel CPUs). + * + * @param DispatcherContext + * A pointer to the dispatcher provding information about function entry and stack frame (not used on Intel CPUs). + * + * @return This routine returns an exception disposition value if the exception was not handled by any filter. + * + * @since XT 1.0 + */ XTCLINK XTCDECL EXCEPTION_DISPOSITION - __CxxFrameHandler3(IN PEXCEPTION_RECORD ExceptionRecord, - IN PVOID EstablisherFrame, - IN OUT PCONTEXT ContextRecord, - IN OUT PVOID DispatcherContext) +__CxxFrameHandler3(IN PEXCEPTION_RECORD ExceptionRecord, + IN PVOID EstablisherFrame, + IN OUT PCONTEXT ContextRecord, + IN OUT PVOID DispatcherContext) { UNIMPLEMENTED; @@ -42,13 +80,32 @@ EXCEPTION_DISPOSITION return ExceptionContinueSearch; } +/** + * Finds the appropriate exception handler to process the current exception. + * + * @param ExceptionRecord + * A pointer to the exception record providing information about the specific exception. + * + * @param Registration + * A pointer to the record that indicates which scope table should be used to find the exception handler. + * + * @param Context + * Reserved. + * + * @param Dispatcher + * Reserved. + * + * @return This routine returns DISPOSITION_DISMISS or DISPOSITION_CONTINUE_SEARCH. + * + * @since XT 1.0 + */ XTCLINK XTCDECL INT -_except_handler3(PEXCEPTION_RECORD ExceptionRecord, - PVOID Registration, - PCONTEXT Context, - PVOID Dispatcher) +_except_handler3(IN PEXCEPTION_RECORD ExceptionRecord, + IN PVOID Registration, + IN PCONTEXT Context, + IN PVOID Dispatcher) { UNIMPLEMENTED; @@ -56,6 +113,13 @@ _except_handler3(PEXCEPTION_RECORD ExceptionRecord, return 0; } +/** + * Handles pure virtual function call error. This implementation displays a panic screen and halts the system. + * + * @return This function does not return any value. + * + * @since XT 1.0 + */ XTCLINK XTCDECL VOID