From 037ac38824623c13070384e8fc0e70c4770dcdbd Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Fri, 5 Dec 2025 11:49:28 -0500 Subject: chore! new project filesystem structure. Signed-off-by: Amlal El Mahrouss --- include/DebuggerKit/Common.inl | 23 +++++ include/DebuggerKit/DebuggerContract.h | 43 +++++++++ include/DebuggerKit/Detail/Config.h | 66 ++++++++++++++ include/DebuggerKit/NeKernelContract.h | 50 +++++++++++ include/DebuggerKit/POSIXMachContract.h | 155 ++++++++++++++++++++++++++++++++ 5 files changed, 337 insertions(+) create mode 100644 include/DebuggerKit/Common.inl create mode 100644 include/DebuggerKit/DebuggerContract.h create mode 100644 include/DebuggerKit/Detail/Config.h create mode 100644 include/DebuggerKit/NeKernelContract.h create mode 100644 include/DebuggerKit/POSIXMachContract.h (limited to 'include/DebuggerKit') diff --git a/include/DebuggerKit/Common.inl b/include/DebuggerKit/Common.inl new file mode 100644 index 0000000..c630041 --- /dev/null +++ b/include/DebuggerKit/Common.inl @@ -0,0 +1,23 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#define kBlank "\e[0;30m" +#define kRed "\e[0;31m" +#define kWhite "\e[0;97m" + +#define kStdOut (std::cout << kRed << "dbg: " << kWhite) + +inline bool kKeepRunning = false; + +#ifdef DK_NEKERNEL_DEBUGGER +inline DebuggerKit::NeKernel::NeKernelContract kKernelDebugger; +#else +inline DebuggerKit::POSIX::POSIXMachContract kUserDebugger; +#endif + +static DebuggerKit::ProcessID kPID = 0L; +static DebuggerKit::CAddress kActiveAddress = nullptr; +static CompilerKit::STLString kPath = ""; diff --git a/include/DebuggerKit/DebuggerContract.h b/include/DebuggerKit/DebuggerContract.h new file mode 100644 index 0000000..e205e26 --- /dev/null +++ b/include/DebuggerKit/DebuggerContract.h @@ -0,0 +1,43 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +#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; + + virtual std::unordered_map& Get() { return m_breakpoints; } + + protected: + ProcessID m_pid{(ProcessID) ~0}; + std::unordered_map m_breakpoints; +}; +} // namespace DebuggerKit diff --git a/include/DebuggerKit/Detail/Config.h b/include/DebuggerKit/Detail/Config.h new file mode 100644 index 0000000..0ea3ba1 --- /dev/null +++ b/include/DebuggerKit/Detail/Config.h @@ -0,0 +1,66 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +/// =========================================================== /// +/// @author Amlal El Mahrouss +/// =========================================================== /// + +#include + +#include +#include +#include +#include + +#include +#include +#include +#include +#include + +#include + +#ifdef __APPLE__ +#include +#include +#include +#endif + +#ifndef kDistRelease + +#define kDistVersion "v0.0.7-debuggerkit" +#define kDistVersionBCD 0x0001 + +#define ToString(X) Stringify(X) +#define Stringify(X) #X + +#define kDistRelease ToString(kDistReleaseBranch) + +#endif // !kDistRelease + +namespace DebuggerKit { +/// =========================================================== /// +/// \brief Process ID +/// =========================================================== /// +typedef uint64_t ProcessID; + +/// =========================================================== /// +/// \brief Address type, a la BSD. +/// =========================================================== /// +typedef char* CAddress; + +namespace Detail { + constexpr auto kDebugCmdLen = 256U; + constexpr auto kDebugPort = 51820; + constexpr auto kDebugMagic = "NE1.0.0;"; + constexpr uint16_t kDebugVersion = 0x0100; + constexpr auto kDebugDelim = ';'; + constexpr auto kDebugEnd = '\r'; + using dk_socket_type = int64_t; +} // namespace Detail +} // namespace DebuggerKit \ No newline at end of file diff --git a/include/DebuggerKit/NeKernelContract.h b/include/DebuggerKit/NeKernelContract.h new file mode 100644 index 0000000..fe38a22 --- /dev/null +++ b/include/DebuggerKit/NeKernelContract.h @@ -0,0 +1,50 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#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/POSIXMachContract.h b/include/DebuggerKit/POSIXMachContract.h new file mode 100644 index 0000000..abf23b5 --- /dev/null +++ b/include/DebuggerKit/POSIXMachContract.h @@ -0,0 +1,155 @@ +/* ======================================== + + Copyright (C) 2025 Amlal El Mahrouss, Licensed under the Apache 2.0 license. + +======================================== */ + +#pragma once + +#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; + m_pid = pid; + + pid = this->m_pid; + + 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(), m_pid, &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(), m_pid, &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(), m_pid, &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(), m_pid, &task); + + kern_return_t kr = mach_port_deallocate(mach_task_self(), task); + + return kr = KERN_SUCCESS; + } +#endif + + private: + ProcessID m_pid{0}; + CompilerKit::STLString m_path; +}; +} // namespace DebuggerKit::POSIX + +#endif -- cgit v1.2.3