chore! new project filesystem structure.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

5 files changed, 337 insertions, 0 deletions

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 <DebuggerKit/Detail/Config.h>
+#include <unordered_map>
+
+#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<uintptr_t, uintptr_t>& Get() { return m_breakpoints; }
+
+ protected:
+  ProcessID                                m_pid{(ProcessID) ~0};
+  std::unordered_map<uintptr_t, uintptr_t> 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 <CompilerKit/Detail/Config.h>
+
+#include <arpa/inet.h>
+#include <sys/socket.h>
+#include <sys/types.h>
+#include <sys/un.h>
+
+#include <sys/ptrace.h>
+#include <sys/types.h>
+#include <sys/user.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#include <dlfcn.h>
+
+#ifdef __APPLE__
+#include <mach-o/dyld.h>
+#include <mach/mach.h>
+#include <mach/mach_error.h>
+#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 <CompilerKit/Detail/Config.h>
+#include <DebuggerKit/DebuggerContract.h>
+
+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 <DebuggerKit/DebuggerContract.h>
+#include <filesystem>
+#include <vector>
+
+#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<char*> argv_arr;
+
+      argv_arr.push_back(const_cast<char*>(path.c_str()));
+      argv_arr.push_back(const_cast<char*>(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