Merge pull request #75 from nekernel-org/dev

feat: kernel: new CRuntimeOverrides file, and documentation

6 files changed, 85 insertions, 50 deletions

diff --git a/dev/kernel/FirmwareKit/VEPM.h b/dev/kernel/FirmwareKit/VEPM.h
index 49b6335e..129d3b61 100644
--- a/dev/kernel/FirmwareKit/VEPM.h
+++ b/dev/kernel/FirmwareKit/VEPM.h
@@ -10,25 +10,37 @@
 #include <FirmwareKit/EFI.h>
 #include <FirmwareKit/EPM.h>
 
+/// =========================================================== ///
 /// @brief The Virtual Explicit Partition Map scheme extension.
+/// =========================================================== ///
 
 #if defined(__NE_VEPM__)
 #ifdef kEPMMagic
 #undef kEPMMagic
 #endif  // kEPMMagic
 
+/// =========================================================== ///
+/// @brief VEPM Ident String.
+/// =========================================================== ///
 #define kEPMMagic "EPMVM"
 
+/// =========================================================== ///
 /// @brief VEPM GUID.
 /// @note This is the GUID used to identify a VEPM partition.
+/// =========================================================== ///
 inline EPM_GUID kVEPMGuidEPM = {
     0x9a1b3f2e, 0x4c3f, 0x4d52, {0xa7, 0x83, 0x9c, 0x21, 0x7b, 0x5e, 0x4d, 0xac}};
 
+/// =========================================================== ///
 /// @brief VEPM GUID.
 /// @note This is the GUID used to identify a VEPM partition (EFI version)
+/// =========================================================== ///
 inline EFI_GUID kVEPMGuidEFI = {
     0x9a1b3f2e, 0x4c3f, 0x4d52, {0xa7, 0x83, 0x9c, 0x21, 0x7b, 0x5e, 0x4d, 0xac}};
 
+/// =========================================================== ///
+/// @brief VEPM GUID String.
+/// =========================================================== ///
 #define kVEPMGuidStr "9a1b3f2e-4c3f-4d52-a783-9c217b5e4dac"
 #endif  // __NE_VEPM__
 
diff --git a/dev/kernel/NeKit/KString.inl b/dev/kernel/NeKit/KString.inl
index 2ee5afba..50f46837 100644
--- a/dev/kernel/NeKit/KString.inl
+++ b/dev/kernel/NeKit/KString.inl
@@ -10,7 +10,7 @@
 namespace Kernel {
 template <typename CharKind>
 inline void ort_string_append(CharKind* lhs, const CharKind* rhs, Int32 cur) {
-  SizeT sz_rhs = ort_string_len<CharKind>(rhs);
+  SizeT sz_rhs = oe_string_len<CharKind>(rhs);
   SizeT rhs_i  = 0;
 
   for (; rhs_i < sz_rhs; ++rhs_i) {
@@ -46,9 +46,9 @@ inline bool KBasicString<CharKind>::operator==(const KBasicString<CharKind>& rhs
 
 template <typename CharKind>
 inline bool KBasicString<CharKind>::operator==(const CharKind* rhs) const {
-  if (ort_string_len<CharKind>(rhs) != this->Length()) return false;
+  if (oe_string_len<CharKind>(rhs) != this->Length()) return false;
 
-  for (Size index = 0; index < ort_string_len<CharKind>(rhs); ++index) {
+  for (Size index = 0; index < oe_string_len<CharKind>(rhs); ++index) {
     if (rhs[index] != this->fData[index]) return false;
   }
 
@@ -68,9 +68,9 @@ inline bool KBasicString<CharKind>::operator!=(const KBasicString<CharKind>& rhs
 
 template <typename CharKind>
 inline bool KBasicString<CharKind>::operator!=(const CharKind* rhs) const {
-  if (ort_string_len<CharKind>(rhs) != this->Length()) return false;
+  if (oe_string_len<CharKind>(rhs) != this->Length()) return false;
 
-  for (Size index = 0; index < ort_string_len<CharKind>(rhs); ++index) {
+  for (Size index = 0; index < oe_string_len<CharKind>(rhs); ++index) {
     if (rhs[index] == this->fData[index]) return false;
   }
 
@@ -79,10 +79,10 @@ inline bool KBasicString<CharKind>::operator!=(const CharKind* rhs) const {
 
 template <typename CharKind>
 inline KBasicString<CharKind>& KBasicString<CharKind>::operator+=(const KBasicString<CharKind>& rhs) {
-  if (ort_string_len<CharKind>(rhs.fData) > this->Length()) return *this;
+  if (oe_string_len<CharKind>(rhs.fData) > this->Length()) return *this;
 
   ort_string_append(this->fData, const_cast<CharKind*>(rhs.fData), this->fCur);
-  this->fCur += ort_string_len<CharKind>(const_cast<CharKind*>(rhs.fData));
+  this->fCur += oe_string_len<CharKind>(const_cast<CharKind*>(rhs.fData));
 
   return *this;
 }
@@ -90,7 +90,7 @@ inline KBasicString<CharKind>& KBasicString<CharKind>::operator+=(const KBasicSt
 template <typename CharKind>
 inline KBasicString<CharKind>& KBasicString<CharKind>::operator+=(const CharKind* rhs) {
   ort_string_append(this->fData, const_cast<CharKind*>(rhs), this->fCur);
-  this->fCur += ort_string_len<CharKind>(const_cast<CharKind*>(rhs));
+  this->fCur += oe_string_len<CharKind>(const_cast<CharKind*>(rhs));
 
   return *this;
 }
@@ -99,7 +99,7 @@ template <typename CharKind>
 inline ErrorOr<KBasicString<CharKind>> KStringBuilder::Construct(const CharKind* data) {
   if (!data || *data == 0) return ErrorOr<KBasicString<CharKind>>(nullptr);
 
-  KBasicString<CharKind>* view = new KBasicString<CharKind>(ort_string_len<CharKind>(data));
+  KBasicString<CharKind>* view = new KBasicString<CharKind>(oe_string_len<CharKind>(data));
   (*view) += data;
 
   return ErrorOr<KBasicString<CharKind>>(*view);
@@ -109,12 +109,12 @@ inline const CharKind* KStringBuilder::FromBool(const CharKind* fmt, bool i) {
   if (!fmt) return ("?");
 
   const CharKind* boolean_expr = i ? "YES" : "NO";
-  CharKind*       ret          = (CharKind*) RTL_ALLOCA(ort_string_len<CharKind>(boolean_expr) + ort_string_len<CharKind>(fmt));
+  CharKind*       ret          = (CharKind*) RTL_ALLOCA(oe_string_len<CharKind>(boolean_expr) + oe_string_len<CharKind>(fmt));
 
   if (!ret) return ("?");
 
-  const auto fmt_len = ort_string_len<CharKind>(fmt);
-  const auto res_len = ort_string_len<CharKind>(boolean_expr);
+  const auto fmt_len = oe_string_len<CharKind>(fmt);
+  const auto res_len = oe_string_len<CharKind>(boolean_expr);
 
   for (Size idx = 0; idx < fmt_len; ++idx) {
     if (fmt[idx] == '%') {
@@ -135,9 +135,9 @@ inline const CharKind* KStringBuilder::FromBool(const CharKind* fmt, bool i) {
 }
 template <typename CharKind>
 inline bool KStringBuilder::Equals(const CharKind* lhs, const CharKind* rhs) {
-  if (ort_string_len<CharKind>(rhs) != ort_string_len<CharKind>(lhs)) return false;
+  if (oe_string_len<CharKind>(rhs) != oe_string_len<CharKind>(lhs)) return false;
 
-  for (Size index = 0; index < ort_string_len<CharKind>(rhs); ++index) {
+  for (Size index = 0; index < oe_string_len<CharKind>(rhs); ++index) {
     if (rhs[index] != lhs[index]) return false;
   }
 
@@ -147,17 +147,17 @@ template <typename CharKind>
 inline const CharKind* KStringBuilder::Format(const CharKind* fmt, const CharKind* fmt2) {
   if (!fmt || !fmt2) return ("?");
 
-  CharKind* ret = (CharKind*) RTL_ALLOCA(sizeof(char) * (ort_string_len<CharKind>(fmt2) + ort_string_len<CharKind>(fmt)));
+  CharKind* ret = (CharKind*) RTL_ALLOCA(sizeof(char) * (oe_string_len<CharKind>(fmt2) + oe_string_len<CharKind>(fmt)));
 
   if (!ret) return ("?");
 
-  const auto len = ort_string_len<CharKind>(fmt);
+  const auto len = oe_string_len<CharKind>(fmt);
 
   for (Size idx = 0; idx < len; ++idx) {
-    if (fmt[idx] == '%' && idx < ort_string_len<CharKind>(fmt) && fmt[idx] == 's') {
+    if (fmt[idx] == '%' && idx < oe_string_len<CharKind>(fmt) && fmt[idx] == 's') {
       Size result_cnt = idx;
 
-      for (Size y_idx = 0; y_idx < ort_string_len<CharKind>(fmt2); ++y_idx) {
+      for (Size y_idx = 0; y_idx < oe_string_len<CharKind>(fmt2); ++y_idx) {
         ret[result_cnt] = fmt2[y_idx];
         ++result_cnt;
       }
diff --git a/dev/kernel/NeKit/Ref.h b/dev/kernel/NeKit/Ref.h
index 08b1538d..a95cec7b 100644
--- a/dev/kernel/NeKit/Ref.h
+++ b/dev/kernel/NeKit/Ref.h
@@ -14,6 +14,9 @@
 #include <NeKit/KernelPanic.h>
 
 namespace Kernel {
+/// =========================================================== ///
+/// @brief Reference wrapper class.                          ///
+/// =========================================================== ///
 template <typename T>
 class Ref final {
  public:
@@ -66,7 +69,7 @@ class NonNullRef final {
   Ref<T> fRef{};
 };
 
-using RefAny = Ref<Any>;
+using RefAny        = Ref<Any>;
 using NonNullRefAny = NonNullRef<Any>;
 }  // namespace Kernel
 
diff --git a/dev/kernel/NeKit/Utils.h b/dev/kernel/NeKit/Utils.h
index f2cffd8c..b622eda0 100644
--- a/dev/kernel/NeKit/Utils.h
+++ b/dev/kernel/NeKit/Utils.h
@@ -9,7 +9,9 @@
 #include <NeKit/Defines.h>
 
 namespace Kernel {
-/// ASCII API
+/// =========================================================== ///
+/// @brief ASCII API
+/// =========================================================== ///
 
 Int         rt_copy_memory(const voidPtr src, voidPtr dst, Size len);
 Int         rt_move_memory(const voidPtr src, voidPtr dst, Size len);
@@ -20,29 +22,36 @@ const Char* rt_alloc_string(const Char* text);
 Size        rt_string_len(const Char* str);
 Size        rt_string_len(const Char* str, SizeT _len);
 Boolean     rt_to_string(Char* str_out, UInt64 base, Int32 limit);
-Boolean     rt_is_newln(Char chr);
-Boolean     rt_is_space(Char chr);
-Int32       rt_is_alnum(Int32 character);
+Boolean     rt_is_newln(Int chr);
+Boolean     rt_is_space(Int chr);
+Int32       rt_is_alnum(Int character);
 Int         rt_to_uppercase(Int c);
 Int         rt_to_lower(Int c);
 voidPtr     rt_string_in_string(const Char* in, const Char* needle);
 char*       rt_string_has_char(Char* str, Char chr);
 
-// Safe memory functions
+/// =========================================================== ///
+/// @brief Safe memory functions API
+/// =========================================================== ///
+
 Int     rt_copy_memory_safe(const voidPtr src, voidPtr dst, Size len, Size dst_size);
 voidPtr rt_set_memory_safe(voidPtr dst, UInt32 value, Size len, Size dst_size);
 
-/// UNICODE API
+/// =========================================================== ///
+/// @brief UNICODE API
+/// =========================================================== ///
 
 Int  urt_string_cmp(const Utf8Char* src, const Utf8Char* cmp, Size len);
 Void urt_set_memory(const voidPtr src, UInt32 dst, Size len);
 Int  urt_copy_memory(const voidPtr src, voidPtr dst, Size len);
 Size urt_string_len(const Utf8Char* str);
 
-/// OpenTemplate UTILS API
+/// =========================================================== ///
+/// @brief OpenEncoding API
+/// =========================================================== ///
 
 template <typename CharType = Char>
-inline SizeT ort_string_len(const CharType* str) {
+inline SizeT oe_string_len(const CharType* str) {
   if (!str) return 0;
 
   SizeT len{0};
diff --git a/dev/kernel/src/AsciiUtils.cc b/dev/kernel/src/AsciiUtils.cc
index aed11e94..94011d20 100644
--- a/dev/kernel/src/AsciiUtils.cc
+++ b/dev/kernel/src/AsciiUtils.cc
@@ -98,23 +98,23 @@ Int32 rt_copy_memory(const voidPtr src, voidPtr dst, Size len) {
   return static_cast<Int>(len);
 }
 
-Int32 rt_to_uppercase(Int32 ch) {
+Int32 rt_to_uppercase(Int ch) {
   return (ch >= 'a' && ch <= 'z') ? ch - 0x20 : ch;
 }
 
-Int32 rt_to_lower(Int32 ch) {
+Int32 rt_to_lower(Int ch) {
   return (ch >= 'A' && ch <= 'Z') ? ch + 0x20 : ch;
 }
 
-Int32 rt_is_alnum(Int32 ch) {
+Int32 rt_is_alnum(Int ch) {
   return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9');
 }
 
-Boolean rt_is_space(Char ch) {
+Boolean rt_is_space(Int ch) {
   return ch == ' ';
 }
 
-Boolean rt_is_newln(Char ch) {
+Boolean rt_is_newln(Int ch) {
   return ch == '\n';
 }
 
@@ -124,7 +124,8 @@ Char rt_to_char(UInt64 value, Int32 base) {
 }
 
 Bool rt_to_string(Char* str, UInt64 value, Int32 base) {
-#ifdef __NE_AMD64__
+  if (!str || base < 2 || base > 16) return NO;
+
   Int i = 0;
   do {
     str[i++] = rt_to_char(value, base);
@@ -139,8 +140,6 @@ Bool rt_to_string(Char* str, UInt64 value, Int32 base) {
   }
 
   return YES;
-#endif
-  return NO;
 }
 
 VoidPtr rt_string_in_string(const Char* haystack, const Char* needle) {
@@ -163,19 +162,4 @@ Char* rt_string_has_char(Char* str, Char ch) {
   while (*str && *str != ch) ++str;
   return (*str == ch) ? str : nullptr;
 }
-
-EXTERN_C void* memset(void* dst, int c, long long unsigned int len) {
-  return Kernel::rt_set_memory_safe(dst, c, static_cast<Size>(len), static_cast<Size>(len));
-}
-
-EXTERN_C void* memcpy(void* dst, const void* src, long long unsigned int len) {
-  Kernel::rt_copy_memory_safe(const_cast<void*>(src), dst, static_cast<Size>(len),
-                              static_cast<Size>(len));
-  return dst;
-}
-
-EXTERN_C Int32 strcmp(const char* a, const char* b) {
-  return Kernel::rt_string_cmp(a, b, rt_string_len(a));
-}
-
 }  // namespace Kernel
diff --git a/dev/kernel/src/CRuntimeOverrides.cc b/dev/kernel/src/CRuntimeOverrides.cc
new file mode 100644
index 00000000..49b1d49d
--- /dev/null
+++ b/dev/kernel/src/CRuntimeOverrides.cc
@@ -0,0 +1,27 @@
+/* -------------------------------------------
+
+  Copyright (C) 2025, Amlal El Mahrouss, licensed under the Apache 2.0 license.
+
+------------------------------------------- */
+
+#include <NeKit/Utils.h>
+
+using namespace Kernel;
+
+/// =========================================================== ///
+/// @brief C Standard Library overrides.                     ///
+/// =========================================================== ///
+
+EXTERN_C void* memset(void* dst, int c, long long unsigned int len) {
+  return Kernel::rt_set_memory_safe(dst, c, static_cast<Size>(len), static_cast<Size>(len));
+}
+
+EXTERN_C void* memcpy(void* dst, const void* src, long long unsigned int len) {
+  Kernel::rt_copy_memory_safe(const_cast<void*>(src), dst, static_cast<Size>(len),
+                              static_cast<Size>(len));
+  return dst;
+}
+
+EXTERN_C Int32 strcmp(const char* a, const char* b) {
+  return Kernel::rt_string_cmp(a, b, rt_string_len(a));
+}