Add comments to syscall components

6 files changed, 53 insertions, 12 deletions

diff --git a/arch/x86_64/include/arch/context_switching/syscall/main.hpp b/arch/x86_64/include/arch/context_switching/syscall/main.hpp
index ae4c2db..48fa195 100644
--- a/arch/x86_64/include/arch/context_switching/syscall/main.hpp
+++ b/arch/x86_64/include/arch/context_switching/syscall/main.hpp
@@ -5,28 +5,61 @@
 
 namespace teachos::arch::context_switching::syscall
 {
+  /**
+   * @brief Possible syscall implementation that should actually be called.
+   *
+   * @note Attempts to reflect the Linux interface partially. See https://filippo.io/linux-syscall-table/ for more
+   * information.
+   */
   enum class type : uint64_t
   {
-    WRITE = 1U
+    WRITE = 1U,  ///< Loads the arg_0 parameter as an address pointing to a const char array, which will then be printed
+                 ///< onto the VGA buffer screen.
   };
 
+  /**
+   * @brief Possible error codes that can be returned by the different syscall methods called depending on the type
+   * enum.
+   */
   enum class error
   {
     OK = 0U,
   };
 
+  /**
+   * @brief Allows to convert the error enum type into a boolean directly. Where any code besides 0 being no error, will
+   * return true. The remaining errors return true.
+   *
+   * @param e Error code that was returned by the syscall.
+   * @return Return true if there was no error and false otherwise.
+   */
   constexpr bool operator!(error e) { return e == error::OK; }
 
+  /**
+   * @brief Maximum amount of arguments that can be passed to a syscall. Default value is 0 and arguments are only ever
+   * used depending on the actual enum type and if the method requires thoose parameters.
+   */
   struct arguments
   {
-    uint64_t arg_0{};
-    uint64_t arg_1{};
-    uint64_t arg_2{};
-    uint64_t arg_3{};
-    uint64_t arg_4{};
-    uint64_t arg_5{};
+    uint64_t arg_0{};  ///< First optional paramter to the syscall representing the RDI register.
+    uint64_t arg_1{};  ///< Second optional paramter to the syscall representing the RSI register.
+    uint64_t arg_2{};  ///< Third optional paramter to the syscall representing the RDX register.
+    uint64_t arg_3{};  ///< Fourth optional paramter to the syscall representing the R10 register.
+    uint64_t arg_4{};  ///< Fifth optional paramter to the syscall representing the R8 register.
+    uint64_t arg_5{};  ///< Sixth optional paramter to the syscall representing the R9 register.
   };
 
+  /**
+   * @brief Calls the method associated with the given syscall number and passes the given optional arguments to it,
+   * over the RDI, RSI, RDX, R10, R8 and R9 register.
+   *
+   * @param syscall_number Syscall method that should be called. See enum values in type for possible implemented
+   * methods.
+   * @param args Optional arguments passable to the different syscall methods, called depending on the syscall_number.
+   * Not passing the required parameters to the method, will result in passing 0 instead, which might make the fail or
+   * not function correctly.
+   * @return Bool-convertable error code converting to true if the syscall failed or false if it didn't.
+   */
   auto syscall(type syscall_number, arguments args = {}) -> error;
 
 }  // namespace teachos::arch::context_switching::syscall
diff --git a/arch/x86_64/include/arch/context_switching/syscall/syscall_enable.hpp b/arch/x86_64/include/arch/context_switching/syscall/syscall_enable.hpp
index 59b97b2..8cb468a 100644
--- a/arch/x86_64/include/arch/context_switching/syscall/syscall_enable.hpp
+++ b/arch/x86_64/include/arch/context_switching/syscall/syscall_enable.hpp
@@ -3,6 +3,14 @@
 
 namespace teachos::arch::context_switching::syscall
 {
+  /**
+   * @brief Enables and sets up internal CPU registers to allow for syscall to function correctly and switch context
+   * temporarily back to the kernel level.
+   *
+   * @note Configures the Model Specific Register required by syscall (LSTAR, FMASK, STAR) with the correct values so
+   * that the syscall_handler is called and sets the System Call Extension bit on the EFER flags to allow for syscall
+   * to be used.
+   */
   auto enable_syscall() -> void;
 
 }  // namespace teachos::arch::context_switching::syscall
diff --git a/arch/x86_64/src/context_switching/syscall/main.cpp b/arch/x86_64/src/context_switching/syscall/main.cpp
index a226e23..93fc613 100644
--- a/arch/x86_64/src/context_switching/syscall/main.cpp
+++ b/arch/x86_64/src/context_switching/syscall/main.cpp
@@ -23,4 +23,4 @@ namespace teachos::arch::context_switching::syscall
     return error;
   }
 
-}  // namespace teachos::arch::context_switching::syscall
\ No newline at end of file
+}  // namespace teachos::arch::context_switching::syscall
diff --git a/arch/x86_64/src/context_switching/syscall/syscall_enable.cpp b/arch/x86_64/src/context_switching/syscall/syscall_enable.cpp
index e6265d3..3c43336 100644
--- a/arch/x86_64/src/context_switching/syscall/syscall_enable.cpp
+++ b/arch/x86_64/src/context_switching/syscall/syscall_enable.cpp
@@ -8,7 +8,7 @@ namespace teachos::arch::context_switching::syscall
 {
   namespace
   {
-    constexpr interrupt_descriptor_table::segment_selector KERNEL_CODE_SEGMENT_SELECTOR{
+    interrupt_descriptor_table::segment_selector constexpr KERNEL_CODE_SEGMENT_SELECTOR{
         1U, interrupt_descriptor_table::segment_selector::REQUEST_LEVEL_KERNEL};
 
     auto constexpr IA32_STAR_ADDRESS = 0xC0000081;
@@ -29,4 +29,4 @@ namespace teachos::arch::context_switching::syscall
 
     kernel::cpu::set_efer_bit(kernel::cpu::efer_flags::SCE);
   }
-}  // namespace teachos::arch::context_switching::syscall
\ No newline at end of file
+}  // namespace teachos::arch::context_switching::syscall
diff --git a/arch/x86_64/src/context_switching/syscall/syscall_handler.cpp b/arch/x86_64/src/context_switching/syscall/syscall_handler.cpp
index fbfecc0..da9eb1b 100644
--- a/arch/x86_64/src/context_switching/syscall/syscall_handler.cpp
+++ b/arch/x86_64/src/context_switching/syscall/syscall_handler.cpp
@@ -72,4 +72,4 @@ namespace teachos::arch::context_switching::syscall
                  "sysretq");
   }
 
-}  // namespace teachos::arch::context_switching::syscall
\ No newline at end of file
+}  // namespace teachos::arch::context_switching::syscall
diff --git a/arch/x86_64/src/user/main.cpp b/arch/x86_64/src/user/main.cpp
index 8ce21ba..1d56d2e 100644
--- a/arch/x86_64/src/user/main.cpp
+++ b/arch/x86_64/src/user/main.cpp
@@ -32,4 +32,4 @@ namespace teachos::arch::user
                               video::vga::text::common_attributes::green_on_black);
     }
   }
-}  // namespace teachos::arch::user
\ No newline at end of file
+}  // namespace teachos::arch::user