From 9b7dbb3e5c131d84730b88c4fc493665c74613fd Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Wed, 25 Mar 2026 08:31:45 +0100 Subject: [FEAT] Refactor DebuggerKit design (BREAKING API CHANGES) Signed-off-by: Amlal El Mahrouss --- include/DebuggerKit/Common.inl | 12 ++- include/DebuggerKit/DebuggerContract.h | 48 ---------- include/DebuggerKit/IDebugger.h | 48 ++++++++++ include/DebuggerKit/Mach.h | 153 ++++++++++++++++++++++++++++++++ include/DebuggerKit/MachContract.h | 157 --------------------------------- include/DebuggerKit/NeKernelContract.h | 50 ----------- include/DebuggerKit/NeSystem.h | 50 +++++++++++ include/DebuggerKit/POSIX.h | 115 ++++++++++++++++++++++++ 8 files changed, 376 insertions(+), 257 deletions(-) delete mode 100644 include/DebuggerKit/DebuggerContract.h create mode 100644 include/DebuggerKit/IDebugger.h create mode 100644 include/DebuggerKit/Mach.h delete mode 100644 include/DebuggerKit/MachContract.h delete mode 100644 include/DebuggerKit/NeKernelContract.h create mode 100644 include/DebuggerKit/NeSystem.h create mode 100644 include/DebuggerKit/POSIX.h (limited to 'include/DebuggerKit') diff --git a/include/DebuggerKit/Common.inl b/include/DebuggerKit/Common.inl index b54c410..a9e5d35 100644 --- a/include/DebuggerKit/Common.inl +++ b/include/DebuggerKit/Common.inl @@ -13,9 +13,17 @@ inline bool kKeepRunning = false; #ifdef DK_NEKERNEL_DEBUGGER -inline DebuggerKit::NeKernel::NeKernelContract kKernelDebugger; +inline DebuggerKit::NeKernel::NeSystemDebugger kKernelDebugger; #else -inline DebuggerKit::POSIX::POSIXMachContract kUserDebugger; +#ifdef DK_MACH_DEBUGGER + +inline DebuggerKit::POSIX::MachDebugger kUserDebugger; + +#else + +inline DebuggerKit::POSIX::POSIXDebugger kUserDebugger; + +#endif #endif static DebuggerKit::ProcessID kPID = 0L; diff --git a/include/DebuggerKit/DebuggerContract.h b/include/DebuggerKit/DebuggerContract.h deleted file mode 100644 index adaeb6e..0000000 --- a/include/DebuggerKit/DebuggerContract.h +++ /dev/null @@ -1,48 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// Copyright 2024-2026, Amlal El Mahrouss (amlal@nekernel.org) -// Licensed under the Apache License, Version 2.0 (See accompanying -// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) -// Official repository: https://github.com/ne-foss-org/nectar - -#ifndef NECTAR_DEBUGGERKIT_DEBUGGERCONTRACT_H -#define NECTAR_DEBUGGERKIT_DEBUGGERCONTRACT_H - -#include -#include - -#define DK_DEBUGGER_CONTRACT : public ::DebuggerKit::IDebuggerContract - -namespace DebuggerKit { -class IDebuggerContract; - -/// =========================================================== /// -/// \brief Debugger contract class in C++, as per the design states. -/// \author Amlal El Mahrouss -/// =========================================================== /// -class IDebuggerContract { - public: - explicit IDebuggerContract() = default; - virtual ~IDebuggerContract() = default; - - public: - IDebuggerContract& operator=(const IDebuggerContract&) = default; - IDebuggerContract(const IDebuggerContract&) = default; - - public: - virtual bool Attach(std::string path, std::string argv, ProcessID& pid) noexcept = 0; - virtual bool BreakAt(std::string symbol) noexcept = 0; - virtual bool Break() noexcept = 0; - virtual bool Continue() noexcept = 0; - virtual bool Detach() noexcept = 0; - - using BreakpointMap = std::unordered_map; - - virtual BreakpointMap& Leak() { return mBreakpoints; } - - protected: - ProcessID mPid{(ProcessID) ~0}; - BreakpointMap mBreakpoints; -}; -} // namespace DebuggerKit - -#endif // NECTAR_DEBUGGERKIT_DEBUGGERCONTRACT_H diff --git a/include/DebuggerKit/IDebugger.h b/include/DebuggerKit/IDebugger.h new file mode 100644 index 0000000..81fddc5 --- /dev/null +++ b/include/DebuggerKit/IDebugger.h @@ -0,0 +1,48 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2024-2026, Amlal El Mahrouss (amlal@nekernel.org) +// Licensed under the Apache License, Version 2.0 (See accompanying +// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) +// Official repository: https://github.com/ne-foss-org/nectar + +#ifndef NECTAR_DEBUGGERKIT_DEBUGGERCONTRACT_H +#define NECTAR_DEBUGGERKIT_DEBUGGERCONTRACT_H + +#include +#include + +#define DK_DEBUGGER_CONTRACT : public ::DebuggerKit::IDebugger + +namespace DebuggerKit { +class IDebugger; + +/// =========================================================== /// +/// \brief Debugger contract class in C++, as per the design states. +/// \author Amlal El Mahrouss +/// =========================================================== /// +class IDebugger { + public: + explicit IDebugger() = default; + virtual ~IDebugger() = default; + + public: + IDebugger& operator=(const IDebugger&) = default; + IDebugger(const IDebugger&) = default; + + public: + virtual bool Attach(const CompilerKit::STLString& path, const CompilerKit::STLString& argv, ProcessID& pid) noexcept = 0; + virtual bool BreakAt(const CompilerKit::STLString& symbol) noexcept = 0; + virtual bool Break() noexcept = 0; + virtual bool Continue() noexcept = 0; + virtual bool Detach() noexcept = 0; + + using BreakpointMap = std::unordered_map; + + virtual BreakpointMap& Leak() { return mBreakpoints; } + + protected: + ProcessID mPid{(ProcessID) ~0}; + BreakpointMap mBreakpoints; +}; +} // namespace DebuggerKit + +#endif // NECTAR_DEBUGGERKIT_DEBUGGERCONTRACT_H diff --git a/include/DebuggerKit/Mach.h b/include/DebuggerKit/Mach.h new file mode 100644 index 0000000..05dc37f --- /dev/null +++ b/include/DebuggerKit/Mach.h @@ -0,0 +1,153 @@ +// Copyright 2024-2025, Amlal El Mahrouss (amlal@nekernel.org) +// Licensed under the Apache License, Version 2.0 (See accompanying +// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) +// Official repository: https://github.com/ne-foss-org/nectar + +#ifndef NECTAR_DEBUGGERKIT_MACHCONTRACT_H +#define NECTAR_DEBUGGERKIT_MACHCONTRACT_H + +#ifdef DK_MACH_DEBUGGER + +/// @file MachDebugger.h +/// @brief POSIX Mach debugger. + +#include +#include +#include + +CK_IMPORT_C kern_return_t mach_vm_write(vm_map_t target_task, mach_vm_address_t address, + vm_offset_t data, mach_msg_type_number_t dataCnt); + +CK_IMPORT_C kern_return_t mach_vm_protect(vm_map_t target_task, mach_vm_address_t address, + mach_vm_size_t size, boolean_t set_maximum, + vm_prot_t new_protection); + +#define PTRACE_ATTACH PT_ATTACHEXC +#define PTRACE_DETACH PT_DETACH +#define PTRACE_POKETEXT PT_WRITE_I +#define PTRACE_CONT PT_CONTINUE +#define PTRACE_PEEKTEXT PT_READ_I + +namespace DebuggerKit::POSIX { +/// =========================================================== /// +/// \brief MachDebugger engine class in C++ +/// \author Amlal El Mahrouss +/// =========================================================== /// +class MachDebugger DK_DEBUGGER_CONTRACT { + public: + explicit MachDebugger() = default; + ~MachDebugger() override = default; + + public: + MachDebugger& operator=(const MachDebugger&) = default; + MachDebugger(const MachDebugger&) = default; + + public: + bool Attach(const CompilerKit::STLString& path, const CompilerKit::STLString& argv, + ProcessID& pid) noexcept override { + pid = fork(); + + if (pid == 0) { + if (argv.empty()) { + ptrace(PT_TRACE_ME, 0, nullptr, 0); + kill(getpid(), SIGSTOP); + } + + std::vector argv_arr; + + argv_arr.push_back(const_cast(path.c_str())); + argv_arr.push_back(const_cast(argv.c_str())); + argv_arr.push_back(nullptr); + + execv(path.c_str(), argv_arr.data()); + + _exit(1); + } + + m_path = path; + mPid = pid; + + pid = this->mPid; + + return true; + } + + void SetPath(const CompilerKit::STLString& path) noexcept { + if (path.empty()) { + return; + } + + m_path = path; + } + + bool BreakAt(const CompilerKit::STLString& symbol) noexcept override { + if (!m_path.empty() && std::filesystem::exists(m_path) && + std::filesystem::is_regular_file(m_path)) { + auto handle = dlopen(m_path.c_str(), RTLD_LAZY); + + if (handle == nullptr) { + return false; + } + + auto addr = dlsym(handle, symbol.c_str()); + + if (addr == nullptr) { + return false; + } + + task_read_t task; + task_for_pid(mach_task_self(), mPid, &task); + +#ifdef __x86_64__ + uint32_t brk_inst = 0xD43E0000; + + mach_vm_protect(task, (mach_vm_address_t) addr, sizeof(uint32_t), false, + VM_PROT_READ | VM_PROT_WRITE | VM_PROT_EXECUTE); + + mach_vm_write(task, (mach_vm_address_t) addr, (vm_offset_t) &brk_inst, sizeof(addr)); +#endif + + return true; + } + + return false; + } + + bool Break() noexcept override { + task_read_t task; + task_for_pid(mach_task_self(), mPid, &task); + + kern_return_t ret = task_suspend(task); + + return ret == KERN_SUCCESS; + } + + bool Continue() noexcept override { + task_read_t task; + task_for_pid(mach_task_self(), mPid, &task); + + kern_return_t ret = task_resume(task); + + return ret == KERN_SUCCESS; + } + + bool Detach() noexcept override { + this->Continue(); + + task_read_t task; + task_for_pid(mach_task_self(), mPid, &task); + + kern_return_t kr = mach_port_deallocate(mach_task_self(), task); + + return kr = KERN_SUCCESS; + } + + private: + ProcessID mPid{0}; + CompilerKit::STLString m_path; +}; +} // namespace DebuggerKit::POSIX + +#endif // DK_MACH_DEBUGGER + +#endif // NECTAR_DEBUGGERKIT_MACHCONTRACT_H diff --git a/include/DebuggerKit/MachContract.h b/include/DebuggerKit/MachContract.h deleted file mode 100644 index bd62007..0000000 --- a/include/DebuggerKit/MachContract.h +++ /dev/null @@ -1,157 +0,0 @@ -// Copyright 2024-2025, Amlal El Mahrouss (amlal@nekernel.org) -// Licensed under the Apache License, Version 2.0 (See accompanying -// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) -// Official repository: https://github.com/ne-foss-org/nectar - -#ifndef NECTAR_DEBUGGERKIT_POSIXMACHCONTRACT_H -#define NECTAR_DEBUGGERKIT_POSIXMACHCONTRACT_H - -#ifdef DK_MACH_DEBUGGER - -/// @file POSIXMachContract.h -/// @brief POSIX Mach debugger. - -#include -#include -#include - -#ifdef __APPLE__ -CK_IMPORT_C kern_return_t mach_vm_write(vm_map_t target_task, mach_vm_address_t address, - vm_offset_t data, mach_msg_type_number_t dataCnt); - -CK_IMPORT_C kern_return_t mach_vm_protect(vm_map_t target_task, mach_vm_address_t address, - mach_vm_size_t size, boolean_t set_maximum, - vm_prot_t new_protection); -#endif - -#define PTRACE_ATTACH PT_ATTACHEXC -#define PTRACE_DETACH PT_DETACH -#define PTRACE_POKETEXT PT_WRITE_I -#define PTRACE_CONT PT_CONTINUE -#define PTRACE_PEEKTEXT PT_READ_I - -namespace DebuggerKit::POSIX { -/// =========================================================== /// -/// \brief POSIXMachContract engine class in C++ -/// \author Amlal El Mahrouss -/// =========================================================== /// -class POSIXMachContract final DK_DEBUGGER_CONTRACT { - public: - explicit POSIXMachContract() = default; - ~POSIXMachContract() override = default; - - public: - POSIXMachContract& operator=(const POSIXMachContract&) = default; - POSIXMachContract(const POSIXMachContract&) = default; - - public: - bool Attach(CompilerKit::STLString path, CompilerKit::STLString argv, - ProcessID& pid) noexcept override { - pid = fork(); - - if (pid == 0) { - if (argv.empty()) { - ptrace(PT_TRACE_ME, 0, nullptr, 0); - kill(getpid(), SIGSTOP); - } - - std::vector argv_arr; - - argv_arr.push_back(const_cast(path.c_str())); - argv_arr.push_back(const_cast(argv.c_str())); - argv_arr.push_back(nullptr); - - execv(path.c_str(), argv_arr.data()); - - _exit(1); - } - - m_path = path; - mPid = pid; - - pid = this->mPid; - - return true; - } - - void SetPath(CompilerKit::STLString path) noexcept { - if (path.empty()) { - return; - } - - m_path = path; - } - - bool BreakAt(CompilerKit::STLString symbol) noexcept override { - if (!m_path.empty() && std::filesystem::exists(m_path) && - std::filesystem::is_regular_file(m_path)) { - auto handle = dlopen(m_path.c_str(), RTLD_LAZY); - - if (handle == nullptr) { - return false; - } - - auto addr = dlsym(handle, symbol.c_str()); - - if (addr == nullptr) { - return false; - } - -#ifdef __APPLE__ - task_read_t task; - task_for_pid(mach_task_self(), mPid, &task); - - uint32_t brk_inst = 0xD43E0000; - - mach_vm_protect(task, (mach_vm_address_t) addr, sizeof(uint32_t), false, - VM_PROT_READ | VM_PROT_WRITE | VM_PROT_EXECUTE); - - mach_vm_write(task, (mach_vm_address_t) addr, (vm_offset_t) &brk_inst, sizeof(addr)); -#endif - - return true; - } - - return false; - } - -#ifdef __APPLE__ - bool Break() noexcept override { - task_read_t task; - task_for_pid(mach_task_self(), mPid, &task); - - kern_return_t ret = task_suspend(task); - - return ret == KERN_SUCCESS; - } - - bool Continue() noexcept override { - task_read_t task; - task_for_pid(mach_task_self(), mPid, &task); - - kern_return_t ret = task_resume(task); - - return ret == KERN_SUCCESS; - } - - bool Detach() noexcept override { - this->Continue(); - - task_read_t task; - task_for_pid(mach_task_self(), mPid, &task); - - kern_return_t kr = mach_port_deallocate(mach_task_self(), task); - - return kr = KERN_SUCCESS; - } -#endif - - private: - ProcessID mPid{0}; - CompilerKit::STLString m_path; -}; -} // namespace DebuggerKit::POSIX - -#endif // DK_MACH_DEBUGGER - -#endif // NECTAR_DEBUGGERKIT_POSIXMACHCONTRACT_H diff --git a/include/DebuggerKit/NeKernelContract.h b/include/DebuggerKit/NeKernelContract.h deleted file mode 100644 index 470da46..0000000 --- a/include/DebuggerKit/NeKernelContract.h +++ /dev/null @@ -1,50 +0,0 @@ -// SPDX-License-Identifier: Apache-2.0 -// Copyright 2024-2026, Amlal El Mahrouss (amlal@nekernel.org) -// Licensed under the Apache License, Version 2.0 (See accompanying -// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) -// Official repository: https://github.com/ne-foss-org/nectar - -#ifndef DK_NEKERNEL_CONTRACT_H -#define DK_NEKERNEL_CONTRACT_H - -/// @brief NeKernel Debugging Protocol -/// @author Amlal El Mahrouss - -#ifdef DK_NEKERNEL_DEBUGGER - -#include -#include - -namespace DebuggerKit::NeKernel { -class NeKernelContract; - -/// =========================================================== /// -/// \brief NeKernel Debugger Contract -/// \author Amlal El Mahrouss -/// =========================================================== /// -class NeKernelContract final DK_DEBUGGER_CONTRACT { - public: - NeKernelContract(); - virtual ~NeKernelContract() override; - - public: - NeKernelContract& operator=(const NeKernelContract&) = default; - NeKernelContract(const NeKernelContract&) = default; - - public: - bool Attach(CompilerKit::STLString path, CompilerKit::STLString arg_v, - ProcessID& pid) noexcept override; - bool BreakAt(CompilerKit::STLString symbol) noexcept override; - bool Break() noexcept override; - bool Continue() noexcept override; - bool Detach() noexcept override; - - private: - CompilerKit::STLString m_kernel_path{}; - Detail::dk_socket_type m_socket{0}; -}; -} // namespace DebuggerKit::NeKernel - -#endif // ifdef DK_NEKERNEL_DEBUGGER - -#endif // DK_NEKERNEL_CONTRACT_H diff --git a/include/DebuggerKit/NeSystem.h b/include/DebuggerKit/NeSystem.h new file mode 100644 index 0000000..299815d --- /dev/null +++ b/include/DebuggerKit/NeSystem.h @@ -0,0 +1,50 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2024-2026, Amlal El Mahrouss (amlal@nekernel.org) +// Licensed under the Apache License, Version 2.0 (See accompanying +// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) +// Official repository: https://github.com/ne-foss-org/nectar + +#ifndef DK_NEKERNEL_CONTRACT_H +#define DK_NEKERNEL_CONTRACT_H + +/// @brief NeKernel Debugging Protocol +/// @author Amlal El Mahrouss + +#ifdef DK_NEKERNEL_DEBUGGER + +#include +#include + +namespace DebuggerKit::NeKernel { +class NeSystemDebugger; + +/// =========================================================== /// +/// \brief NeKernel Debugger Contract +/// \author Amlal El Mahrouss +/// =========================================================== /// +class NeSystemDebugger final DK_DEBUGGER_CONTRACT { + public: + NeSystemDebugger(); + virtual ~NeSystemDebugger() override; + + public: + NeSystemDebugger& operator=(const NeSystemDebugger&) = default; + NeSystemDebugger(const NeSystemDebugger&) = default; + + public: + bool Attach(CompilerKit::STLString path, CompilerKit::STLString arg_v, + ProcessID& pid) noexcept override; + bool BreakAt(CompilerKit::STLString symbol) noexcept override; + bool Break() noexcept override; + bool Continue() noexcept override; + bool Detach() noexcept override; + + private: + CompilerKit::STLString m_kernel_path{}; + Detail::dk_socket_type m_socket{0}; +}; +} // namespace DebuggerKit::NeKernel + +#endif // ifdef DK_NEKERNEL_DEBUGGER + +#endif // DK_NEKERNEL_CONTRACT_H diff --git a/include/DebuggerKit/POSIX.h b/include/DebuggerKit/POSIX.h new file mode 100644 index 0000000..47f6abb --- /dev/null +++ b/include/DebuggerKit/POSIX.h @@ -0,0 +1,115 @@ +// Copyright 2024-2025, Amlal El Mahrouss (amlal@nekernel.org) +// Licensed under the Apache License, Version 2.0 (See accompanying +// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0) +// Official repository: https://github.com/ne-foss-org/nectar + +#ifndef NECTAR_DEBUGGERKIT_MACHCONTRACT_H +#define NECTAR_DEBUGGERKIT_MACHCONTRACT_H + +#ifdef DK_MACH_DEBUGGER + +/// @file POSIXDebugger.h +/// @brief POSIX Mach debugger. + +#include +#include +#include +#include + +#define PTRACE_ATTACH PT_ATTACH +#define PTRACE_DETACH PT_DETACH +#define PTRACE_POKETEXT PT_WRITE_I +#define PTRACE_CONT PT_CONTINUE +#define PTRACE_PEEKTEXT PT_READ_I + +namespace DebuggerKit::POSIX { +/// =========================================================== /// +/// \brief POSIXDebugger engine class in C++ +/// \author Amlal El Mahrouss +/// =========================================================== /// +class POSIXDebugger DK_DEBUGGER_CONTRACT { + public: + explicit POSIXDebugger() = default; + ~POSIXDebugger() override = default; + + public: + POSIXDebugger& operator=(const POSIXDebugger&) = default; + POSIXDebugger(const POSIXDebugger&) = default; + + public: + bool Attach(const CompilerKit::STLString& path, const CompilerKit::STLString& argv, + ProcessID& pid) noexcept override { + pid = fork(); + + if (pid == 0) { + if (argv.empty()) { + ptrace(PT_TRACE_ME, 0, nullptr, 0); + kill(getpid(), SIGSTOP); + } + + std::vector argv_arr; + + argv_arr.push_back(const_cast(path.c_str())); + argv_arr.push_back(const_cast(argv.c_str())); + argv_arr.push_back(nullptr); + + execv(path.c_str(), argv_arr.data()); + + _exit(1); + } + + m_path = path; + mPid = pid; + + pid = this->mPid; + + return true; + } + + void SetPath(const CompilerKit::STLString& path) noexcept { + if (path.empty()) { + return; + } + + m_path = path; + } + + bool BreakAt(const CompilerKit::STLString& symbol) noexcept override { + if (!m_path.empty() && std::filesystem::exists(m_path) && + std::filesystem::is_regular_file(m_path)) { + auto handle = dlopen(m_path.c_str(), RTLD_LAZY); + + if (handle == nullptr) { + return false; + } + + auto addr = dlsym(handle, symbol.c_str()); + + if (addr == nullptr) { + return false; + } + + return true; + } + + return false; + } + + bool Break() noexcept override { return false; } + + bool Continue() noexcept override { return false; } + + bool Detach() noexcept override { + this->Continue(); + return false; + } + + private: + ProcessID mPid{0}; + CompilerKit::STLString m_path; +}; +} // namespace DebuggerKit::POSIX + +#endif // DK_MACH_DEBUGGER + +#endif // NECTAR_DEBUGGERKIT_MACHCONTRACT_H -- cgit v1.2.3